Welcome to Resource Bundle Translations’s documentation!

Module author: Michael N. Lipp

Purpose of this module

When I got started with python, I found the “standard” way of getting localized texts with gettext rather complicated. The directory layout and especially the extra compilation step from po-files to mo-files is very annoying and in my opinion not compensated by having smaller mapping files, at least not in applications with a limited number of texts.

I looked for a good alternative for quite some time, but didn’t find one. So I decided to port the Java ResourceBundle approach to Python, with some minor adaptations.

Usage

The translations are stored in files with the same format as Java properties files. As an extension, utf-8 encoded properties files are supported (Java defines iso-8859-1 as standard encoding for properties files). The encoding can be specified as in python source files by adding a magic comment as first or second line in the properties file. The comment must match the regular expression coding[:=]\s*([-\w.]+) to be recognized (i.e. “coding: utf-8”). You may also use different encodings as long as they are supported by the codecs module and use “\n” as a line separator.

Keys in properties files may contain spaces. This allows using the default translation to be used as key as you usually do with gettext. Escaped spaces (“\ ”) are treated like regular characters and can be used to define keys or values that have leading or trailing spaces.

Translations are obtained by calling rbtranslations.translation(). The returned rbtranslations.Translations provide a subset of the methods provided by the built-in gettext.NullTranslations.

class rbtranslations.BaseTranslations(language=None)[source]

This class defines a dummy translations class that simply maps any message to itself. It is also used as a base class for real Translations classes and thus defines the interface of the Translations classes from this module.

The class mimics the interface of the standard gettext.NullTranslations class as far as reasonable. Handling of encodings has drastically been reduced. With unicode strings being available, the only reasonable approach is to get the translated messages using this type. If other encodings are required for further processing, they should be applied when interfacing with the components that require these encodings.

add_fallback(fallback)[source]

Append fallback to the chain of fallbacks for the current translation object. A translation object consults its fallback if it cannot provide a translation for a given message. (Identical to gettext.NullTranslations from the standard library.)

gettext(message)[source]

Return the translated message if defined in the instance’s dictionary as utf-8 encoded string, else forward the call to the fallback (if set). BaseTranslations simply returns the message.

language[source]

Returns the language for which this translations provides the mapping. May be None if the translations id the fall back of returning the key as mapping and no language was specified for the keys.

ugettext(message)[source]

Return the translated message if defined in the instance’s dictionary as unicode object, else forward the call to the fallback (if set). BaseTranslations simply returns the message as unicode object.

class rbtranslations.Translations(fp, fallback=None, language=None)[source]

The Translations class that takes its dictionary from a properties file object.

gettext(message)[source]

Return the translated message if defined in the instance’s dictionary as utf-8 encoded string, else forward the call to the fallback (if set). BaseTranslations simply returns the message.

ugettext(message)[source]

Return the translated message if defined in the instance’s dictionary as unicode object, else forward the call to the fallback (if set). BaseTranslations simply returns the message as unicode object.

rbtranslations.translation(basename, props_dir, languages, key_language=None)[source]

Return a chain of Translations instances that are created from the properties files with the given basename in the directory props_dir. As a convenience, props_dir may be the name of a directory or the name of a file in a directory. This allows __file__ to be passed without any modification if the properties files reside in the same directory as the python module that requests translations.

The third parameter languages is a list of strings that specifies acceptable languages for mappings.

The chain of Translations is found by searching, for each language, for properties files “basename.lang_spec.properties”. The lang_spec part is initially the string from the the current element of languages. Then a trailing “_...” part is removed and the lookup is repeated until only the basic language identifier remains (e.g. “de_DE_var1”, “de_DE”, “de”). Finally, a file “basename.properties” is searched for. Any matching properties file is converted to a Translations instance that is added as fallback to the first instance that has been found. Finally, an instance of BaseTranslations is added as fall back and the Translations instance at the beginning of the chain is returned.

The gettext key/value mapping assumes that the keys themselves are a valid translation for a single given language. Building the translation chain as described above, however, make them the last resort, preferring any match for the given languages over using the keys as translations. This behavior can be changed by specifying the key_language. If specified, using the keys as translations is considered equivalent to a file “basename.key_locale.properties”. If both a key_language is specified and a file “basename.key_language.properties” exists, translations from the file override the key values. This allows easy fixing of single mappings without changing the program’s code.

The resulting chain of Translations is cached in a global, thread-safe cache. If the result is modified by calling add_fallback() on its head, it is automatically removed from the cache.

If props_dir is a list, translations are searched for in each directory in the list as described above. Starting with the second directory in the list, each translation found is appended to the first translation as a fallback.

rbtranslations.available_translations(basename, props_dir, key_language=None)[source]

Returns the languages that are available for the given basename in the given props_dir (which may be a list as described for translation()). The set is simply derived by searching all files in the directory that match the pattern “^basename(_[a-z]{2}(_[a-zA-Z]{2}(_.*)?)?).properties$” and collecting the locale specifier part from the matches.

Download and Installation

Instructions for downloading and installing can be found on the module’s pypi page

Indices and tables

Table Of Contents

This Page