The class-based API of the gettext module gives you more flexibility and greater convenience than the GNU gettext API. It is the recommended way of localizing your Python applications and modules. gettext defines a ``translations'' class which implements the parsing of GNU .mo format files, and has methods for returning either standard 8-bit strings or Unicode strings. Instances of this ``translations'' class can also install themselves in the built-in namespace as the function _().
|domain[, localedir[, languages[, all]]])|
If localedir is not given, then the default system locale directory is used.21.2 If languages is not given, then the following environment variables are searched: LANGUAGE, LC_ALL, LC_MESSAGES, and LANG. The first one returning a non-empty value is used for the languages variable. The environment variables should contain a colon separated list of languages, which will be split on the colon to produce the expected list of language code strings.
find() then expands and normalizes the languages, and then iterates through them, searching for an existing file built of these components:
The first such file name that exists is returned by find().
If no such file is found, then
None is returned. If all
is given, it returns a list of all file names, in the order in which
they appear in the languages list or the environment variables.
|domain[, localedir[, languages[, class_[, fallback[, codeset]]]]])|
If multiple files are found, later files are used as fallbacks for earlier ones. To allow setting the fallback, copy.copy is used to clone each translation object from the cache; the actual instance data is still shared with the cache.
If no .mo file is found, this function raises IOError if fallback is false (which is the default), and returns a NullTranslations instance if fallback is true.
Changed in version 2.4: Added the codeset parameter.
|domain[, localedir[, unicode [, codeset[, names]]]])|
For the names parameter, please see the description of the translation object's install method.
As seen below, you usually mark the strings in your application that are candidates for translation, by wrapping them in a call to the _() function, like this:
print _('This string will be translated.')
For convenience, you want the _() function to be installed in Python's builtin namespace, so it is easily accessible in all modules of your application.
Changed in version 2.4: Added the codeset parameter. Changed in version 2.5: Added the names parameter.