summaryrefslogtreecommitdiffstats
path: root/doc/extdev/i18n.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 17:25:40 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 17:25:40 +0000
commitcf7da1843c45a4c2df7a749f7886a2d2ba0ee92a (patch)
tree18dcde1a8d1f5570a77cd0c361de3b490d02c789 /doc/extdev/i18n.rst
parentInitial commit. (diff)
downloadsphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.tar.xz
sphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.zip
Adding upstream version 7.2.6.upstream/7.2.6
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/extdev/i18n.rst')
-rw-r--r--doc/extdev/i18n.rst97
1 files changed, 97 insertions, 0 deletions
diff --git a/doc/extdev/i18n.rst b/doc/extdev/i18n.rst
new file mode 100644
index 0000000..6b32b8b
--- /dev/null
+++ b/doc/extdev/i18n.rst
@@ -0,0 +1,97 @@
+.. _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`) 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: https://babel.pocoo.org/