Adding l10n support to Trac plugins (Trac ≥ 0.12)

Motivation

[FIXME: content needed, especially address the intended audience (plugin maintainers and developers in general) here - who should read on (and who shouldn't care at all)]

i18n vs. l10n (again)

[FIXME: is this needed?, well consider this is nice to the reader allowing to focus on i18n after coming from the greater scope of l10n, but be as short as possible when]

Background and basics of i18n support

The evolution of native support for Trac plugins is documented in ticket 7497. The final implementation as documented there in comment 12 was introduced to Trac trunk in changeset r7705 and finally done with changeset r7714. Adding the needed i18n helper functions is as easy as adding

from trac.util.translation import domain_functions

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

at the beginning of the main python script file of an existing or new plugin. To bring in the compiled message catalog for actually using the translated texts one will have to extend the __init__ function of plugins main class too. For a fictional plugin Foo this would 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 (of the Python egg).

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

Required minimal workflow

a walk-through

General advice of TracL10N on making good translation for Trac in general applies here too.

Preparing the pluging code

Translation work

Compilation and testing

Advanced stuff

Finally l10n

Related resources