class h10n.translator.Translator(name=None, default=None, locales=None, use_only=None, lang_map=None, country_map=None, fallback=None, strategy='simple', scan=None, helpers=None)

A Translator object is used to manage locales and perform translation.

The Translator accepts a number of keyword arguments: name, default, locales, use_only, lang_map, country_map, fallback, strategy, scan and helpers.

If the name argument is passed as non-None value, current instance of translator will be registered in the internal class-level registry. The named instance can be accessed later using get_instance() class method.


Attempt to initialize translator with name already in use will raise the ValueError.

The default argument, if passed, should be a name of default locale.

The locales argument, if passed, should be a dictionary object, which store locale names in keys, and arguments for h10n.core.Locale class in values.

The use_only argument, if passed, should be a list of locale names, which will be used in the translator. All other locales, passed via locales or loaded via scan, will be ignored.

The lang_map argument, if passed, should be a dictionary object, which store language names in keys, and locale names in values. The language map is used to resolve locale name via language name. The argument is needed only if you want to use lang property to manage locales and have more than one locale per language. For example, en-US and en-GB.

The country_map argument means the same thing as lang_map, but is used to resolve locale via country name, i.e. country property.

The fallback argument, if passed, should be a dictionary object, which store locale names in its keys and values. Is used to resolve fallback order.

The strategy argument means how to store name of current locale: globally and non-threadsafe (simple, default value) or locally in each thread (thread_local value).

The scan argument, if passed, should be a list of URIs to scan for locales. All loaded locales will override the passed ones via locales argument.

The helpers argument, if passed, should be a dictionary, which store helper aliases in keys and python path’s to helper factories in values. Is used to construct application-level helper namespace.


Set or get current locale name using country part of the name

classmethod from_config(config, prefix='h10n.')

Create Translator from “flat” configuration.

A config argument should be a dictionary, which provide arguments for default constructor. All nested dictionaries should be flatten using dot-separated keys. The keys, which contain dots, should be escaped using square brackets. If prefix argument is passed as non-empty string (default is h10n.), all non-prefixed keys from config will be ignored.

For example:

>>> # This...
>>> Translator(locales={
...    'en-US': {
...        'test.catalog': {
...            'msg': u'Message'
...        }
...    }
... })

>>> # ...is equal to:
>>> Translator.from_config({
...     'h10n.locales.en-US.[test.catalog].msg':  u'Message'
... })
classmethod get_instance(name)

Get a named instance from the registry:

>>> t = Translator(name='t', locales={'en-US': {}})
>>> t is Translator.get_instance('t')

Get application-level helper namespace from current locale


Set or get current locale name using language part of the name


Set or get current locale name

message(id, fallback=None, **params)

Factory for lazy translatable messages. Creates Message object using self as translator argument.

translate(id, fallback, locale=None, **params)

Perform message translation

An id argument should be an identifier of the message to translate, i.e. string in format {catalog}:{message}.

A fallback argument should be a string, which will be used as result of failed translation.

A locale argument, if passed as non-None value, should be a name of locale, which override current one on translation time.

Other keyword arguments will be passed directly to h10n.core.Message.format() method.

class h10n.translator.Message(translator, id, fallback, **params)

A Message object is used for lazy translatable messages.

A translator argument must be an instance or name of instance of Translator class. All other arguments are the same as for Translator.translate() method.

The Message object will be translated implicitly on convert into unicode or str. It also can be called to be translated explicitly. Keyword arguments passed via __call__ method will override passed ones via constructor.

Project Versions

Previous topic


Next topic


This Page