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 _().
find(
domain[, localedir[,
languages[, all]]])
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
components:
localedir/language/LC_MESSAGES/domain.mo
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.
Return a Translations instance based on the domain,
localedir, and languages, which are first passed to
find() to get a list of the
associated .mo file paths. 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 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.
install(
domain[, localedir[, unicode]])
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.
