API Documentation

class translationstring.TranslationString

The constructor for a translation string. A translation string is a Unicode-like object that has some extra metadata.

This constructor accepts one required argument named msgid. msgid must be the message identifier for the translation string. It must be a unicode object or a str object encoded in the default system encoding.

Optional keyword arguments to this object’s constructor include domain, default, and mapping.

domain represents the translation domain. By default, the translation domain is None, indicating that this translation string is associated with the default translation domain (usually messages).

default represents an explicit default text for this translation string. Default text appears when the translation string cannot be translated. Usually, the msgid of a translation string serves double duty as as its default text. However, using this option you can provide a different default text for this translation string. This feature is useful when the default of a translation string is too complicated or too long to be used as a message identifier. If default is provided, it must be a unicode object or a str object encoded in the default system encoding (usually means ASCII). If default is None (its default value), the msgid value used by this translation string will be assumed to be the value of default.

mapping, if supplied, must be a dictionary-like object which represents the replacement values for any translation string replacement marker instances found within the msgid (or default) value of this translation string.

After a translation string is constructed, it behaves like most other unicode objects; its msgid value will be displayed when it is treated like a unicode object. Only when its ugettext method is called will it be translated.

Its default value is available as the default attribute of the object, its translation domain is available as the domain attribute, and the mapping is available as the mapping attribute. The object otherwise behaves much like a Unicode string.

interpolate(translated=None)

Interpolate the value translated which is assumed to be a Unicode object containing zero or more replacement markers (${foo} or ${bar}) using the mapping dictionary attached to this instance. If the mapping dictionary is empty or None, no interpolation is performed.

If translated is None, interpolation will be performed against the default value.

translationstring.TranslationStringFactory(domain)

Create a factory which will generate translation strings without requiring that each call to the factory be passed a domain value. A single argument is passed to this class’ constructor: domain. This value will be used as the domain values of translationstring.TranslationString objects generated by the __call__ of this class. The msgid, mapping, and default values provided to the __call__ method of an instance of this class have the meaning as described by the constructor of the translationstring.TranslationString

translationstring.ChameleonTranslate(translator)

When necessary, use the result of calling this function as a Chameleon template ‘translate’ function (e.g. the translate argument to the chameleon.zpt.template.PageTemplate constructor) to allow our translation machinery to drive template translation. A single required argument translator is passsed. The translator provided should be a callable which accepts a single argument translation_string ( a translationstring.TranslationString instance) which returns a unicode object as a translation. translator may also optionally be None, in which case no translation is performed (the msgid or default value is returned untranslated).

translationstring.Translator(translations=None, policy=None)

Return a translator object based on the translations and policy provided. translations should be an object supporting at least the Python gettext.NullTranslations API but ideally the babel.support.Translations API, which has support for domain lookups like dugettext.

policy should be a callable which accepts three arguments: translations, tstring and domain. It must perform the actual translation lookup. If policy is None, the translationstring.dugettext_policy() policy will be used.

The callable returned accepts three arguments: tstring (required), domain (optional) and mapping (optional). When called, it will translate the tstring translation string to a unicode object using the translations provided. If translations is None, the result of interpolation of the default value is returned. The optional domain argument can be used to specify or override the domain of the tstring (useful when tstring is a normal string rather than a translation string). The optional mapping argument can specify or override the tstring interpolation mapping, useful when the tstring argument is a simple string instead of a translation string.

translationstring.dugettext_policy(translations, tstring, domain)

A translator policy function which assumes the use of a babel.support.Translations translations object, which supports the dugettext API; fall back to ugettext.

translationstring.ugettext_policy(translations, tstring, domain)

A translator policy function which unconditionally uses the ugettext API on the translations object.

translationstring.Pluralizer(translations=None, policy=None)

Return a pluralizer object based on the translations and policy provided. translations should be an object supporting at least the Python gettext.NullTranslations API but ideally the babel.support.Translations API, which has support for domain lookups like dugettext.

policy should be a callable which accepts five arguments: translations, singular and plural, n and domain. It must perform the actual pluralization lookup. If policy is None, the translationstring.dungettext_policy() policy will be used.

The object returned will be a callable which has the following signature:

def pluralizer(singular, plural, n, domain=None, mapping=None):
    ...

The singular and plural objects passed may be translation strings or unicode strings. n represents the number of elements. domain is the translation domain to use to do the pluralization, and mapping is the interpolation mapping that should be used on the result. Note that if the objects passed are translation strings, their domains and mappings are ignored. The domain and mapping arguments must be used instead. If the domain is not supplied, a default domain is used (usually messages).

translationstring.dungettext_policy(translations, singular, plural, n, domain)

A pluralizer policy function which assumes the use of the babel.support.Translations class, which supports the dungettext API; falls back to ungettext.

translationstring.ungettext_policy(translations, singular, plural, n, domain)

A pluralizer policy function which unconditionally uses the ungettext API on the translations object.