diff options
| -rw-r--r-- | doc/extdev/i18n.rst | 80 | ||||
| -rw-r--r-- | doc/extdev/index.rst | 1 | ||||
| -rw-r--r-- | sphinx/locale/__init__.py | 11 |
3 files changed, 86 insertions, 6 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 -------------------------------- diff --git a/sphinx/locale/__init__.py b/sphinx/locale/__init__.py index 77566ec04..6ae20d0d0 100644 --- a/sphinx/locale/__init__.py +++ b/sphinx/locale/__init__.py @@ -255,20 +255,19 @@ def get_translation(catalog, namespace='general'): import os from sphinx.locale import get_translation - _ = get_translation(__name__) + 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(__name__, locale_dir) + app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir) With this code, sphinx searches a message catalog from - ``${package_dir}/locales/${language}/LC_MESSAGES/${__name__}.mo`` - (ex. ``sphinxcontrib.applehelp.mo``). Of course, you can use - arbitrary catalog name instead of ``__name__``. The - :confval:`language` is used for the searching. + ``${package_dir}/locales/${language}/LC_MESSAGES/myextension.mo``. + The :confval:`language` is used for the searching. .. versionadded:: 1.8 """ |