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.
Translations instances can also install themselves in the built-in
namespace as the function _().
This function implements the standard .mo file search
algorithm. It takes a domain, identical to what
textdomain() takes. Optional localedir is as in
bindtextdomain() Optional languages is a list of
strings, where each string is a language code.
If localedir is not given, then the default system locale
directory is used.6.3 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
The first such file name that exists is returned by find().
If no such file is found, then None is returned.
Return a Translations instance based on the domain,
localedir, and languages, which are first passed to
find() to get the
associated .mo file path. Instances with
identical .mo file names are cached. The actual class instantiated
is either class_ if provided, otherwise
GNUTranslations. The class's constructor must take a single
file object argument. If no .mo file is found, this
function raises IOError.
This installs the function _ in Python's builtin namespace,
based on domain, and localedir which are passed to the
function translation(). The unicode flag is passed to
the resulting 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.