2 files changed, 81 insertions, 0 deletions
diff --git a/doc/extdev/i18n.rst b/doc/extdev/i18n.rst
index c8c54da36..c3ec173a2 100644
--- a/doc/extdev/i18n.rst
+++ b/doc/extdev/i18n.rst
@@ -15,3 +15,83 @@ i18n API
 
 .. autofunction:: __
 
+
+.. _ext-i18n:
+
+Extension internationalization (`i18n`) and localization (`l10n`) using i18n API
+---------------------------------------------------------------------------------
+
+.. versionadded:: 1.8
+
+An extension may naturally come with message translations.  This is briefly
+summarized in :func:`sphinx.locale.get_translation` help.
+
+In practice, you have to:
+
+#. 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.
+
+#. Mark in your extension 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
+
+     MESSAGE_CATALOG_NAME = 'myextension'
+     _ = get_translation(MESSAGE_CATALOG_NAME)
+
+     translated_text = _('Hello Sphinx!')
+
+#. Set up 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(MESSAGE_CATALOG_NAME, locale_dir)
+
+#. Generate message catalog template ``*.pot`` file, usually in ``locale/``
+   source directory, for example via `Babel`_:
+
+   .. code-block:: console
+
+      $ pybabel extract --output=src/locale/myextension.pot src/
+
+#. Create message catalogs (``*.po``) for each language which your extension
+   will provide localization, for example via `Babel`_:
+
+   .. code-block:: console
+
+      $ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR
+
+#. Translate message catalogs for each language manually
+
+#. Compile message catalogs into ``*.mo`` files, for example via `Babel`_:
+
+   .. code-block:: console
+
+      $ pybabel compile --directory=src/locale --domain=myextension
+
+#. Ensure that message catalog 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 *.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`_:
+
+.. code-block:: console
+
+   $ pybabel extract --output=src/locale/myextension.pot src/
+   $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale
+
+.. _Babel: http://babel.pocoo.org/
diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst
index fca8fbba3..eac4ded40 100644
--- a/doc/extdev/index.rst
+++ b/doc/extdev/index.rst
@@ -187,6 +187,7 @@ as metadata of the extension.  Metadata keys currently recognized are:
   output files can be used when the extension is loaded.  Since extensions
   usually don't negatively influence the process, this defaults to ``True``.
 
+
 APIs used for writing extensions
 --------------------------------