The gettext module defines the following API, which is very
similar to the GNU gettext API. If you use this API you
will affect the translation of your entire application globally. Often
this is what you want if your application is monolingual, with the choice
of language dependent on the locale of your user. If you are
localizing a Python module, or if your application needs to switch
languages on the fly, you probably want to use the class-based API
instead.
bindtextdomain(
domain[, localedir])
Bind the domain to the locale directory
localedir. More concretely, gettext will look for
binary .mo files for the given domain using the path (on Unix):
localedir/language/LC_MESSAGES/domain.mo,
where languages is searched for in the environment variables
LANGUAGE, LC_ALL, LC_MESSAGES, and
LANG respectively.
If localedir is omitted or None, then the current binding
for domain is returned.6.2
textdomain(
[domain])
Change or query the current global domain. If domain is
None, then the current global domain is returned, otherwise the
global domain is set to domain, which is returned.
gettext(
message)
Return the localized translation of message, based on the
current global domain, language, and locale directory. This function
is usually aliased as _ in the local namespace (see
examples below).
dgettext(
domain, message)
Like gettext(), but look the message up in the specified
domain.
ngettext(
singular, plural, n)
Like gettext(), but consider plural forms. If a translation
is found, apply the plural formula to n, and return the
resulting message (some languages have more than two plural forms).
If no translation is found, return singular if n is 1;
return plural otherwise.
The Plural formula is taken from the catalog header. It is a C or
Python expression that has a free variable n; the expression evaluates
to the index of the plural in the catalog. See the GNU gettext
documentation for the precise syntax to be used in .po files, and the
formulas for a variety of languages.
New in version 2.3.
dngettext(
domain, singular, plural, n)
Like ngettext(), but look the message up in the specified
domain.
New in version 2.3.
Note that GNU gettext also defines a dcgettext()
method, but this was deemed not useful and so it is currently
unimplemented.
Here's an example of typical usage for this API:
import gettext
gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
gettext.textdomain('myapplication')
_ = gettext.gettext
# ...
print _('This is a translatable string.')
The default locale directory is system dependent; for example,
on RedHat Linux it is /usr/share/locale, but on Solaris
it is /usr/lib/locale. The gettext module
does not try to support these system dependent defaults;
instead its default is sys.prefix/share/locale.
For this reason, it is always best to call
bindtextdomain() with an explicit absolute path at
the start of your application.
