Adding i18n/l10n to Trac plugins (Trac ≥ 0.12)

Intro and Motivation

Are you a user of Trac and do your work with it, nothing more? Well, you may ignore this page and go on reading another subpage of CookBook.

Professional coders/translators, please skip to the actual cookbook content in 'Required workflow', since there can't be any news for you before that section.

If you want to learn about translation for a plugin, that as you know already provides one/several message catalog/s, the section 'Do translators work' and following parts are for you.

Ultimately, all plugin maintainers and developers in general, that are facing requests and are willing to take care for growing demand of their plugin to speak same (foreign) language(s) as Trac ≥ 0.12 should just read on.

i18n, l10n, … help!

In short i18n stands for internationalization (count 18 more chars between i and n) and is defined as software design for programs with translation support. localisation that is abbreviated as l10n could be seen as a follow-up process providing data for one or more locales. It is taking care of feature differences between the original/default (that is English is most cases including Trac) and a given locale as well. Such features are i.e. sentence structure including punctuation and formatting of numbers, date/time strings, and currencies. Once you did some ground work at the source (i18n), most remaining is proper translation work (l10n) putting more or less effort in preserving the sense of the original while looking as native locale as possible.¹

NLS (National Language Support or Native Language Support) is meant to be the sum of both. And there are more related terms that we could safely skip for now.^{1, 2}

Background and concept of i18n/l10n support for Trac plugins

It begun with adding Babel to Trac. Some plugin maintainers created their own translation module inside each plugin separately. Growing amount of code redundancy and possibility of error within imperfect copies and variants of a translation module all that was certainly not a desirable situation. And Trac core maintainers took responsibility with adding functions dedicated to i18n/l10n support for Trac plugins.

The evolution of this functions has been documented in ticket 7497. The final implementation as mentioned there in comment 12 was introduced to Trac trunk in changeset r7705 and finally done with changeset r7714.

Now adding the needed i18n/l10n helper functions is done by importing a set of functions from trac/util/translation.py and providing proper configuration for an additional translation layer ('domain') inside the plugin code. On plugin initialization the dedicated translation domain is created as well and corresponding catalog files holding translated messages are loaded into it. Whenever a translatable text is encountered during runtime inside plugin's code, i18n/l10n helper functions will try to get the corresponding translation from the message catalog of plugin's domain and fall back silently to Trac's main message catalog, if needed.

Both searches take the locale setting as a second request argument. Valid settings are a combination of language and country code, often extended further by the character encoding used, i.e. to read like ‘de_DE.UTF-8’. The encoding is of special relevance for languages that had an older encoding per default that was not sufficient for all common chars used by native speakers of that language. 'C' is a special locale code since it disables all translations and programs use English texts as required by POSIX standard. Character encoding is highly dependent on the underlying operation system then.³

First matching translation will replace the default text what by gettext convention is the same as the msgid, that is used, if all attempts fail to find an exact matching translation.

Required workflow

a walk-through

Prepare plugin code

Import i18n/l10n helper programs

For a fictional plugin 'foo' just add

from trac.util.translation import domain_functions

_, tag_, N_, add_domain = domain_functions('foo', 
    '_', 'tag_', 'N_', 'add_domain')

at the beginning of the main python script file.

To bring in the compiled message catalog for actually using plugin's message catalogs you'll have to extend the __init__ function of plugins main class as well. This could be done like this:

    def __init__(self):
        self._version = None
        self.ui = None
        # bind the 'foo' catalog to the specified locale directory
        locale_dir = pkg_resources.resource_filename(__name__, 'locale')
        add_domain(self.env.path, locale_dir)

assuming that folder locale will reside in ./foo/locale/ within the directory structure (as observable inside the Python egg after packaging).

If you didn't have it in the source by now, add a

import pkg_resources

at the beginning of the plugin script as well or the line locale_dir = ... (see previous code snippet) will throw an 'ImportError'.

[FIXME: explain what _version and ui are used for or leave them out, if unnecessary here]

Preset configuration for i18n/l10n helper programs

Add some lines to setup.cfg or, if it doesn't exist by now, create it with the following content:

[extract_messages]
add_comments = TRANSLATOR:
msgid_bugs_address =
output_file = foo/locale/messages.pot
keywords = _ ngettext:1,2 N_ tag_
width = 72

[init_catalog]
input_file = foo/locale/messages.pot
output_dir = foo/locale
domain = foo

[compile_catalog]
directory = foo/locale
domain = foo

[update_catalog]
input_file = foo/locale/messages.pot
output_dir = foo/locale
domain = foo

