IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update docs for i18n

Browse Source
This commit is contained in:
Takeshi KOMIYA 2019-03-02 19:45:42 +09:00
parent 4b15b6659f
commit b3b5a595a9
2 changed files with 48 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
doc/extdev/i18n.rst
View File

@ -18,77 +18,80 @@ i18n API
.. _ext-i18n:
Extension internationalization (`i18n`) and localization (`l10n`)
-----------------------------------------------------------------
Extension internationalization (`i18n`) and localization (`l10n`) using i18n API
---------------------------------------------------------------------------------
.. 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.
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 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.:
#. 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
:caption: src/__init__.py
from sphinx.locale import get_translation
from sphinx.locale import get_translation
EXTENSION_NAME = 'myextension'
_ = get_translation(EXTENSION_NAME)
MESSAGE_CATALOG_NAME = 'myextension'
_ = get_translation(MESSAGE_CATALOG_NAME)
translated_text = _('Hello Sphinx!')
translated_text = _('Hello Sphinx!')
#. Setup your extension to be aware of its dedicated translations:
#. Set up your extension to be aware of its dedicated translations:
.. code-block:: python
:caption: src/__init__.py
: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)
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 messages catalog template ``*.pot`` file, usually in ``locale/``
#. Generate message catalog template ``*.pot`` file, usually in ``locale/``
source directory, for example via `Babel`_:
.. code-block:: sh
.. code-block:: console
$ pybabel extract --output=src/locale/myextension.pot src/
$ pybabel extract --output=src/locale/myextension.pot src/
#. Create messages catalogs (``*.po``) for each language your extension
#. Create message catalogs (``*.po``) for each language which your extension
will provide localization, for example via `Babel`_:
.. code-block:: sh
.. code-block:: console
$ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR
$ 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`_:
#. Translate message catalogs for each language manually
.. code-block:: sh
#. Compile message catalogs into ``*.mo`` files, for example via `Babel`_:
$ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale
.. code-block:: console
#. Update translated messages, thanks your internationalization team.
#. Compile translated messages in ``*.mo`` files, for example via `Babel`_:
$ pybabel compile --directory=src/locale --domain=myextension
.. code-block:: sh
$ pybabel compile --directory=src/locale --domain=myextension
#. Ensure that ``*.mo`` files are distributed when your package will
#. 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
:caption: MANIFEST.in
recursive-include src *.mo
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/

12
sphinx/locale/__init__.py
View File

@ -255,21 +255,19 @@ def get_translation(catalog, namespace='general'):
import os
from sphinx.locale import get_translation
EXTENSION_NAME = 'myextension' # name of both *.pot, *.po and *.mo files
_ = get_translation(EXTENSION_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(EXTENSION_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/myextension.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
"""