]> Thomas Diehl Nicolas Goutte Frank Schütte Rewrite of the doc-translation part Arash Zeini Update of the GUI-translation part 1999-2002 Thomas Diehl 2005 Nicolas Goutte 2005-12-19 2.00.19 This translators' HOWTO is meant for translation team coordinators, new translators, and everybody else interested in the subject of translating KDE. It gives a first overview of how new languages are introduced to KDE, and how the translations of the graphic user interface, the on-line help, and other KDE-related things are actually done. It also takes a closer look at resources available to assist translators in the process. Other important areas (e.g. how to compile KDE sources or how to find one's way around SVN) are referenced throughout. A current HTML version of this document can be found at l10n.kde.org/translation-howto. You can download the file in various formats. Have a look at http://l10n.kde.org/sitedoc.html. To contribute, comment, or correct, please send email to kde-i18n-doc mailing list. KDE translation HOWTO I18N internationalization L10N localization Parts of this document are currently in an inconsistent state, as the document is in the process of being renewed, especially due to using SVN instead of CVS as version control system, due to the new l10n module, due to the change of servers, due to new file names or due to new habits. If you are not sure about how to interpret what is written here, please ask the kde-i18n-doc mailing list. In this document are a few email addresses from persons, not only from mailing lists. Most of these persons, if not all, are volunteers, and therefore might not be able to answer within a day (even less in near real-time). If you do not get any answer for days (at most a week), please ask the kde-i18n-doc@kde.org mailing list instead. (If you had attached an attachment in your original email, please do not send this attachment to the mailing list.) As stated in the abstract, this HOWTO is meant for everybody interested in KDE translation. It is not taken for granted that such people are at the same time developers, "geeks", or that they know the ins and outs of all this stuff anyway and just want to check if others are as smart as they are. ;-) On the contrary, translation can be one of the fields for non-programmers and non-techs to contribute to the KDE project if they would like to. Areas covered are the introduction of new languages to KDE, the resources available, translation of the graphic user interface (GUI) and of the documentation (which provides the bulk of the on-line help). The translation of the KDE web sites, handling of bug reports and user feedback are described to some extent. Also a few issues of KDE "localization" are touched upon to the extent as it actually concerns team coordinators. We do not try to define exactly what is meant by the terms "i18n" (short for "internationalization") or "l10n" (short for "localization"), much less to stick to such definitions throughout the document, especially that those two terms were used wrongly in KDE for a long time. In theory "i18n" means to prepare code to allow it to be internationalized, i.e. to be translated, to show correct date forms, to write in the correct text direction and other such important stuff for the user. In theory "l10n" means the data for a specific country or language (translations, flags, date format, etc.) In KDE, "l10n" was more country-related, while "i18n" was more language-related. This wrong use of the terms have been fixed in the meanwhile, but it may still be present in one or another KDE document or name (e.g. the name of the kde-i18n-doc mailing list). (For a short explanation of the original meaning and the development side of both terms take a look at developer.kde.org/documentation/library/kdeqt/kde3arch/kde-i18n-howto.html.) This HOWTO is mostly a "quick start" type of document and can, therefore, only serve as an initial overview of what is required for practical translation work. It cannot provide a thorough explanation of areas as complex as, for instance, Unicode or the inner workings of DocBook as used in KDE documentation. There are extra teams providing extra information on these areas. With regard to the DocBook example, this would be the documentation team that works closely together with the translation team and is sharing the same mailing list for subjects of general interest, namely kde-i18n-doc@kde.org. For things related to documentation writing there is another list: kde-doc-english@kde.org. Since I have been asked about this: Everyone who feels like it, is invited to translate this document for the use of an individual language team. Please feel free to replace the German translation examples with your own ones and to add whatever you think could be useful for your team or to skip what does not make sense in your context. But since all things KDE are changing rapidly, please always make sure that you are using the latest DocBook source of the HOWTO for such translations. Major revisions will be announced on the translators' and documenters' mailing list at kde-i18n-doc@kde.org. Also probably, issues and errata about this document will appear there before being incorporated into this document. This document is more written for somebody wanting to become the coordinator of a new language in KDE. If your goal is simply knowing how to translate in KDE, the document will be more tedious to read and to use, unfortunately, even if it is currently probably the best document to know how to translate for KDE. Having said all that, constructive feedback or contributions are highly welcome, of course. Send an email to kde-i18n-doc@kde.org and tell what you would like to see in here. Before doing anything else, get on the mailing list for translators and documenters (either via the web page or by sending a mail with "subscribe" in the subject and the body to kde-i18n-doc-request@kde.org). This mailing list is being archived with the others at lists.kde.org. (See the corresponding part of the appendix for more details.) Second: Take a look at the list of languages and coordinators in KDE. What follows depends on whether your language is listed on that page or not. If your language is listed, simply write to the coordinator(s) of your language team and ask him, her, or them how to proceed. If your language is not listed, post a message to the kde-i18n-doc mailing list asking if anybody is already working on your language or would be willing to join your effort. It might happen that you do not get an answer from your message on kde-i18n-doc mailing list because nobody is working on your prefered language. Do not worry! First as this is an international mailing list and as most people are volunteers you will probably not get an immediate answer anyway. So please wait at least 24 hours. Especially do not re-send the same message within hours. (Sometimes the mailing list distribution is stalling and in extreme cases it can be for hours.) If after a few days (at most a week), you have not got any answer, then it means that there is currently nobody interested to work on your prefered language. In that case, you can start translating. It would be nice to send a message to tell that you are starting, to avoid thinking that you have abandonned because you have not get any co-worker. When you start a new translation, you can be added to the language team page. Please contact Claudiu Costin to do so. Read this Translation HOWTO entirely, especially the section on GUI translation in KDE. Find out how to install KDE and then just do it. Although you can theoretically do your translation work for KDE under an older version than the one the translation is meant for, it is better and recommended to have the needed version on your computer for at least testing purposes. Check out the HOWTO section for assisting documentation on this subject. Make sure you have the GNU gettext package installed and start to get familiar with it. At least have a good look at its Info pages. (Remember: the KDE on-line help provides a very convenient way to read this kind of documentation.) Take a closer look at the programs, scripts and statistical aids which will help you with translation. You will need programs and tools that can handle the UTF-8 encoding, at least for the GUI translation. The recommended tool for making translation is KBabel. Finally, make yourself familiar with SVN (if you are going to be a team coordinator), with anonymous SVN (if you are just translating). In case you have never heard of SVN (in full: Subversion): it is a version control system for directories and files. In the case of KDE (as for many other open source projects), it is used so that files and directories may be created, modified and removed by different users over the Internet. In KDE, the name "SVN" or "KDE SVN" primarily refers to a server called "svn.kde.org" where all the source code for KDE programs, the documentation, the translations and about all other needed data for KDE are stored. People with a SVN account have a local client setup on their own computer corresponding to this SVN server which mirrors the source tree on the remote machine. This local SVN client also allows them to merge e.g. new translations back into the remote source tree system. In order to get an account you have to send a request, along with a user name and an encrypted password to KDE Sysadmin. Please see the tutorial for how exactly to do it correctly. As a rule, there should be only one (personal) account per translation team. But, of course, it can be more than one if your team needs them. If you do not know SVN, or if you do not know it well, probably you want to read the handbook about SVN, which is available online: Version Control with Subversion, it might be part of the documentation of SVN packages that you have or are going to install on your system. (The book is also available as "hardcopy" in bookshops). Of course, as you will only use SVN and as you plan neither to program nor to administer SVN, you do not need to read and understand all chapters of the book. If you know CVS, for example because you have used it for another open source project, you might find another documentation also useful: CVS to SVN Crossover Guide. (It is part of the SVN documentation too.) The main commands of the svn client are: svn checkout (for getting something from the remote system to your local repository), svn update (if you just want to refresh already existing stuff on your local system), svn add (to add new files and directories as being), svn remove (to remove new files and directories as being), svn copy (to copy files), svn move (to move files) and last but not least: svn commit (to "register" your work back in the remote system. This is a process named "committing"). At the time of writing this paragraph of this documentation, there are not many dedicated graphical SVN front-ends for KDE. KBabel's catalog manager has support for it (from KDE 3.5 on). Other graphical front-ends are kdesvn and eSVN. There is also the svn: KIO slave (part of the kdesdk module), which gives some SVN functionality, for example in Konqueror and KDevelop. (As for Cervisia, only a special un-released development version offers SVN support.) Start your translation with the graphic user interface (GUI), preferably using KBabel set to "UTF-8" (8bit Unicode Transfer Format). First translate the file kdelibs.pot because its contents are spread over most KDE applications, providing the text of their standard menus. Continue with desktop_kdelibs.pot and desktop_l10n.pot which are responsible for the stuff in the K menu. Then go to the applications in kdebase. You will find a thorough explanation of how to do this in the section on GUI translation. But it will not hurt to see the important steps being listed here as well: Download kdelibs.pot, the template file for all translations of kdelibs. (You can do this for example using WebSVN and download the latest revision.) Save this file as kdelibs.po to a local directory on your computer. (All translated GUI files end in ".po" whereas the originals end in ".pot" which means ".po template".) Start translating. (Taking a look at the GUI section of this HOWTO and at the work of other translators could be useful now and then.) When you are finished with kdelibs.po, test your work with msgfmt --statistics --check-header kdelibs.po. Most of the above things (from correct transformation of .pot to .po files to the syntax check) are done automatically by KBabel. Since it also handles Unicode while many text editors do not it is now the recommended tool for KDE GUI translation. Apart from the fact that in recent versions it has probably more useful features than any other free translation program in this area. When you are ready to send your first files, write a short email to the kde-i18n-doc mailing list without attaching the files. Somebody will answer that you can send him the files, so that he can process them. This person will create a new directory for your language (l10n/$LANG/). This person will also create subdirectories for PO files (and, if already necessary, for documentation) and commit your first translation to the KDE code via SVN). After this, committing the translations, creating new directories and so on will be your own responsibility (i.e. the responsibility of the language team coordinator). After your language is in KDE SVN, you should probably ask the kde-i18n-doc mailing list how to procede for being listed on the team page (if you are not listed yet) and how to create a "component" for your language in KDE Bugs, KDE's bug database. Furthermore you need to check if an entry.desktop file to l10n/$LANG/messages/ has been created by the person having made the first commit of the new language. If the file is still missing, you will have to create it. This entry.desktop needs only to contain the following two lines: [KCM Locale] Name=Add_here_the_name_of_your_language_in_American_English The syntax of the language code in KDE is nearly like the one described in RFC 3066, especially section 2.3, except that KDE uses a underscore character (_) rather than a dash (-) (e.g. KDE uses en_GB for British English while RFC 3066 would use en-GB). Most often using RFC 3066 means using the 2 letter code for languages from ISO 639-1, e.g. de for German, fr for French. (See Wikipedia's article about ISO 639.) In the rare case that your language would not have a code according to RFC 3066, e.g. if your language is a small regional language, you are recommend to register it at IANA according to the procedure described in RFC 3066, especially section 3. If for any reason, you do not want to register your language at IANA, you must use a language name staring with x- (the letter x and a dash). Gather a team of co-translators (if you have not already), distribute the tasks and start building an effective "infrastructure" for your work. First of all make up a mailing list and a web site for internal use by your language team. You can get both from KDE although it will be somewhat basic stuff. (The list server will not accept many commands and the web site does not allow CGI yet.) Anyway, if you are interested, contact the webmaster of the i18n-server. After organizing these things, you may want to take a look now and then into the "practical hints" section of this HOWTO. If GUI translation is well under way and everything else in your team seems pretty much organized, you should start documentation translation. You will find the basic information on the documentation site of the i18n server. This HOWTO only provides a short overview to let you know where the journey will be going. An overview of the progress GUI translation teams are making is provided on the Status table of KDE Translations for the trunk branch. Based on its data the decision is made which languages will be part of a KDE release and which will be not. The official rule for release versions says around 90% of kdelibs.pot, 100% of desktop_kdelibs.pot and desktop_l10n.pot and around 75% of kdebase should be translated in order to get into a release. (See the Essential Statistic.) But, usually, it is up to the team coordinators to decide when their language is "ready for release" and to report it as such to the people in charge of the release. There are a few things that are not directly related to translation but are usually done by the translation team coordinators. The most important one is taking care of basic "localization" issues, if the new language at the same time represents a new country. In this case, it is appreciated if you can provide KDE with information about the currency used in that country, formats of date, time, numbers, and addresses, the flag and a few other settings. This info is stored in the "l10n" directories of the kdebase package and is used all over KDE but especially in the desktop section of the Control Center. Again: This stuff is country related, not language related. So if your language is not the "official" language of your country you probably do not have to worry about this. Even if your language is not an official language of a country, it might be related to one country, or perhaps to a few of them. It would be nice if you could check existing country entries for these countries and eventually add missing entries. This is especially important if the official language of a country is a wide-spread language like French or British English, where the corresponding translator teams have no idea of the habits of the country. Of course, if a country shares a few languages, it would be preferable that the different translator teams agree on the entry for that country. Unfortunately, if in a country, different users use different settings depending of the language, this cannot be correctly reflected in KDE. This is especially important for countries like Switzerland or Belgium, where you cannot express "P.O. Box" in the correct translated spelling for each language region. If really needed, KDE can be hacked, but then the setting for the country becomes language dependant, which is still not completely correct. (E.g. a letter to a P.O. box to Geneva, in the French-speaking part of Switzerland, should always have "Case Postale", while to Zurich in the German-speaking part of Switzerland, it should be "Postfach".) The directories in kdebase/l10n are for countries, not for languages, so the codes have a different meaning (even if for example the French language and the country France share a same code: fr). The codes for countries are specified in ISO 3166 (see Wikipedia's article about ISO 3166's two letter code.). In order to localize KDE to the needs of your country, you have to do the following: Checkout the kdebase/l10n directory from svn.kde.org and then go to kdebase/l10n svn mkdir xx (Remember: xx stands for a country code, not for a language). cd xx cp /path/to/my_entry.desktop entry.desktop (This is necessary, otherwise, the flag picture will not be used.) cp /path/to/my_flag.png flag.png cd .. svn add xx/entry.desktop xx/flag.png svn commit xx For more info see the README in the kdebase l10n directory. The man in charge for "l10n" (i.e. localization) in KDE is Hans Petter Bieker. This section is a collection of hints and tips that proved helpful in real world translation, team work, building an infrastructure and so on for several language teams. For the most part, it is up to you if you want to make use of these recommendations. Many things in this section have to do with "consistency" in one way or another. This is a main consideration for a desktop system that is trying to keep its look and feel as unified as possible. Similarly, all programs should use the same translation terms in GUI and doc translation. At the same time, achieving this kind of consistency is one of the biggest challenges for writers and translators in projects like KDE. As always: if you think something should be mentioned in this section but you cannot find it yet, please ask the kde-i18n-doc mailing list. (Even better: send a patch against the DocBook version of this document.) Do not work in isolation. Be as responsive as possible to your team and to the rest of KDE. If you know that you will not be reachable for a while please let others know via your team site or your team mailing list. If you do not have enough time for coordination any more please find another coordinator or a co-coordinator. Do not cling to the "title". Your work will usually only succeed as a team effort. Just as KDE as a whole. If your team has more than one coordinator it is often a good idea to let people know who is mainly responsible for which areas (for examples: PO files, docs, web site, user feedback, bug reports) or who is generally the main contact. And please: if there are struggles and discussions inside your team about organizational questions, keep them internal. The i18n coordinator does not know enough about individual team problems to work as a referee here. "Do not work in isolation" also means: Talk to your co-translators about what your translation should look like and what your target groups are. If your translation is for "ordinary users", including business people, it will look very different from a translation that is made for computer specialists. (Normally, KDE is not considered to be something that is "made only for geeks".) In any case: try to develop a style guide for your team. Find standard translations for standard elements and stick to them. The archived PO translations (also known as "compendium files") at l10n.kde.org/po_overview will be very helpful in this respect, as will specialized translation programs like KBabel that either allow you to search these files or provide comparable means to help you with consistency checking. Also make good use of word lists and dictionaries, of web fora and mailing lists. A very interesting tool for maintaining such word lists is kdedict by Matthias Kiefer. Develop a system of "mutual proofreading" to make sure that everybody involved sticks to the rules. This can be somewhat delicate at times (so do not be too argumentative;), but since this also provides your best means of correcting spelling mistakes and stupid errors you will have to set up such a mechanism anyway, at least in the long run. It may be a good idea to have the same person do the GUI translation and the translation of the on-line help (i.e. the documentation) of a given program. If this is not possible, the person who does the final proofreading of the documentation, the screenshots and so on should be allowed to make corrections to the PO files as well, ensuring that GUI and on-line help are "speaking the same language". It is extremely confusing to the users if the terms in the documentation are different from the terms in the actual menus of the same program. Never commit a file to SVN without doing appropriate syntax checks as pointed out in the respective sections on GUI and doc translation. Again, the use of specialized programs (like KBabel for POs of the &GUI; and Doc Translation) is highly recommended since they provide mechanisms for syntax and other checks. Most people in free software do very good work without any payment. Nevertheless, they would like to see some acknowledgment of that work. In KDE translation your work can be acknowledged in the following ways: On the KDE credits page In the Help->About box of the translated program In the "credits" section of translated documentation With regard to the credits page: The names are getting there via a script which picks up the contents for the HTML page from a file in the www module of SVN (trunk/www/sites/www/people/credits/index.php). So do not change the HTML page but the index.php file. — Entering the translators' names is the job of the respective language coordinator. With regard to the "About" box in the help menu: The name(s) and email address(es) of translators are getting there by filling in the following strings in the respective PO file: #: _translatorinfo.cpp:1 msgid "" "_: NAME OF TRANSLATORS\n" "Your names" msgstr "" #: _translatorinfo.cpp:3 msgid "" "_: EMAIL OF TRANSLATORS\n" "Your emails" msgstr "" If there is more than one translator make up a comma separated list without spaces (translator1,translator2,translator3). Same goes for the mail addresses. If you do not know an address leave the field empty (address1,,address3). It then would look as follows: #: _translatorinfo.cpp:1 msgid "" "_: NAME OF TRANSLATORS\n" "Your names" msgstr "Translator One,Translator Two,Translator Three" #: _translatorinfo.cpp:3 msgid "" "_: EMAIL OF TRANSLATORS\n" "Your emails" msgstr "translator.one@some.domain,,translator.three@another.domain" For info on the credit section of translated documentation please see the respective step-by-step instruction. This chapter deals with the translation of the graphic user interface (GUI) of KDE and its applications. For background information on what is actually translated here (i.e. the .pot and the .po files) please read the gettext Info pages. (Remember: the KDE on-line help provides a very convenient way to read this kind of documentation). — Special thanks to Christopher Kuhi for creating the first version of this section from the German original. To provide a template for translations, the English menu and dialog texts of a program are stored in text files with the extension .pot (short for "PO Template" like .po stands for "Portable Object".) To see examples of how POTs and POs look you may want to pay a visit to WebSVN after reading the following topographic information about the directory structure. (The best is perhaps to start with the British English translations of kdelibs on WebSVN.) From the standard templates or "POT files" translation teams produce the PO files for their respective language -- simply by loading anyfile.pot to a text editor or one of the specialized PO programs and saving it as anyfile.po to another directory. After translating the strings inside the file, these POs will contain the menu and dialog texts for a given program if users choose, for example, "German" or "Icelandic" as the standard language. To be exact, there is another intermediate step which make MOs ("Machine Objects") from the POs during compilation. But this is something which translators do not generally need to worry about. At least, not as long as their POs are in the correct format; see below under the heading Checking and Committing Your Work. The English POs, as well as all the original documentation can be found in the subfolders of each program package. The POT files and all translations can be found in a separate KDE folder called l10n and represent their own package. Included are: the POT files in the folder l10n/templates/ the language-specific PO files in the folder l10n/$LANG/messages/(package-name)/, (e.g. l10n/de/messages/kdebase/konqueror.po for a German file) the language-specific documentation in the folder l10n/$LANG/docs/(package-name)/(appfolder)/index.docbook, (e.g. l10n/de/docs/kdeutils/kdiff/index.docbook) ($LANG is short for language codes like "de", "fr", "ru", etc. As already mentioned, these abbreviations are nearly code from RFC 3066. There are mainly two ways to find out which programs have not been translated yet: Try to figure it out from the KDE internationalization status table. Compare the POT files with the POs for the particular language. In other words: If there are no PO files for a particular program under "l10n/$LANG/messages/(package-name)" then the chances are pretty good that the program has not been translated yet. (This comparison is done automatically by the "Catalog Manager" of KBabel, by the way.) However, before translators jump right in, it is probably a good idea to ask their team coordinator whether a program is not being worked on by someone else and to make sure that the program is not being rewritten or replaced by another one. To-do lists for your team and a system of "package maintainers" (people who are responsible for the translation of whole KDE packages like kdeutils, kdemultimedia etc.) can also often be a big help in avoiding duplicate work. KDE programs are constantly improved. The downside to this rapid development is that almost all GUI texts are constantly changing and the translations are just as constantly in need of revisions. To find out which already-translated programs need a revision, either SVN update your working directory or refer to KDE's GUI messages translation statistics. The above mentioned statistics page organizes the information at three levels: SVN branch, translation team and package. At the package level you will find detailed information about the amount of fuzzies in each .po file. The .po files with fuzzies are the ones in need of a revision. "Fuzzy" is like a kind of question mark for the translations. These are sections which have been marked by an automatic checking routine (in msgmerge) as "suspicious" which means something to the effect of: "Please check this translation again because the original has changed". An overview of how the language teams are doing is provided on the Translation statistics by team for trunk branch. Based on the data on essential packages the decision is made which languages will be part of a KDE release and which are not. (Normally, around 90% of kdelibs.pot, 100% of desktop_kdelibs.pot and desktop_l10n.pot and around 75% of kdebase should be translated in order to get into a release.) General material on the subject can be found in the Info pages for the Gettext package. For a basic understanding of what is expected in KDE translation it follows a description of how the handling of POTs and POs looked like before it was done with specialized programs like KBabel: If there is no translation for a given program (i.e. there are no PO files with the same name in the appropriate folder "l10n/$LANG/messages/(package-name)/") — and only if this is the case! — then a POT file is loaded into an text editor and saved with the ".po" ending in the folder where it was missing. This results in a file with a name like "l10n/$LANG/messages/(package-name)/(program-name).po". For instance: if you are sure that Kate was not translated to your language yet, you load the recent l10n/templates/messages/kdebase/kate.pot and save it as l10n/$LANG/messages/kdebase/kate.po . Then you can start translating. From now on you do all your work for the given program with the PO file. Most of the work consists of updating, improving, and unifying earlier translations (i.e. POs which are already there). After you have filled out (or updated) the header (who, when, etc. as well as deleting the first "fuzzy" tag, see below) you fill in the empty strings with new translations. In POs that were already translated at an earlier time you check the "fuzzy" translations and correct them if necessary. Either way, remove the "fuzzy" tag at the beginning of the line after you finished working on it. Nowadays, most of these steps are done automatically by specialized programs like KBabel — from choosing the POT files and saving them as POs, through header updates and removing fuzzy entries to syntax checks. A sample header could look like this: msgid "" msgstr "" "Project-Id-Version: Some Program\n" "POT-Creation-Date: 2005-08-23 02:43+0200\n" "PO-Revision-Date: 2005-08-28 12:25+0200\n" "Last-Translator: Somebody <null@kde.org>\n" "Language-Team: Some Language <kde-i18n-doc@kde.org>\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "X-Generator: KBabel 1.11\n" "Plural-Forms: nplurals=2; plural=(n != 1);\n" If you are working with a text editor do not remove the initial "msgid / msgstr". Otherwise, the compilation will terminate with a parse error. On the other hand, you should remove the "fuzzy" which is initially there. The entries for Content-Type and the Transfer-Encoding are not relevant at the moment. But the charset should be set to UTF-8 in this case, i.e. 8bit Unicode Transfer Format. The actual translation would look as follows. The original line: #: kedit.cpp:90 kedit.cpp:1071 msgid "Show &Status Bar" msgstr "" ...you would translate like this (assuming you were translating it to German): #: kedit.cpp:90 kedit.cpp:1071 msgid "Show &Status Bar" msgstr "&Statusleiste anzeigen" And from the incorrect: #: ReniceDlg.cpp:31 #, fuzzy msgid "Renice Process" msgstr "Laufende Prozesse" ...you would produce the correct translation: #: ReniceDlg.cpp:31 msgid "Renice Process" msgstr "Neue Prozessprioritaet" After the corrections have been done you need to delete the "fuzzy" tag. Otherwise, the corrected string will just be ignored during compilation. Finally there might be lines at the end of the file beginning with "#~" like this: #~ msgid "Where do you want to go tomorrow?" #~ msgstr "Where do you want to go tomorrow?" #~ msgid "No comment available" #~ msgstr "Keine Erklärung verfügbar" These lines have been commented out, usually because they are no longer used by the program and should be deleted from time to time in the interest of disk space and bandwidth. Once more, KBabel, for instance, does this automatically. For any other questions on this topic you are once more advised to look at the Info pages for the GNU gettext package (see the KDE on-line help). This document is missing a discussion about the KDE-specific handling of plural, which differs from the standard Gettext way of handling plurals. For information on the latter you still have to refer to the respective threads in the translators mailing list, mainly plural handling and plural handling again. We already mentioned that the characters "#" and "~" have special meaning. A few other things to watch out for are the following: The "&" character in one of the examples above is used to mark an "accelerator key", ie a letter which in combination with Alt (on PC keyboards) will execute the command; i.e. Alt + S for "Show &Status Bar". You have to make sure that the same letter is not marked twice within one menu. See Compilation, Context and Accelerator Checks. Some PO files contain so-called "context information" to let translators know whether, for instance, "home" means the user directory, a key on the keyboard or the beginning of a line. Such context information always begins with the letter combination "_:". The important thing is: These strings must not show up in the translations. In other words: Do not translate or copy this stuff into the "msgstr" part of the PO file. If you do, your whole file will not work anymore. The same as above applies to "_n:", which denotes strings handling plural cases. You do not need to translate "_n:". For the correct handling see the following example: #: kdeui/kstdaction.cpp:669 msgid "" "_: beginning (of line)\n" "&Home" msgstr "&Dateianfang" #: src/kernel/qaccel.cpp:562 msgid "" "_: QAccel\n" "Home" msgstr "Pos1" Special characters such as quotes must be "escaped" (i.e. preceded with a backslash), if you want to use them as part of the text (see example below). Unescaped quotes will be interpreted by the programs which read the file as the end of the "msgstr". The test routine msgfmt --statistics --check-header, described below, would terminate at this point with an error. The syntax highlighting and the check routines in KBabel will help you with the handling of these special characters. #: cardmaps.cpp:105 #, c-format msgid "kpat: PANIC, cannot load card pixmap \"%1\"\n" msgstr "KPat: schwerer Fehler, kann Kartenbild \"%1\" nicht laden\n" One problem which languages with longer than average words (German, for example, is notorious here) sometimes encounter is dialog boxes which are too small, cutting off or cramming together translated text. This is one of the things that can only be determined for sure by checking the translations in the compiled program. The obvious, but always temporary, solution is to "keep it short." You would basically do this if there were no more time to pursue the proper solution, namely contacting the author of the program so that he/she can adjust the geometry of the offending boxes. In any case, an email describing the problem should be sent to the author or even better create a new bug report in KDE Bugs. Sometimes English text appears in the program interface even though the PO file has been completely translated, and the text in question cannot even be found there. One way this can happen is when the text comes from "somewhere else" (often from kdelibs which can be found throughout the KDE interface, sometimes from separate modules of the same program that have extra POs). Another possibility is that this particular text has not been made "i18n conform" by the author. Any strings which should be seen by the user are supposed to be passed to the C++ function QString i18n(const char *text). This ensures that the properly localized version of a string is shown (assuming there is a translation). Thus, it is only possible to translate texts which have been prepared in this manner. In cases where the untranslated text cannot be found in the PO file the author may have forgotten to do this. If you want to know for sure, you need to look in the source to the program; for example, you can find out the filename and line number by using grep -n "text in question" *.cpp in the source code folder. Anyway, if you discover such a case, please file a bug at bugs.kde.org or write the author of the program. Do not just leave the problem unmentioned. There are several packages to assist you with practical GUI translation. They automatically search fuzzy or untranslated strings, present you with possible or comparable translations for a given string, and perform syntax, spell and other checks to ensure that the files will work correctly. At the moment, KBabel is the only one that can really be recommended, however, especially since it is the only one that handles Unicode encoded files without problems. Developed by Matthias Kiefer and maintained by Stanislav Visnovsky. The recommended package for GUI translation for the time being. As of version 1.0 its contents and capabilities can be described as follows: General Features: User friendly, easy to understand and widely configurable user interface, fully KDE2/3 conform. Every part of KBabel comes with extensive context ("What's this") help that make every function easy to understand and to handle. Adds capability to Konqueror and KDE file dialogs to preview PO files and show their properties. PO-File Editor: Capability to open multiple files (or multiple views of the same file) Full editing functionality, accessible through the graphic user interface as well as through user definable keyboard shortcuts Powerful spell checking functionality Capability to show diffs to older messages Full navigation capabilities (such as go to next fuzzy or untranslated string) Capability to save and read files in Unicode encoding (UTF-8) Unlimited undo capability Syntax highlighting Automatic file header updates Automatic change of "fuzzy" status of translated messages Support for easy insertion of tags and URLs A plugin framework for dictionaries, such as po compendium files (as for example provided on l10n.kde.org/po_overview/ ) , for consistency checks or translation suggestions A "rough translation" function to initialize untranslated messages with suggestion from a dictionary Automatic syntax check with msgfmt when saving and if an error occurred easy navigation to messages, which contain errors Full Drag & Drop - support Configurable fonts for message editor Various methods to "see" whitespace at end of lines Various methods to check consistency of translated messages, like comparing printf and Qt arguments in msgid and msgstr Quick overview over context in the po file Showing source code by references in message comments Catalog Manager: File manager view for directories of the l10n module (or similarly structured) directories), showing the present status of all PO files: if they are in need of a revision or not, how many fuzzies and untranslated strings are included etc. This view is always automatically updated and reflects all changes done to the files, including changes by programs other than KBabel. Various file open mechanisms for editing in KBabel: use Drag & Drop, double click, keyboard or context menu "Mark files" function (e.g. to identify POs that are in the responsibility of other translators) Powerful navigation using PO file statistics Automatic comparisons and statistics of POT and PO files for a quick overview which and how many files are translated (or not) and which files may be obsolete Syntax check (msgfmt --statistics --check-header) for existing files to control if the translated files will compile and, accordingly, work when distributed Free configurable commands, that can be executed from the Catalog Manager's context menu. Search/Replace functions in multiple files at once. Spellchecking of multiple files at once. Both the KBabel Editor and the Catalog Manager come with extensive "What's this" help that makes every function easy to understand and use. You can get the package from the kdesdk module of SVN or from its home page at l10n.kde.org/tools/kbabel For ways to set this PO mode up with GNU Emacs, see the comments in the file po-mode.el that comes with the GNU gettext package. It also works with XEmacs if you set it up like this: Copy po-mode.el (not the compiled .elc file) from the gettext package to a directory that's visible to XEmacs (e.g. /usr/X11R6/lib/xemacs/site-lisp/); make the following entry at the beginning of the .emacs or, depending on your distribution, .xemacs-options file in your home directory: (autoload 'po-mode "po-mode") and make the following new entry to Options -> Customize -> Variable -> auto-mode-alist: "\\.po[tx]?\\'\\|\\.po\\." (with the quotes) in the upper line and po-mode in the lower line (without any quotes). The functionality is about as follows: All important navigation features (go to next fuzzy, untranslated etc.) Automatic insertion of (some) header data Validation (checking if everything is formatted okay) Lots of useful shortcuts for navigation, removing fuzzies etc. Searching auxiliary-files for translations of a given string into other languages Looking up strings in the sources As always with Emacs, it takes some time to get used to it. (For instance, the buffer with the original text is kind of read-only and you have always to open a new buffer where you can work on your translation.) But for people who are used to Emacs or are willing to learn its ways, this mode can be a big help. Another factor might be that Emacs is apparently still one of the best ways to edit DocBook SGML which is also the format of KDE documentation. A very good introduction to working with Emacs in general and working with the SGML module in particular can be found as an Acrobat PDF file at www.snee.com/bob/sgmlfree/index.html For what is needed to make Emacs work with Unicode files see http://www.cs.uu.nl/~otfried/Mule/. (Most info in the Emacs section thanks to Matthias Kiefer.) Please, never commit a PO file to the SVN source tree without at least validating its syntax. Please also do the other checks described in this section. And do not forget about your spell checker. msgfmt --statistics --check-header /path/to/translated/files is the absolute minimum check you have to do on every file that you are about to send to your coordinator or to commit directly to SVN. What it does is give you either the number of (un)translated strings or the location and the nature of any formatting errors in your translated files. — "msgfmt" (in case you are wondering) is part of the GNU gettext package. Some specialized programs like KBabel will assist you with this. KBabel even contains an automated syntax check (among others) that saves you a lot of the work. The nightly script (nicknamed Scripty) will run on the i18n server and also check the PO files. For wrong PO files, the script will tried to mark wrong entries as fuzzy, but it cannot report in the PO file more serious errors. Such errors are only reported to Scripty's log, which is publicly available. (The files are named like yymmdd.log where yy is the 2 digit year, mm the 2 digit month and dd the 2 digit day. As the logs are packed with full of information, a tip is to try to search all occurences of your language code to get the corresponding errors.) You can spare yourself a lot of administrative work if you keep this from happening. And you can do this quite easy — you guessed it — by testing all your PO files yourself before committing them. Apart from syntax checks you also have to ensure that there are no problems in the following areas: Context information: As pointed out before, PO files may contain comments on the exact meaning of a string (e.g. if "home" stands for the user directory, a key on the keyboard or the beginning of a line). This context information must not show up in your translation. Arguments: Many strings show variables (%1, %2, %3...) which will be replaced with actual contents on runtime of the program. The variables of the original string must all show up in the translation (although not necessarily in the same order). Equations: have to be balanced in the translation just the same as in the original. Again, KBabel provides automatic validation routines for all these possible issues. In recent versions, it also allows spell checking of your files. To be able to check the translated packages in the context of the program interface, you have to generate the "(G)MO" files we mentioned above. This is accomplished by compiling the sub-folder of the l10n package appropriate to the translated language: Change to the directory "l10n" and create a file named inst-apps and add the language(s) that you want to compile (one per line, see the subdirs file as example of the needed format.) Then just compile with ./scripts/autogen.sh && ./configure && make && make install. If you need only just one language, you do not need to create an inst-apps file but you can use the language code as parameter of autogen.sh, like (where xx is the language code) ./scripts/autogen.sh xx && ./configure && make && make install If you are using unsermake instead of automake, then replace make by unsermake, so the full command becomes: ./scripts/autogen.sh && ./configure && unsermake && unsermake install In case there are any error you may want to try ./configure & & make -k; make -k docs; make -k install. With the -k parameter files and directories that do not compile are skipped. For more on this subject, see the info in the HOWTO section. After this it should be possible to choose your language and to see your translation in the program interface (assuming you compiled the program also). Now you can start your context checks: Go through all menus and dialogs and check if all your translations make sense in their real environment. Make ready for some big surprises. Then correct your PO file, recompile and check again. These context checks are often neglected due to tight release schedules. But everybody who has seen how unprofessional and even ridiculous a whole program can look if it has a lot of out-of-context information in its menus will agree that these checks are among the most important things in the whole translation process. Another test that can only be done after the translated program has been compiled is the check for "accelerator clashes". As pointed out earlier, the "&" character in PO files is used to mark "accelerator keys" (a letter which in combination with Alt (on PC keyboards) will execute a command). Program authors and translators have to make sure that no accelerator key shows up twice in the same menu (e.g. that there is not something like "&Save" and "&Save as" but maybe "&Save" and "Save &as" ). In other words: you have to prevent "accelerator clashes". After having checked their work, most translators will sent their completed translations to their language coordinator. The coordinator will usually check again and then commit their files to the main SVN server at svn.kde.org. The necessary information on SVN and its graphical frontends is given in the section Taking a Look at Available Resources and SVN, including some hints about the commands and parameters needed. You cannot commit a file if the SVN server has a more recent revision of the same file. In that case, you will probably need to use svn update to get the new version. SVN will merge it for you. You should check the result, as SVN merges only text files; it has not any idea about the syntax of a PO file. In some cases, you will get conflict, which you will need to fix (technically this is called "resolve"). One thing to watch out for are version conflicts. When you update files by SVN, SVN will try to merge changes, if there are changes on both your local version of a file and the version of the SVN server of that file. SVN only merges text lines and this works normally well. But not always... One kind of problems could be that the resulting file is not a valid PO file, as SVN has not any idea about the syntax of PO files, as for SVN, PO files are just a text files. Another, more serious kind of problems is called a conflict. In that case, SVN gives up the merging, telling that it could not merge, as both the local change and the change of the server are on the same lines of a file. SVN remember that a conflict has happened and will refuse to commit the file until you have told SVN that the conflict was fixed. In case of conflicts in text files, SVN tries to be helpful and puts special marks (lines with <, = and > characters) to help the user to see what are the conflicting change. It is your task as user to resolve (i.e. fix) the conflict. In the case of binary files, SVN cannot offer such a service, to avoid to corrupt the file. For example: Date: Wed, 05 Jan 2000 15:33:17 +0100 From: Stephan Kulow <coolo@kde.org> To: kde-i18n-doc@master.kde.org Subject: Re: Errors? Marko Rosic wrote: > > msgid "" > msgstr "" > <<<<< kdelibs.po > "Project-Id-Version: PACKAGE VERSION\n" > "POT-Creation-Date: 1999-12-06 00:59+0100\n" > "PO-Revision-Date: 1999-12-30 20:22+0100\n" > "Last-Translator: Strahinja Radi <E6> <rstraxy@sezampro.yu>\n" > "Language-Team: Serbian <LL@kde.org.yu>\n" > ======= > "Project-Id-Version: kdelibs\n" > "POT-Creation-Date: 1999-12-30 00:53+0100\n" > "PO-Revision-Date: 1999-08-23 12:57+0100\n" > "Last-Translator: Marko Rocic <roske@mainstream.co.yu>\n" > "Language-Team: Serbian <sr@li.org>\n" > >>>>>>> 1.21 > "MIME-Version: 1.0\n" > "Content-Type: text/plain; charset=iso-8859-2\n" > "Content-Transfer-Encoding: ENCODING\n" > > What does this mean? Which do I need to delete? Depends. The portion between <<<<< and ====="=" is your version and the one between ===="=" and >>>>>> is the one in CVS. I would say merge them :) Greetings, Stephan The example above come from the time KDE used CVS and is embeded in an email. But it could happen with SVN too, in a very similar way. Probably you wonder now how to solve such a problem. Normally you can try to solve it by using your normal tool, e.g. KBabel. But sometimes, this is not possible and you need to use a text editor, e.g. Kate. An easy way of removing a conflict is to revert the file by the command svn revert. Another is to use one of the auxiliary files created by the update with have file names starting by the file name of the conflicting file. You can simply copy the version that you find correct instead of the file with a conflict. When you have fixed the conflict, you need to tell SVN that you have fixed the conflict, so that SVN will allow you to commit the file. This can be done easily by svn resolved. (If you have chosen to revert the file, this step is not necessary, as SVN has already done it implicitly.) Conflicts might appear often with PO files automatically merged by Scripty. Here a good solution is to keep working on the local version (so copy the corresponding file over). (Scripty will again work during the next European night and morning.) The bulk of information on KDE documentation is of course being provided by the KDE documentation team, especially their coordinator Lauri Watts. Please have a look at their web pages at http://docs.kde.org/team/. The documentation and online-help for KDE programs are written now entirely in &XML; (eXtensible Markup Language) DocBook. 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 KBabel by Matthias Kiefer just as for GUI translation. This program is part of the kdesdk module in SVN. This package can be downloaded from the same source as the other parts of &kde;. KBabel supports UTF-8 as required for the documentation and online help. For localized screen shots, you should make yourself familiar with a program like KSnapshot (from the &kde; package kdegraphics) or XV. 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 meinproc by Stephan Kulow. This parser is part of the kdelibs core module. Finally you are going to need po2xml. It takes a po-file and produces from this source the complete &XML; document. This program belongs like KBabel to kdesdk. 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. 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 program xml2pot extracts the translatable strings from the file. It then writes those strings to a POT file. Basically, the resulting POTs do not differ too much from what you already know from the GUI files. The next paragraph is outdated. The update_xml must be run by hand to create the translated DocBook documentation file. 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 is regularly run on the l10n.kde.org server. If a &kde; user eventually has set the standard language in &kde; to for example "German" or "Icelandic" and opens the &kde; help center, this translated DocBook files are processed by the help ioslave from Stephan Kulow and the resulting HTML files are shown on screen. The automatic 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-i18n. For the package "EXAMPLE" you will find the POT files in the directory l10n/templates/docmessages/(EXAMPLE) the translated PO files in the directory l10n/$LANGUAGE/docmessages/(EXAMPLE)/ the English documentation files in the directory l10n/documentation/(EXAMPLE)/doc/ (you need this file to generate the translated DocBook file) the translated documentation (in DocBook format) in the directory l10n/$LANGUAGE/docs/(EXAMPLE) Claudiu Costin has built scripts for a daily documentation statistic. This page gives an overview of the existing documentation for your language and the status (&ie; outdated, current...). This statistics does currently contain only documentation that was at least at some time completely translated — simply because this statistic does compare DocBook files. These files are generated by po2xml only if the corresponding PO file contains no fuzzies and untranslated strings. If you have the l10n sources for your language on your computer then the Catalog Manager of KBabel 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. 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 the pages of the documentation team. Generally speaking, you should just install KBabel 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/templates/docmessages/, l10n/$LANGUAGE/docmessages/, l10n/$LANGUAGE/docs/ l10n/scripts/ and l10n/documentation/(PACKAGE)/doc/ from SVN): 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 KBabel 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. Remember to set SettingsConfigure KBabel... PreferencesSaveEncoding: Default: to UTF-8 (8bit Unicode Transfer Format). Additionally, you should enter the path to your PO files for the Catalog Manager (see next item) and probably also activate PreferencesEdit the Show surrounding quotes on the Appearance tab because otherwise you cannot see spaces at line ends. First thing after you launch KBabel you should start the Catalog Manager with ToolsCatalog Manager.... The Catalog Manager 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/templates/docmessages/ and l10n/$LANGUAGE/docmessages/. Also you have to enter the path to these files in the KBabel settings. If the Catalog Manager shows no translation for your program (&ie; there is no corresponding PO file in l10n/$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 &ie; l10n/$LANGUAGE/docmessages/(PACKAGE)/(PROGRAM).po. KBabel takes automatically care of this, if you load the file from the Catalog Manager and save it afterwards. You just need to make sure that you put the right path names in SettingsConfigure KBabel... in the dialog at Catalog Manager. 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 (&ie; 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 KBabel provides the "diff mode". In this mode (for corrections this mode should always be switched on) new and deleted parts of the msgid are highlighted. For this to work KBabel keeps a translation database where it automatically stores translated msgids and 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 screen shots you should produce a localized (⪚ with a translated &GUI;) version. KSnapshot is a useful tool for this purpose, but any application is fine as long as it can produce screen shots and save them as PNG file. 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. 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 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 KBabel 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"... KBabel helps with this because if you hit the quotation mark key on the keyboard KBabel actually inserts a backslash before the quotation mark automatically. & in the msgid is used in the &GUI; translation as the mark for a shortcut to a menu entry. So to help with this KBabel highlights the msgstr as wrong if this character is not balanced between msgid and msgstr (actually KBabel tries to guess if you translate &GUI; or documentation but for this guess it is not always enough information available). For documentation this balancing is no longer true and can lead to a highlighted msgstr even though the msgstr is correct. For translation of documentation you can turn this feature off (SettingsConfigure KBabel... and Edit, General, Change text color on error). 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 coordinator.) 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 --> and <!-- TRANS:ROLES_OF_TRANSLATORS --> This are XML comments and are not displayed in the English documentation. split2po 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. Style: Each translation team should probably have some basic style guides which sets the tone for 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. KBabel has a translation database. This database 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 database as well. This is also a great help to keep consistency (SettingsConfigure DictionaryTranslation database). There exists also the web based &kde; Dictionary database with translations that you can use for your language. 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 KBabel (ToolsSpellingSpell check...). This spell checker can be configured through the Preferences dialog (SettingsConfigure KBabel...). 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 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. 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 NN, you type update_xml NN 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: update_xml de kdemultimedia or the German translation application aktion: update_xml de aktion update_xml automatically calls the &XML; parser meinproc with the option --check which makes it validate the generated &XML; document. If the parsing process fails, it will tell you the line numbers and error messages. If meinproc 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 recently 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, &ie; if your language was "German" change the line <!ENTITY % English "INCLUDE" ><!-- change language only here --> like this: <!ENTITY % German "INCLUDE" ><!-- change language only here --> Now that you generated the docbook file for your language you can check that the syntax is correct and all used entities (&ie; &kapp; etc.) can be resolved correctly. 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 meinproc from Stephan Kulow. The calling syntax is meinproc --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 meinproc 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/kde.dtx" that could not be found, check that the needed version of meinproc is called. (If you realize that your self-compiled KDE is missing a new meinproc, check the BZip2 library and recompile kdelibs.) 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 meinproc not only checks the syntax but additionally generates HTML files in the directory of the corresponding docbook file. 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;. As the former chapter about KDE Bugs (KDE's bug database) was completely outdated, this is an ersatz in telegraphic mode to (some?) important points about KDE Bugs. In KDE, bugs are collected in a bug database, called KDE Bugs. KDE Bugs is a database of the Bugzilla-kind. Mainly KDE Bugs is web-based, but it uses emails for notifications. KDE Bugs has also an email interface with limited possibilities (especially you cannot create a bug report by email.) Often KDE Bugs has some reach problems, in such cases, it can be useful to know that there is also a SSL access: https://bugs.kde.org. (Of course, it does not work always, especially if KDE Bugs is overloaded.) Bug reports are handled by their number. KDE Bugs handles wishes like bugs too, just with a different priority. In KDE Bugs, a user needs to be registered to be able to write to bug reports (or to create new ones). Users are represented by their email address (but do not worry, KDE Bugs allows you to change your email address, in case you would need it). When not registered, a user has only a restricted read-only view of the bug reports. Each time a bug report is modified, KDE Bugs sends an email to the emails linked to the bug report (bug reporter, the "maintainer", people having voted for the bugs, people having registered themselves in the CC list of the bug report). Also the notification is sent to the kde-bugs-dist mailing list. The life of a bug report is that first it is created, getting the status UNCONFIRMED or NEW. (Unlike other Bugzilla-like databases, bug reports are seldom confirmed in KDE, as KDE has not a special team for it.) When the bug is fixed, the bug report's status is changed to RESOLVED/FIXED. There are also other possible RESOLVED state, for a duplicate (RESOLVED/DUPLICATE), for an invalid bug (RESOLVED/INVALID, e.g. if a reporter has reported the exact same bug more than once or if a question remains unanswered for more than a year), for stating that the bug report will not be fixed (RESOLVED/WONTFIX) or that the bug report cannot be reproduced at all (RESOLVED/WORKSFORME). (Other Bugizlla-like databases uses the states VERIFY and CLOSE, but KDE does not, as KDE has no bug quality team). To be able to change properties of the bug report (including status), a user must have an "editing" capability. Please ask the Sysadmins to get it if you need it. Translation bugs are in the "component" named "i18n", there is a "product" named "general" and there are other "products" for many language teams. (Your team can be added too, either as a private email address or with a mailing list address. Ask the Sysadmins to get it if you want it.) Mostly "component" and "product" are written together e.g. i18n/general . The mail interface has, as written before, limited capabilities, but can be enough for many tasks, and also can avoid to have to wait on a crowded web site. The most simple address is of the form nnnnnn@bugs.kde.org where nnnnnn is the (unpadded) bug number (example 12345@bugs.kde.org). This simple form can be used by any user having an account on KDE Bugs, of course only when using the registered email address, not from another email address. Replying to a notification email of KDE Bugs produces such an email address too. For users with "editing" capability, other email addresses are available (where nnnnnn is still the bug number). The main ones are: nnnnnn-close@bugs.kde.org and nnnnnn-done@bugs.kde.org . They change the bug report's status to RESOLVED/FIXED. (As written before the status CLOSED is not used in KDE, however the name of the email addresses comes from the previous KDE Bugs system, before it was Bugzilla-like.) To re-open a bug (status REOPEN), you can use nnnnnn-reopen@bugs.kde.org . To mark as RESOLVED/INVALID: nnnnnn-invalid@bugs.kde.org . To mark as RESOLVED/WONTFIX: nnnnnn-wontfix@bugs.kde.org . To mark as RESOLVED/WORKSFORME: nnnnnn-worksforme@bugs.kde.org . To mark as RESOLVED/DUPLICATE: nnnnnn-duplicate-xxxxxx@bugs.kde.org , where xxxxxx is the bug number of the original bug that is duplicated. This area is pretty much in the responsibility of the individual teams. It is not a "must" for any team to maintain a web site. But it is highly recommended. To be more specific: it is even recommendable to have two web sites: one for internal use of the translation team and one for the KDE users the individual team is translating for. As a matter of course, both sites will be created in the language of the respective team. And both sites can also be just one if the team prefers it that way. As already stated in the intro of this HOWTO, you can get the web space for an internal team site from the KDE project. It will be located at l10n.kde.org/teams/$LANG/ . Normally you would use this kind of space for internal announcements, to-do lists, overviews of who is doing what, Howtos, style guides, lists of standard translations and a lot of other things related to the "infrastructure" of your team. In most cases, together with a mailing list such a team site pretty much is your "infrastructure". If you ever went to a Linux fair or a KDE user meeting in your own country, you probably know that there is real demand for information on KDE in people's own language. Strangely, this area is often neglected, though. So far, very few teams have up-to-date translations of the KDE web site or real informative KDE user sites of their own. There are exceptions, of course. The French team, for instance, even has a press book and does a lot of public relations for KDE, not only by maintaining a web site. At the moment, there are two points under consideration: To provide the translation teams with separate snapshots of the original KDE web sites in order to make translation easier To create separate entries for "user web sites" (as opposed to "team web sites") on the team page Suggestions as to what else we can do for the visibility and effective creation of localized web sites are very welcome. KDE (as many other open source projects) uses mailing lists as main way of communication. Many mailing lists of KDE are described on the mailing lists description page. Most KDE mailing lists are handled by the Mailman interface (Here too is a list with descriptions). Look at the start of mailing lists description page if you would prefer reading a mailing list in another way than as emails to you. Most KDE mailing lists are publicly archived in lists.kde.org, some are only archived in the Mailman interface; in that case they might be reserved to subscribers (therefore not public). Most KDE mailing lists are either for "developers" or for "users" (seldom for both). This difference can be important if you want to follow closely an application in KDE. Often information about releases are only given in such developer mailing lists and not repeated in any other mailing list. This is especially true for freeze or release schedules. Of course in KDE there are mailing lists that are more oriented for translators, general ones and also language-specific ones. (The language specific languages are listed only in the Mailman interface. Mostly they have the language code in their name.) The main mailing list for translators in KDE is the mailing list called kde-i18n-doc. You can subscribe it at its Mailman interface. The archive is at lists.kde.org. (The archive is public.) The direct email is kde-i18n-doc@kde.org. Even if the mailing list has "doc" in its name, it is not limited to discussions about translating documentation. (The name has historical reasons. There were two mailing lists for discussing about translations. As it soon seemed to be futile, only one was kept. The mailing list kde-i18n-doc was the more active, so it is this one that was kept.) The mailing list for developers and users of KBabel You can subscribe it at its Mailman interface. The archive is done by Mailman. (The archive is public.) The direct email is kbabel@kde.org. The mailing list for discussing about untranslated messages and untranslated documentation is kde-doc-english. You can subscribe it at its Mailman interface. The archive is at lists.kde.org. (The archive is public.) The mailing list for discussing about using Docbook to write documentation for KDE. You can subscribe it at its Mailman interface. The archive is at lists.kde.org. (The archive is public.) This mailing list was reported as being as good as death, unfortunately. In KDE, there is a mailing for notification of every change in KDE SVN. This mailing list is called kde-commits. The mailing list is not read-only, and often there are discussions about a commit, when other developers do not find the commit right. This mailing list is with very high traffic. It is recommended to have a (cheap) broadband Internet connection if you want to subscribe to this list. You can subscribe it at its Mailman interface. The archive is at lists.kde.org. (The archive is public.) In KDE, there is a mailing for notification of every change in KDE SVN. This mailing list is called kde-bugs-dist. The mailing list is read-only. If you want to reply to a message, please do it to the corresponding bug report. This mailing list is with very high traffic. It is recommended to have a (cheap) broadband Internet connection if you want to subscribe to this list. You can subscribe it at its Mailman interface. The archive is at lists.kde.org. (The archive is public.) Subscribing to this list is of limited use for a translator, as mostly the bugs reported will not have anything to do with translations. It can only be useful to find translation bugs reported to an application instead of being reported as "l10n" bug (and to move such bug reports). Mostly for translators it is easier to query for the "l10n" bugs when they have time to do it, especially if there are interested only in their own language. There are two active l10n modules in KDE SVN (and also all the released ones). The two modules are: trunk/l10n for the unstable development branch branches/stable/l10n for the stable branch The generic directory overview of a l10n module is: the templates directory: the place where the translation templates are stored. the language directories (e.g. fr, de, en_GB) where the translations are stored. the scripts directory: here are scripts needed for the l10n module, however most of the scripts are not necessarily usable by translators. the documentation directory: the place where the original English documentation is referred. l10n/templates/messages Place of the translation template files for the GUI. l10n/templates/docmessages Place of the translation template files for the documentation. l10n/templates/webmessages Place of the translation template files for some of KDE websites. l10n/$lang/messages Place of the translation files for the GUI. l10n/$lang/docmessages Place of the translation files for the documentation. l10n/$lang/docs Place of the translated documentation. l10n/$lang/webmessages Place of the translation files for some of KDE websites. l10n/$lang/internal Place for internal files of the translation teams, e.g. for the compendium file. The files in such a directory will never be released. l10n/documentation Place for the untranslated original English DocBook documentation files. The sub-directories of this directory are external references to the doc sub-directories of the corresponding modules. l10n/scripts Place for internal script files of the l10n module. The files that are to be translated by the individual languages teams are stored in the following locations: The original GUI translation templates are located in l10n/templates/messages. The already translated GUI files (the POs) are located in l10n/language/messages. For the procedure on how to make a PO file from POT file please read the section on GUI translation. The translated documentation files are located in l10n/language/docs. (The same goes for downloading these files as for POs.) For more info on this whole subject please read the section on doc translation. You can get files via SVN or WebSVN. The following is mainly a reference section of the most important of the resources that have been described throughout this HOWTO — a reference of the files that are to be translated, of statistics about the present status of these files and of many other useful things we all need in the process of KDE translation. But there are also some additional items that have not been mentioned so far. Chances are that you know the l10n server already, simply because it is the home of this document. If you do not, you should do a look around as soon as possible since many of the resources for translators are located there, including now a "tools" page: a listing of specialized programs for translators and documenters which are available on the server. Every feedback and contribution to the material (tools, scripts, Howtos) is highly welcome as stated in the original announcement. The person in charge for the i18n server is (at the time of writing this document) Claudiu Costin (technical side, managing the web server and the scripts). You can also have a web site for your team on this server (e.g. for internal todo lists, lists of who is responsible for what, internal translation HOWTOs, styleguides and so on). The advantage to having it here compared to having it on private sites on the outside is that everybody in your team has access to it via KDE SVN. That means: no problems accessing the data if someone is on vacation or simply drops out. The necessary information on SVN and their graphic frontends is provided in the section Taking a Look at Available Resources and SVN. The use of WebSVN should be pretty much self-evident. These are the main resources in this area: The mailing list for translators and documenters (kde-i18n-doc@kde.org), archived with plenty of other KDE lists at lists.kde.org. Main platform for discussions, problem reports and announcements regarding KDE translation and documentation. Quite naturally, this is the most up-to-date resource of information for you. Another list that often provides useful information or has answers to questions about technical difficulties is the main developer list at kde-devel@kde.org (get in by sending a mail with "subscribe" in the subject to kde-devel-request@kde.org). There is also a specialized list for technical issues of DocBook at kde-docbook@kde.org (subscription procedure is similar to the one just mentioned). The KDE chat rooms at irc.kde.org which often lend the opportunity to "talk directly" (sort of) to the developers. It can also be used, of course, for translator meetings. There are several different flavors: The original KDE web sites: The most important one is www.kde.org, of course, the virtual center of all information on KDE Grouped around this center is the "family" of specialized web servers like developer.kde.org (info and documentation for programmers), l10n.kde.org (well, you know), lists.kde.org (searchable archives of most KDE mailing lists), bugs.kde.org (web interface for the bug reporting and tracking system), devel-home.kde.org (home pages for several KDE apps), koffice.org (for the KDE office suite), www.kdevelop.org (home of the KDE programming environment), and kde.themes.org (info and showroom for KDE designs). Localized and translated KDE web sites: Those for internal use of the translation teams (with to-do lists, translation term lists, Howtos, style guides and so on) such as l10n.kde.org/teams/fr/. Remember: you can get such a site on the i18n server for your translation team And user sites such as the ones at