This will tell the i18n/l10n helper programs where to look for and store message catalog files. Since we prepare for a domain dedicted to the plugin you need to change the configuration to the existing plugin directory (that is a short all-lowercase form of plugin's name in most cases) wherever it reads foo in the example.

In the extract_messages section there are other lines you may like to change. Starting with add_comments there is the place to announce yourself as the translator by adding your name after the default TRANSLATOR: label. To allow for direct feedback regarding your translation add a valid e-mail address or a mailing list dedicated to translation issues to msgid_bugs_address.

Mark text for extraction

In python scripts you'll have to wrap text with the translation function _() to get it handled by translation helper programs. Some code, that was

    msg = 'This is a msg text.'

before, will read like

    msg = _('This is a msg text.')

afterwards.

This is a somewhat time consuming task depending on the size of the plugin's code. If you initially fail to find all desired texts you may notice this by missing them from the message catalog later and come back to this step again. If the plugin maintainer is unaware of your i18n work or unwilling to support it and he adds more message without the translation function call, remember that you have to do the wrapping of these new texts too.

Message extraction for Genshi templates should be done auto-magically. However there is the markup i18n:msg available to ensure extraction even from less common tags. But there are not all issues settled with some special cases for message extraction from Genshi templates, i.e. see ​Genshi ticket 385. You should search for similar issues you may encounter while trying to handle plugin templates.

[FIXME: add more details about msg extraction from other files]

Register message catalog files for packaging

To include the translated messages into the packaged plugin you need to add the path to the catalog files to package_data in setup.py.

Announce new plugin version

The plugin will not work with any Trac version before 0.12dev, since import of the translation helper functions introduced for 0.12 will fail. It is possible to wrap the import with a try: and define dummy functions in a corresponding except ImportError: to allow the plugin to work with older versions of Trac, but there might already be a different version for 0.11 and 0.12, so this is not required in most cases.

All the work you did by now will go unnoticed, at least with regard to package naming. To help with identification of the new revision you should bump the plugin's version. This is done by changing the version/revision, typically in setup.cfg or setup.py.

Do translators work

General advice from TracL10N on making good translation for Trac in general applies here too. For those who read previous parts, you do notice that we switch from talking about i18n to 'l10n' now, don't you? No source code mangling. All code below is no meant to become part of the plugin source but meant to be put to the command line.

Switch to root directory of plugin's source, i.e.:

cd /usr/src/trac_plugins/foo

Extract the messages that where marked for translation before, or on case of Genshi templates are exposed by other means:

python ./setup.py extract_messages

The attentive reader will notice that the argument to setup.py has the same wording as a section in setup.cfg, that is not incidental. And this does apply to the following command lines as well.

If you attempt to do improvements on existing message catalogs you'll update the one for your desired language:

python ./setup.py update_catalog -l de_DE

If you omit the language selection argument -l and identifier string, existing catalogs of all languages will be updated, what is acceptably fast (just seconds) on current hardware.

But if you happen to do all the i18n work before, the you know you there's nothing to update right now. Well, so now it's time to create the message catalog for your desired language:

python ./setup.py init_catalog -l de_DE

As you may guess, there is not much to be done, if the helper programs don't know what language you'd like to work on, so the language selection argument -l and identifier string are mandatory here.

Now fire up the editor of your choice. There are dedicated message catalog (.po) file editors that ensure for quick results as a beginner as well as make working on large message catalogs with few untranslated texts or translations marked 'fuzzy' much more convenient. See dedicated resources for details on choosing an editor program as well as for help on editing .po files.^{4, 5}

Compile and use it

Compile the messages.po catalog file with your translations into a machine readable messages.mo file.

python ./setup.py compile_catalog -f -l de_DE

The argument -f is needed to include even the msgid's marked 'fuzzy'. If you have prepared only one translated catalog the final language selection argument -l and identifier string are superfluous. But as soon as there are several other translations that you don't care, it will help to select just your work for compilation.

Now you've used all four configuration sections in setup.cfg, that are dedicated to i18n/l10n helper programs. You could finish your work by packaging the plugin.

Make the python egg as usual:

python ./setup.py bdist_egg

Install the new egg and restart your web-server after you made sure to purge any former version of that plugin (without your latest work).

Advanced stuff

Finally 'true' l10n

Related resources

¹ ​http://en.wikipedia.org/wiki/Internationalization_and_localization - Internationalization and localization
² ​http://en.wikipedia.org/w/index.php?title=Multilingualism&section=18 - Multilingualism in computing
³ ​http://www.gnu.org/software/gettext/manual/gettext.html#Locale-Names - GNU 'gettext' utilities: Locale Names
⁴ ​http://www.gnu.org/software/gettext/manual/gettext.html#Editing - GNU 'gettext' utilities: Editing PO Files
⁵ ​http://techbase.kde.org/Localization/Concepts/PO_Odyssey - PO Odyssey in 'Localization/Concepts' section of KDE TechBase