Doc Translation

General Requirements for Doc Translation

The documentation and online-help for KDE programs are written now entirely in XML (eXtensible Markup Language) DocBook. Some information on DocBook formatting can be found in DocBook HOWTO by Jorge Godoy. DocBook is a widely used standard for technical documentation.

A major advantage of DocBook is the capability of the conversion from one markup to another one, for example to HTML or PostScript. If you ever happened to work with a markup language like HTML or LaTeX then DocBook will be no problem. If not, you will probably need to get at least a basic understanding of these markup languages. Further information is provided in the next sections.

The software requirements are about as follows:

You are going to need Lokalize by Nick Shaforostoff just as for GUI translation. This package can be downloaded from the same source as the other parts of KDE. Lokalize supports UTF-8 as required for the documentation and online help.
For localized screenshots, you should make yourself familiar with a program like Spectacle, KSnapshot or import (from ImageMagick package).
It is also extremely advisable to have a program around for checking the syntax of the finished doc translation. For this task, you will need the XML parser meinproc5 by Stephan Kulow. This parser is part of the kdoctools repository.
Finally you are going to need po2xml. It takes a po-file and produces from this source the complete XML document. This program belongs to the repository po2xml.

These programs are a big help in the translation process (especially when searching and correcting fuzzies and untranslated strings). They ease up the comparison between older translations, check for formal correctness and the work flow in general. And if you use this tools and give the authors feedback, they are going to improve even more.

POT and PO Files Used for Documentation

This is meant as a short overview of the peculiarities of those file formats in the process of doc translation — basically, you already know them from the part on GUI translation.

The files that have to be translated are in Unicode UTF-8 format with the extension .pot and .po. But this is only for the convenience of translators. Originally, the English documentation is included in DocBook files (see above). Once the documentation author commits a documentation to the SVN, the translatable strings from the file are extracted to a POT file and committed to l10n-kf5/templates/docmessages on the server. If there are no updated templates on the server, your translations in the <docmessage>.po will be removed by scripty's next run to the SVN. Basically, the resulting POTs do not differ too much from what you already know from the GUI files.

The English POT file is the common ground for the translation teams which produce for each POT file one PO for their language. These localized PO files provide the translated strings, from which the program po2xml produces the translated DocBook file. po2xml must be regularly run by your language coordinator or dedicated committer for your language. This can be done using one of the scripts in /l10n-scripty, namely update_xml. During compilation of your translation files (see above), this translated DocBook files are processed to obtain HTML files that will be shown on screen. The generation of the translated DocBook files by po2xml require the PO files to be syntactically correct.

You can find the English DocBook documentation in subdirectories of the source code for the corresponding package. The POT files and the translated PO files and DocBook files for all languages are located in the KDE package named kde-l10n. For the package "EXAMPLE" you will find

the POT files in the directory l10n-kf5/templates/docmessages/EXAMPLE/
the translated PO files in the directory l10n-kdf5/$LANGUAGE/docmessages/EXAMPLE/
the English documentation files in the directory l10n-kf5/documentation/EXAMPLE (you need this file to generate the translated DocBook file)
the translated documentation (in DocBook format) in the directory l10n-kf5/$LANGUAGE/docs/EXAMPLE/

To-do Lists for Doc Translation

The page for a daily documentation statistic gives an overview of the existing documentation for your language and the status.

If you have the l10n sources for your language on your computer then the Project Overview of Lokalize contains considerably more information.

Another important point is to not duplicate the work of somebody else. It may be useful to split the work so that for each package one person (and only one) is responsible. Usually, it is the job of your language coordinator to organize this part. So you should better not start to work before you have checked with your language coordinator.

There is another item to check for: Before translating you should contact the author of the English original documentation to make sure there is not going to be a major new revision in the near future. By doing this you make sure your work is not obsolete.

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]{.menuchoice} (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]{.menuchoice}.

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]{.keycombo}. 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.

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.

Peculiarities and Difficulties

First, the answers to some frequently asked questions and a piece of advice:

Line breaks have no influence on the formatting of the generated DocBook. You can insert a line break wherever you find it suitable for your needs. It is important, however, to have a space at the end of the line. For example:
```
"... volume of your"
sound card."
```
would otherwise become:
```
... volume of yoursound card.
```
Between <keyword> and </keyword> only text is allowed, for example <keyword>&kmidi;</keyword> is not valid. It has to be <keyword>kmidi</keyword> instead.

