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.
- 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):
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
- Change or query the current global domain. If domain is
then the current global domain is returned, otherwise the global domain is set to domain,
which is returned.
- 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).
- Like gettext(), but look the message up in the specified domain.
||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.
||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:
_ = gettext.gettext
print _('This is a translatable string.')
- ... returned.6.2
- 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
For this reason, it is always best to call bindtextdomain() with
an explicit absolute path at the start of your application.