1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
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/
|