Important: The DocBook keywords (technically named "tags"), like for example <keyword> must not be translated! Even in a non-English DocBook document, the tags are in English.
The screenshots should always show the current appearance of the GUI.
One word of advice: Do not translate word for word or sentence for sentence literally. Try to translate the meaning. Read a complete section and translate it.

In addition to the role of "#" and "~" (explained above) there are a few more peculiarities:

There are two msgids which are dedicated to documentation translation. They are somewhat special in that they do not have corresponding strings in the English original documentation. These are CREDIT_FOR_TRANSLATORS and ROLES_OF_TRANSLATORS. As you probably guessed this is the place where you put in your name and your email address. It is important that these msgstrs have a special markup to make them fit into the context (You can find some background about this special msgids and possibilities to add paragraphs that do not exist in the English documentation here.) So here is an example of a document which has two different translators:

msgid "CREDIT_FOR_TRANSLATORS"
msgstr ""
"<para>Translation FIRSTNAME1 LASTNAME1 "
"<email>EMAILADDRESS1<email></para>"
"<para>Correction of the Translation FIRSTNAME2 LASTNAME2 "
"<email>EMAILADDRESS2</email></para>"

and

msgid "ROLES_OF_TRANSLATORS"
msgstr ""
"<othercredit "
"role=\"translator\"><firstname>FIRSTNAME1</firstname><surname>LASTNAME1</surname>"
"<affiliation><address><email>EMAILADDRESS1</email></address></affiliation>"
"<contrib>Translation</contrib></othercredit>"
"<othercredit "
"role=\"translator\"><firstname>FIRSTNAME2</firstname><surname>LASTNAME2</surname>"
"<affiliation><address><email>EMAILADDRESS2</email></address></affiliation>"
"<contrib>Correction of the Translation</contrib></othercredit>"

