PrevDoc TranslationNext

Step by Step: The Translation of Documentation Files

In the following we assume that you are somewhat familiar with the structure and syntax of DocBook files. For further information on this format please have a look at Writing Documentation Using DocBook: A Crash Course.

Generally speaking, you should just install Lokalize and translate the PO file as already explained in the GUI section of this HOWTO. (Additionally you need the current version of the directories

  • l10n-kf5/templates/docmessages/,

  • l10n-kf5/$LANGUAGE/docmessages/,

  • l10n-kf5/$LANGUAGE/docs/

  • l10n-kf5/l10n-scripty/

  • and l10n-kf5/documentation/PACKAGE/doc/ from SVN).

Important

Since things keep changing (standards, formats, etc.) it is important to join the translators mailing list and to watch out for the announcements there.

  • If you start Lokalize for the first time it will ask you for some user information that you should supply correctly. From this information the headers of the PO files are automatically generated.

    Additionally, you should enter the path to your PO files for the Project Overview (see next item) and probably also activate Settings → Configure Lokalize the Highlight spaces at the end on the Appearance tab because otherwise you cannot see spaces at line ends.

  • First thing after you launch Lokalize you should start the Project Overview with Project → Project Overview (F4). The Project Overview shows you what documents exactly require work (fuzzies, untranslated strings and programs). For this to work you need a current copy of the directories l10n-kf5/templates/docmessages/ and l10n-kf5/$LANGUAGE/docmessages/. Also you have to enter the path to these files in the Lokalize settings.

  • If the Project Overview shows no translation for your program (i.e. there is no corresponding PO file in l10n-kf5/$LANGUAGE/docmessages/PACKAGE — and only in this case — on double click the POT file is loaded into the editor and saved with the extension PO in this same directory where this file is missing i.e. l10n-kf5/$LANGUAGE/docmessages/PACKAGE/PROGRAM.po.

    Lokalize takes automatically care of this, if you load the file from the Project Overview and save it afterwards. You just need to make sure that you put the right path names in the dialog that can be opened Project → Configure project.

    Note

    From now on you are only working with the PO file for this program. The main part of your work will be to change and keep current already translated documents (i.e. existing PO files).

  • Then you have to translate untranslated strings and check the already translated strings that are marked as "fuzzy". To simplify correction of fuzzies Lokalize provides the Original Diff panel. This panel shows new and deleted parts of the msgid highlighted. For this to work PO file keeps old msgids which can be translated using data from Lokalize database of msgstrs. As soon as you change the msgstr the "fuzzy" mark will disappear. If you decide that the msgstr is without changes correct you need to delete the "fuzzy" mark yourself by pressing Ctrl+U. This is important because a DocBook file can only be generated, if the PO file is 100% translated.

If the documentation directory of the program contains screenshots you should produce a localized (e.g. with a translated GUI) version. If your language will not have no localized screenshots, the English screenshots are displayed in the translated documentation. KSnapshot is a useful tool to produce localized screenshots, but any application is fine as long as it can produce screenshots and save them as PNG files.

To compress PNG files you can use pngnq, optipng, and the following script (just put it in the folder where you store captured images and run): 

#!/bin/sh

for i in *.png
do
     pngnq -s 1 $i && optipng ${i%.*}-nq8.png && mv -f ${i%.*}-nq8.png $i
done

Important

You should follow the screenshots rules while creating a screenshot for the documentation.

Caution

It is important to save the localized picture under the same name as the original one in the translated DocBook directory corresponding to the applications English documentation DocBook directory (not the directory of the PO file).

For more information about PO files and their translation see the respective section in the GUI chapter.