## 6.27.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[, 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.

`translation`( | domain[, localedir[, languages[, class_,[fallback]]]])

  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.

#### Footnotes

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

Subsections

- 6.27.2.1 The `NullTranslations` class
- 6.27.2.2 The `GNUTranslations` class
- 6.27.2.3 Solaris message catalog support
- 6.27.2.4 The Catalog constructor