## 6.23.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, and optionally a localedir (as in `bindtextdomain()`), and a list of languages. All arguments are strings.

  If localedir is not given, then the default system locale directory is used.6.2 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 can contain a colon separated list of languages, which will be split.

  `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 `_()`, e.g.

        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.2
  See the footnote for `bindtextdomain()` above.

Subsections

- 6.23.2.1 The `NullTranslations` class
- 6.23.2.2 The `GNUTranslations` class
- 6.23.2.3 Solaris message catalog support
- 6.23.2.4 The Catalog constructor