sphinx/doc/extdev/i18n.rst

.. _i18n-api:

i18n API
========

.. currentmodule:: sphinx.locale

.. autofunction:: init

.. autofunction:: init_console

.. autofunction:: get_translation

.. autofunction:: _

.. autofunction:: __


.. _ext-i18n:

Extension internationalization (`i18n`) and localization (`l10n`)
-----------------------------------------------------------------

.. versionadded:: 1.8

An extension developped outside `Sphinx` own sources could obviously
come with its own messages translations. This is allowed thanks :ref:`i18n-api`,
and brieffly summarized in :func:`sphinx.locale.get_translation` help.

In practice, you have to:

#. Choose a name for your messages catalogues and template, which must be unique
   (e.g. the name of your extension: ``'myextension'``).
#. Mark in your extension `Python` sources all messages as translatable,
   via :func:`sphinx.locale.get_translation` function, usually renamed
   ``_()``, e.g.:

  .. code-block:: python
      :caption: src/__init__.py

      from sphinx.locale import get_translation

      EXTENSION_NAME = 'myextension'
      _ = get_translation(EXTENSION_NAME)

      translated_text = _('Hello Sphinx!')

#. Setup your extension to be aware of its dedicated translations:

  .. code-block:: python
      :caption: 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(EXTENSION_NAME, locale_dir)

#. Generate messages catalog template ``*.pot`` file, usually in ``locale/``
   source directory, for example via `Babel`_:

   .. code-block:: sh

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

#. Create messages catalogs (``*.po``) for each language your extension
   will provide localization, for example via `Babel`_:

   .. code-block:: sh

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

#. Generate and/or update messages catalogs for all translated languages from
   update catalog template, for example via `Babel`_:

   .. code-block:: sh

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

#. Update translated messages, thanks your internationalization team.
#. Compile translated messages in ``*.mo`` files, for example via `Babel`_:

   .. code-block:: sh

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

#. Ensure that ``*.mo`` files are distributed when your package will
   be installed, by adding equivalent line in your extension ``MANIFEST.in``:

   .. code-block:: ini
       :caption: MANIFEST.in

       recursive-include src *.mo

.. _Babel: http://babel.pocoo.org/