Catalog strategies

The way flufl.i18n finds its catalog for an application is extensible. These are called strategies. flufl.i18n comes with a couple of fairly simple strategies. The first locates catalog files from within a package’s directory. Inside the package directory, you still need the gettext standard layout of <code>/LC_MESSAGES/<application>.mo.

Python package strategies

For example, to use the catalog in flufl.i18n‘s testing package, you would use the PackageStrategy.

>>> from flufl.i18n import PackageStrategy
>>> import flufl.i18n.testing.messages

By setting the $LANG environment variable, we can specify that the application translates into that language automatically.

>>> # The testing 'xx' language rot13's the source string.
>>> import os
>>> os.environ['LANG'] = 'xx'

The first argument is the application name, which must be unique among all registered strategies. The second argument is the package in which to search.

>>> strategy = PackageStrategy('flufl', flufl.i18n.testing.messages)

Once you have the desired strategy, register this with the global registry. The registration process returns an application object which can be used to look up language codes.

>>> from flufl.i18n import registry
>>> application = registry.register(strategy)

The application object keeps track of a current translation catalog, and exports a method which you can bind to the ‘underscore’ function in your module globals for convenient gettext usage.

>>> _ = application._

By doing so, at run time, _() will always translate the string argument to the current catalog’s language.

>>> print(_('A test message'))
N grfg zrffntr

Simple strategy

There is also a simpler strategy that uses both the $LANG environment variable, and the $LOCPATH environment variable to set things up:

>>> os.environ['LOCPATH'] = os.path.dirname(
...     flufl.i18n.testing.messages.__file__)

>>> from flufl.i18n import SimpleStrategy
>>> strategy = SimpleStrategy('flufl')
>>> application = registry.register(strategy)

>>> _ = application._
>>> print(_('A test message'))
N grfg zrffntr

Calling with zero arguments

Strategies should be prepared to accept zero arguments when called, to produce a default translation (usually the gettext.NullTranslator). Here, we look for the ugettext() method for Python 2 and the gettext() method for Python 3:

>>> def get_ugettext(strategy):
...     catalog = strategy()
...     try:
...         return catalog.ugettext
...     except AttributeError:
...         # Python 3
...         return catalog.gettext

>>> print(get_ugettext(SimpleStrategy('example'))('A test message'))
A test message

>>> print(get_ugettext(PackageStrategy(
...     'example', flufl.i18n.testing.messages))('A test message'))
A test message