In Lokalize the quotation marks (") have a special meaning. On the other hand you need them at several places in the markup or the normal text. In such cases you have to "escape" them with a backslash. In the above example in the markup you find:
```
"...role=\"translator\"...
```
instead of
```
"... role="translator"...
```
Lokalize helps with this because if you hit the quotation mark key on the keyboard Lokalize actually inserts a backslash before the quotation mark automatically.

What else to watch out for in the translation process?

Organization and syntax:

If the documentation is missing something or is not up to date with the current GUI you should contact the author of the original documentation and ask him or her to add the missing part in the original documentation. (In case (s)he is unavailable you may also contact the documentation mailing list.) Your possibilities to differ from the original are very limited since the markup has to be consistent with the English documentation and the structure of the document must match the English version. So if you want e.g. to add one paragraph in the translation, it is best to ask the author to add that paragraph in the original. That gives you an additional msgid to translate.

For special cases there is a possibility to add paragraphs, that only exist in the translated documentation but not in the English original. However this should be used with care. Two msgids, that represent text, which does not exist in the English document are CREDIT_FOR_TRANSLATORS and ROLES_OF_TRANSLATORS. They are generated by a special comment in the English documentation. You will find the lines
```

```
and
```

```
This are XML comments and are not displayed in the English documentation. xml2pot however generates msgids for this two comments and po2xml fills the msgstrs into the translated documentation. This feature can be used to fill in more paragraphs that are only needed for the translated documentation. Every comment in the English documentation, that is of the above form leads to a msgid.

Important: You have to watch out for the correct markup, so that your translated msgstr fits into the context.
Work as closely as possible together with the GUI translator of the respective application if you cannot translate the GUI yourself (which would be advisable). Always make sure the terms in the GUI and the documentation for the same program are the same for the same elements.
For the program name you should use the entity that is defined for this program. For example the program KApp will have the entity &kapp; defined. You should always use that to make sure the name is written in a consistent way.
You should follow the screenshots rules for all screenshots for the documentation.

Style:

Each translation team should probably have some basic style guides which sets the tone of the texts, determines how to address the user and so on. The technical terms of the GUI should be translated in a consistent manner (like button, menu, tab, ...). To help with this, there is the visual dictionary in the KDE help center. So once these items are translated the terms should be used consistent by all translators of your language.
Lokalize has a translation memory. This memory collects all msgids and msgstrs you translate to make the diff feature work. It is a good idea to put the translations of all other translators into this memory as well. This is also a great help to keep consistency ([Tools > Manage translation memories]{.menuchoice}).
There exists also the web based KDE Dictionary database with translations that you can use for your language.

Checking and Committing Your Work

Checking the Markup and the Spelling

There are two items to check if you finished translating a documentation, namely spelling of the words and syntax of the XML markup.

You could use the spell checker which is built into Lokalize (Tools > Spelling...). This spell checker can be configured through the Regional & Language page of System Settings (Spelling).
To check the XML syntax you have to generate the translated XML documentation (DocBook) from the PO file. After that you can check the XML syntax of this docbook file with an XML parser. You have at least two possibilities to choose from, depending on whether you have only one documentation file or the necessary part of the whole source tree of the documentation for your language:
- If you have at least the necessary part (the part where the PO file in question resides) of the source tree of the package l10n-kf5 for your language and the doc part of the source tree of the package for the translated program (the part where the English docbook file in question resides), you could use the script update_xml (part of l10n-scripty). You also need to have po2xml in your path, as it is called by this script. The script generates the docbook files from the corresponding PO files for that language. The script takes the language to compile as first command line parameter, so if your language directory is named $LANGUAGE, you type
```
./l10n-scripty/update_xml $LANGUAGE
```
  to start the script. The script updates all files it can find in your language tree. If you only want to update a certain package or program, you can add it as second parameter to update_xml. For example, to update the German translation package kdemultimedia:
```
scripts/update_xml de kdemultimedia
```
  or the German translation application JuK:
```
scripts/update_xml de kdemultimedia juk
```
  update_xml automatically calls the XML checker checkXML5 which makes it validate the generated XML document. If the parsing process fails, it will tell you the line numbers and error messages.
  
  If checkXML5 fails then update_xml will automatically remove the file with errors. That is for safety to ensure that the DocBook files for every language compile. Sometimes this feature prevents you from finding errors, since the error messages print the corresponding line numbers in the docbook file and you are not able to check the context because this file is automatically deleted. Therefore the option --nodelete was added by Stephan. But keep in mind not to check this file with errors into the SVN tree or else your language will fail to compile until this file is removed or corrected.
- If you do not have the above requirements you may call po2xml yourself and generate the docbook file. For this to work po2xml needs the English docbook file (usually located in the doc/ subdirectory of the package containing the program with the name index.docbook) and the translated PO file. The syntax is: po2xml english.docbook translated.po >translated.docbook This generates the translated.docbook file.
  
  In the header of the generated file you have to specify your language, i.e. if your language was "German" change the line
```
<!ENTITY % English "INCLUDE" >
```
  like this:
```
<!ENTITY % German "INCLUDE"  >
```
  Now that you generated the docbook file for your language you can check that the syntax is correct and all used entities (i.e. &kapp; etc.) can be resolved correctly.
  
  Important: It is not enough that the docbook file can be displayed more or less correctly by the KDE help center, because the parser there is optimized for speed and does not check the correctness of the XML document. It is very generous in ignoring markup errors and the like.
  
  Instead use the XML parser meinproc5 from Stephan Kulow. The calling syntax is meinproc5 --check translated.docbook If the parsing process fails it will tell you the line numbers and error messages. You can use this application for generating HTML files, too. Just call meinproc5 translated.docbook and you will find a bunch of HTML files in the current directory. The file index.html is the starting point for browsing the documentation.
Error correction: Keep in mind that you need to correct the errors in the PO file, because the docbook file is autogenerated from this. Start corrections from the beginning of the document, because one error may result in a chain of subsequent errors.

If you get errors about some file "dtd/kdedbx45.dtd" that could not be found, check that the needed version of meinproc5 is called. (If you realize that your self-compiled KDE is missing a new meinproc, check the BZip2 library and recompile kdoctools.)

As for proof-reading: Each language team needs to have a certain procedure for error checking. In the German team for instance we decided on proof-reading the documentation by a different team member because the translator tends to overlook the own spelling errors.

Generating HTML files: The program meinproc5 not only checks the syntax but additionally generates HTML files in the directory of the corresponding docbook file.

What to Do with Translated and Corrected Documentation?

Usually, the coordinator for you language will take care of proof-reading and afterwards committing the translated files to SVN. So please check with him or her about the team policy in this regard.

You should always keep in mind that once your documentation is published on the KDE web server, it will be distributed worldwide and may be read by millions of people. So your translation will substantially influence how users experience KDE.

Article contributed by Yuri Chornoivan, Nicolas Goutte, and 1999-2002 Thomas Diehl thd@kde.org under the GFDL-1.2-or-later license.