doc: Enhance documentation about internalization of external extension.

doc/extdev/index.rst

@@ -187,6 +187,84 @@ 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``.
 
+.. _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/
+
+
 APIs used for writing extensions
 --------------------------------
 

sphinx/locale/__init__.py

@@ -255,17 +255,18 @@ def get_translation(catalog, namespace='general'):
         import os
         from sphinx.locale import get_translation
 
-        _ = get_translation(__name__)
+        EXTENSION_NAME = 'myextension'  # name of both *.pot, *.po and *.mo files
+        _ = get_translation(EXTENSION_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(__name__, locale_dir)
+            app.add_message_catalog(EXTENSION_NAME, locale_dir)
 
     With this code, sphinx searches a message catalog from
-    ``${package_dir}/locales/${language}/LC_MESSAGES/${__name__}.mo``
+    ``${package_dir}/locales/${language}/LC_MESSAGES/myextension.mo``
     The :confval:`language` is used for the searching.
 
     .. versionadded:: 1.8