[[PageOutline(2-4)]] = Localization (L10N) of Trac = Trac uses [http://babel.edgewall.org/ Babel] for localization. Trac trunk now contains the i18n framework and L10N files. The ''Preferences'' ' ''Language'' panel can be used to select the language from the list of available translations, otherwise the web browsers' language preferences will be honored, if possible. If you're only interested in using a localized version of Trac, then refer to the simpler ["0.12/TracInstall"] instructions. The more complete installation instructions below are aimed at developers and translators. == Installation == === Getting the Tool Chain === ==== Python Tools ==== #Pythontools 1. Install [http://babel.edgewall.org/ Babel] version [Babel:wiki:Download#LatestRelease:0.9.4 0.9.4] [[br]] Read the [http://babel.edgewall.org/wiki/SubversionCheckout detailed installation instructions] for Babel if you want to build it from source, but you should also be able to install it with a simple `easy_install` or by using one of the packages in the Download page linked above. 1. Likewise, install [http://genshi.edgewall.org/ Genshi], from the Genshi:source:trunk (at least revision [G1072]). 1. Get a svn checkout from the Trac [source:trunk trunk], e.g. `svn checkout http://svn.edgewall.org/repos/trac/trunk trac-0.12dev` === Translation Workflow === ==== Using Python tools ==== 1. Run `python setup.py extract_messages`. [[br]] This will generate the catalog template file: source:trunk/trac/locale/messages.pot [[br]] You should never have to edit that file manually. [[br]] '''Note:''' ''this step is for committers only.'' If you're not a Trac svn committer, you have to use the available messages.pot, or bug us to update that file (though we do it on a regular basis). 1. Run `python setup.py update_catalog`. [[br]] This will regenerate the various string catalogs (`trac/locale/*_*/LC_MESSAGES/messages.po`), preserving the previously translated strings and merging the new translations found in the messages.pot file. Translations that are no longer needed are commented out (`#~`) and moved at the bottom of the .po file. [[br]] Usually, you will be interested in working on one locale only, so you can pass the `-l` option to specify which catalog should be updated. For example: [[br]] `python setup.py update_catalog -l nl_NL`. [[br]] 1. Now, open your favorite editor and add or modify translations for the extracted strings in the messages.po file for your language. [[comment(See examples below.)]] 1. Once you're done, you should test your translations: 1. Run `python setup.py update_catalog -l` again, for normalizing the manual edits. For example: [[br]] `python setup.py update_catalog -l nl_NL`. [[br]] This step is also quite useful for spotting the possible mistakes, like accidental changes of `msgid` strings. Look for lines beginning with `#~`, they are indicative of such errors. Note that the comments corresponding to translations which are no longer present in the messages.pot file (as discussed in step 2. above) have been discarded by this second `update_catalog` run. 2. Run `python setup.py compile_catalog -f`. [[br]] This will generate one compiled catalog (`message.mo` file) for each (or each specified) messages.po file. You don't need to do anything with those files, they'll get installed automatically. [[br]] You will most probably need to use the force option (`-f`) in order to compile catalogs marked "fuzzy". It is fine to have ''fuzzy'' translations but try to never contribute a translation still containing those markers, as they mean that a given translation has not been reviewed by a human but were machine generated. Fuzzy translations should be either cleared when they are wrong, or validated when they are correct, by removing the ''fuzzy'' tag or even the whole line iff ''fuzzy'' was the only keyword on that line [[br]] You can also use the `-l` option here to specify the locale for which the messages.po has to be compiled. 3. Run `python setup.py install` for installing Trac and locale data. Alternatively you can use `python setup.py develop` once for all, if you want to be able to run Trac from your working copy. Note that you could stop at step 3, but then you risk to submit incomplete or, worse, buggy messages.po files. Going through the 4^th^ step will ensure a better quality standard. Finally, seeing your translations "live" in Trac is not only a great way to realize if the translation still makes sense once put in context, but also quite gratifying when you see that you picked the correct wording ;-) == Contributing == The various catalog files (`messages.po`) can be found in the repository under source:trunk/trac/locale. The `messages.pot` is the template file from which the various locale-specific files get created. === Adding translations for a new language #add-a-language If you need to create a catalog for a new locale (e.g. et_EE), do: {{{ $ ./setup.py init_catalog -l et_EE }}} Then proceed through the steps listed [#Pythontools above] starting at step 2. === Statistics === See our [http://www.transifex.net/projects/p/trac/c/default/ translation statistics], on [http://transifex.org/wiki/About Transifex]. === Editing Guidelines === There are tons of good guidelines on the web about how to write good translations. See for example: [http://techbase.kde.org/Localization/Concepts/PO_Odyssey PO_Odyssey] and [http://l10n.kde.org/docs/translation-howto/gui-step-by-step.html step-by-step], and other resources from http://l10n.kde.org. In short, a translation unit is typically something like: {{{ #: trac/ticket/templates/milestone_delete.html:41 #: trac/ticket/templates/milestone_view.html:105 msgid "Delete milestone" msgstr "Supprimer le jalon" }}} - the "#:" lines are comments indicating the locations of the message in the source. - `msgid "..."` is the message itself, this should never be changed - `msgstr` is your translation; you should keep there the same structure, as in the msgid. In particular the presence of "\n" at the beginning or the end of the msgid should be mirrored in msgstr - right after an automatic catalog update you'll see lots of: - `# fuzzy` comments: this identifies translations that are only approximated (the msgid has changed) - `msgstr ""` translations: those are newly added translations There are a few more complex situations. Here's a message containing parameters: {{{ #: trac/ticket/templates/milestone_view.html:26 #, python-format msgid "" "Completed %(duration)s ago\n" " (%(date)s)" msgstr "" "Atteint il y a %(duration)s\n" " (%(date)s)" }}} Note that you need to have to keep the parameters names from `msgid` in `msgstr`, although you can reorder them as needed. Another example, here's how a structured message looks like: {{{ #: trac/ticket/templates/milestone_delete.html:45 msgid "" "[1:Note:] See\n" " [2:TracRoadmap] for help on using\n" " the roadmap." msgstr "" "[1:Note :] consultez [2:TracRoadmap] pour obtenir de l'aide sur " "l'utilisation de la feuille de route." }}} The `[1: ...]` groups are used when the message contains markup (this is Genshi specific). It is important to keep the same semantic structure. As with message parameters, the groups can be reordered but you should have the same groups in msgid and msgstr. Of course, you can have messages that combine markup groups and parameters names: {{{ #: trac/ticket/templates/milestone_view.html:32 #, python-format msgid "" "[1:%(duration)s late]\n" " (%(date)s)" msgstr "" "[1:%(duration)s en retard]\n" " (%(date)s)" }}} Finally, there's the translation of sentences which have a singular and a plural form: {{{ #: trac/ticket/templates/query.html:29 #: trac/ticket/templates/query_results.html:30 #: trac/ticket/templates/report_view.html:94 #, python-format msgid "%(num)s match" msgid_plural "%(num)s matches" msgstr[0] "%(num)s résultat" msgstr[1] "%(num)s résultats" }}} - when such a message is newly added, you'll have [[br]] `#, fuzzy, python-format` as the first comment. Be careful to remove only the `fuzzy, ` part, but not the `python-format` keyword. - some languages (zh, ko) don't have plural forms (plural == 1), so you only have to put a `msgstr[0]` line. - some other languages have more than 2 plural forms, so you need as many `msgstr[]` as needed. ''Note: '' there are some problems with Genshi and Babel when all the `msgstr[]` need to have the same content. Also, Babel seems to handle well different parameters for msgid and msgid_plural, whereas `msgfmt` complains about those. {{{ #!comment File that bug report ;-) progress bar macros #: trac/templates/macros.html:214 #, python-format msgid "%(num)s of %(total)s %(unit)s %(title)s" msgid_plural "%(num)s of %(total)s %(units)s %(title)s" msgstr[0] "%(num)s %(unit)s « %(title)s » sur %(total)s" msgstr[1] "%(num)s %(units)s « %(title)s » sur %(total)s" #: trac/templates/macros.html:227 #, python-format msgid "%(title)s %(unit)s:" msgid_plural "%(title)s %(units)s:" msgstr[0] "%(unit)s « %(title)s » :" msgstr[1] "%(units)s « %(title)s » :" #: trac/templates/macros.html:237 #, python-format msgid "Total %(unit)s:" msgid_plural "Total %(units)s:" msgstr[0] "%(unit)s au total :" msgstr[1] "%(units)s au total :" -- cboos }}} === Terms (Definitions) === #term-definitions Consistent and careful translation of terms like [wiki:TracTimeline timeline], [wiki:TracTickets ticket], [wiki:TracReports report] is very important. These terms are used everywhere and must be easy to remember and comfortable to use. The way to make up good translations of important terms is to discuss them before using everywhere. The easiest way to accomplish it is to set up wiki pages for different languages. Look also at the various term definition pages: [[TitleIndex(TracTerms,hideprefix,format=compact)]] and TracTermTr (to be renamed once we have #1106). === Translation Coordination === #Translationcoordination For the various languages there are already various tickets logged in which the work on them is tracked: [[TicketQuery(keywords~=l10n,status!=closed,order=summary)]] This is a way by which translators for the same language can coordinate their work. === Open Issues === #Openissues - i18n infrastructure for Trac plugins (#7497) - translation of wiki pages (#1513) and help pages (TracDev/Proposals/NewHelp) - translation of text within Javascript source code - failure to start Trac (raw `NullTranslations instance has no attribute 'add'` error) when no .mo file is available [[TicketQuery(keywords~=i18n,status!=closed)]] ---- See also: [[TitleIndex(TracL10N/)]]