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.
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
EMAILADDRESS1<email></para>" "<para>Correction of the Translation
msgid "ROLES_OF_TRANSLATORS" msgstr "" "<othercredit " "role=\"translator\"><firstname>
EMAILADDRESS1</email></address></affiliation>" "<contrib>Translation</contrib></othercredit>" "<othercredit " "role=\"translator\"><firstname>
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:
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
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
<!-- TRANS:ROLES_OF_TRANSLATORS -->
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.
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.
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 ( → ).
There exists also the web based KDE Dictionary database with translations that you can use for your language.