## 6.25.2 Class-based API

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]])
  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.

`translation`(domain[, localedir[, languages[, class_]]])
  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`.

`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.

#### Footnotes

... used.6.3
  See the footnote for `bindtextdomain()` above.

Subsections

- 6.25.2.1 The `NullTranslations` class
- 6.25.2.2 The `GNUTranslations` class
- 6.25.2.3 Solaris message catalog support
- 6.25.2.4 The Catalog constructor