i18n API
********

sphinx.locale.init(locale_dirs, language, catalog='sphinx', namespace='general')

   Look for message catalogs in *locale_dirs* and *ensure* that there
   is at least a NullTranslations catalog set in *translators*.  If
   called multiple times or if several ".mo" files are found, their
   contents are merged together (thus making "init" reentrant).

sphinx.locale.init_console(locale_dir, catalog)

   Initialize locale for console.

   New in version 1.8.

sphinx.locale.get_translation(catalog, namespace='general')

   Get a translation function based on the *catalog* and *namespace*.

   The extension can use this API to translate the messages on the
   extension:

      import os
      from sphinx.locale import get_translation

      MESSAGE_CATALOG_NAME = 'myextension'  # name of *.pot, *.po and *.mo files
      _ = get_translation(MESSAGE_CATALOG_NAME)
      text = _('Hello Sphinx!')


      def setup(app):
          package_dir = path.abspath(path.dirname(__file__))
          locale_dir = os.path.join(package_dir, 'locales')
          app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)

   With this code, sphinx searches a message catalog from
   "${package_dir}/locales/${language}/LC_MESSAGES/myextension.mo".
   The "language" is used for the searching.

   New in version 1.8.

sphinx.locale._(message, *args)

   Translation function for messages on documentation (menu, labels,
   themes and so on). This function follows "language" setting.

sphinx.locale.__(message, *args)

   Translation function for console messages This function follows
   locale setting (*LC_ALL*, *LC_MESSAGES* and so on).


Extension internationalization (*i18n*) and localization (*l10n*) using i18n API
================================================================================

New in version 1.8.

An extension may naturally come with message translations.  This is
briefly summarized in "sphinx.locale.get_translation()" help.

In practice, you have to:

1. Choose a name for your message catalog, which must be unique.
   Usually the name of your extension is used for the name of message
   catalog.

2. Mark in your extension sources all messages as translatable, via
   "sphinx.locale.get_translation()" function, usually renamed "_()",
   e.g.:

   src/__init__.py

      from sphinx.locale import get_translation

      MESSAGE_CATALOG_NAME = 'myextension'
      _ = get_translation(MESSAGE_CATALOG_NAME)

      translated_text = _('Hello Sphinx!')

1. Set up your extension to be aware of its dedicated translations:

   src/__init__.py

      def setup(app):
          package_dir = path.abspath(path.dirname(__file__))
          locale_dir = os.path.join(package_dir, 'locales')
          app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)

1. Generate message catalog template "*.pot" file, usually in
   "locale/" source directory, for example via Babel:

      $ pybabel extract --output=src/locale/myextension.pot src/

2. Create message catalogs ("*.po") for each language which your
   extension will provide localization, for example via Babel:

      $ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR

3. Translate message catalogs for each language manually

4. Compile message catalogs into "*.mo" files, for example via Babel:

      $ pybabel compile --directory=src/locale --domain=myextension

5. Ensure that message catalog files are distributed when your package
   will be installed, by adding equivalent line in your extension
   "MANIFEST.in":

   MANIFEST.in

      recursive-include src *.pot *.po *.mo

When the messages on your extension has been changed, you need to also
update message catalog template and message catalogs, for example via
Babel:

   $ pybabel extract --output=src/locale/myextension.pot src/
   $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale
