User Tools

Site Tools


Translating the Kalkules manual

Translating the Kalkules manual is a little bit harder than translating the program, because you will have to edit an html file. It is an advantage if you know at least the basic structure of html files, but if you don't, you can still translate the manual file, but you will have to be more careful about what you are doing.

The Kalkules manual file is located on the following path: [Kalkules folder]\manual\[language code]\manual.html

For instance: If you've installed Kalkules into C:\Program Files, then the English manual file is located at C:\Program Files\Kalkules\manual\en\manual.html

If you want to learn html, check out the W3Schools html tutorial. Html is really easy to learn, and if you learn it, you will be able to create your own simple websites :)

Basic steps

  1. Create a copy of the manual translation (manual.html), which you want to translate into your language. (most likely you will be translating the English version)
  2. Translate the texts in manual.html
  3. Optionally create screenshots of the translated program windows for the manual
  4. Check the manual.html file for html validity errors
  5. Send all the translated files to the author

Creating a copy of manual.html

For demonstration purposes, let's say that we are creating a Slovak translation of the manual based on the English version.

  1. Open the manual folder ([Kalkules folder]\manual\) and create a new folder for your translation. The folder name should be a two character iso code of your language. In our example, we create a folder named sk. If you don't know the iso code of your language, check out the table of language iso codes.
  2. Open the en folder, and copy the manual.html file into your newly created folder (sk).
  3. Also copy the whole img folder

Translating manual.html

To translate the manual file, use a plain text editor such as PS Pad, Notepad ++, or in the worst case Note Pad. Do not use rich text editors such as MS Word, Open Office Writter nor any WYSIWYG website editors, because they will completely mess up the html code and it's very hard to fix it afterwards.

Open manual.html in your plain text editor and translate only the English texts. Do not change nor delete any of the html tags. Html tags are the texts surrounded by < >. For example:

English translation:

  <h1 id="content">Kalkules program manual</h1>
  <h3>Basic information</h3>
    <li>Kalkules homepage: <a href=""></a>
    <li>You can download the latest version of Kalkules <a href="">here</a>.
    <li>If you have any questions or suggestions on how to make the program better, you can use this <a href="">contact</a>.

Slovak translation:

  <h1 id="content">Návod k programu Kalkules</h1>
  <h3>Základné informácie</h3>
    <li>Domovská stránka programu Kalkules: <a href=""></a>
    <li>Najnovšiu verziu programu si môžete <a href="">stiahnuť tu</a>.
    <li>Vaše otázky ohľadne programu, návrhy na vylepšenia a&nbsp;odhalené chyby píšte na tento <a href="">kontakt</a>.

Creating screenshots

Creating screenshots is easy. You do not need to use any special software. All you need are standard tools available on any Windows computer. The simplest way to create screenshots is:

  1. Open Kalkules and switch the language into yours
  2. Open the window which you wish to make the screenshot of (make sure the window is active - has focus)
  3. Press [alt]+[Prn scr] on your keyboard
  4. Open MS Paint, and press [ctr]+[c] or select Edit/Paste
  5. Overwrite the English screenshot with your new screenshot. Select File/Save as, open your manuals image directory (For instance manual\sk\img) and select the file you wish to overwrite.

Remember that all the translated screenshot files must have exactly the same name as the original files. Otherwise they will not be displayed correctly in the manual.

To get better image quality:

  • Do not use any special tools to make screenshots. These tools often try to enlarge or modify the windows in some way, and the resulting screenshots don't look good. Just use [alt]+[Prn scr] as described above.
  • Make the screenshots in scale 1:1. Do not enlarge nor shrink them.
  • Most Windows systems (Windows XP, Vista, 7) display the program windows with rounded corners. When you make the screenshot, the rounded corners are filled with whatever was on your monitor when you were making the screenshot, which doesn't look good. To prevent this, always make sure that you have a plain white background behind the window when you are making the screenshot. If you have enough skills, the best way is to make the screenshot background transparent. Unfortunately, this cannot be done in MS Paint. You will have to use a more advanced tool like GIMP.

Checking manual.html for validity errors

To ensure the best quality of the manual, we have to make sure that its html code is valid. All the manual files provided with Kalkules have a valid html code, so when you copied and translated one of these files, you also should get a valid html code. However, there is a possibility that during the translation process, you accidentally modified some html tags. Therefore you should check your manual file for validity errors.

To check your manual file:

  1. Upload your manual.html file and click Check
  2. If the validation has passed, your translation is valid. Well done :)
  3. If the validation hasn't passed, the validator will display all the errors with the exact line number of each error. The validator also displays a hint of what could be wrong. Try to edit your file and fix as many errors as you can. Then try to revalidate the file.

If you think you won't be able to check the validity, or you don't know how to fix some errors, don't worry. Just send your translation file anyway and I will do it for you. Just make sure you at least tried, because this saves me a lot of time, so I can focus on improving Kalkules :)

Sending the translated files

Pack your whole manual folder (for instance manual\sk) into a single zip file and send it via email to [email protected], or use the Kalkules website contact form. Your translation will probably be included in the next released version of Kalkules.

Now every one in your country can enjoy a fully translated Kalkules manual :) Well done and thank you for your contribution.

See also

translations/translating_the_manual.txt · Last modified: 2013/02/23 22:18 by admin