summaryrefslogtreecommitdiffstats
path: root/doc/usage/advanced/intl.rst
blob: e858c3c3207a27bbc5b43652fbaf16033164941d (plain)
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
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
.. _intl:

Internationalization
====================

.. versionadded:: 1.1

Complementary to translations provided for Sphinx-generated messages such as
navigation bars, Sphinx provides mechanisms facilitating the translation of
*documents*.  See the :ref:`intl-options` for details on configuration.

.. figure:: /_static/translation.*
   :width: 100%

   Workflow visualization of translations in Sphinx.  (The figure is created by
   `plantuml <https://plantuml.com>`_.)

.. contents::
   :local:

Sphinx internationalization details
-----------------------------------

**gettext** [1]_ is an established standard for internationalization and
localization.  It naively maps messages in a program to a translated string.
Sphinx uses these facilities to translate whole documents.

Initially project maintainers have to collect all translatable strings (also
referred to as *messages*) to make them known to translators.  Sphinx extracts
these through invocation of ``sphinx-build -M gettext``.

Every single element in the doctree will end up in a single message which
results in lists being equally split into different chunks while large
paragraphs will remain as coarsely-grained as they were in the original
document.  This grants seamless document updates while still providing a little
bit of context for translators in free-text passages.  It is the maintainer's
task to split up paragraphs which are too large as there is no sane automated
way to do that.

After Sphinx successfully ran the
:class:`~sphinx.builders.gettext.MessageCatalogBuilder` you will find a
collection of ``.pot`` files in your output directory.  These are **catalog
templates** and contain messages in your original language *only*.

They can be delivered to translators which will transform them to ``.po`` files
--- so called **message catalogs** --- containing a mapping from the original
messages to foreign-language strings.

*gettext* compiles them into a binary format known as **binary catalogs**
through :program:`msgfmt` for efficiency reasons.  If you make these files
discoverable with :confval:`locale_dirs` for your :confval:`language`, Sphinx
will pick them up automatically.

An example: you have a document ``usage.rst`` in your Sphinx project.  The
*gettext* builder will put its messages into ``usage.pot``.  Imagine you have
Spanish translations [2]_ stored in ``usage.po`` --- for your builds to
be translated you need to follow these instructions:

* Compile your message catalog to a locale directory, say ``locale``, so it
  ends up in ``./locale/es/LC_MESSAGES/usage.mo`` in your source directory
  (where ``es`` is the language code for Spanish.) ::

        msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"

* Set :confval:`locale_dirs` to ``["locale/"]``.
* Set :confval:`language` to ``es`` (also possible via
  :option:`-D <sphinx-build -D>`).
* Run your desired build.


In order to protect against mistakes, a warning is emitted if
cross-references in the translated paragraph do not match those from the
original.  This can be turned off globally using the
:confval:`suppress_warnings` configuration variable.  Alternatively, to
turn it off for one message only, end the message with ``#noqa`` like
this::

   Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
   risus tortor, luctus id ultrices at. #noqa

(Write ``\#noqa`` in case you want to have "#noqa" literally in the
text.  This does not apply to code blocks, where ``#noqa`` is ignored
because code blocks do not contain references anyway.)

.. versionadded:: 4.5
   The ``#noqa`` mechanism.


Translating with sphinx-intl
----------------------------

Quick guide
~~~~~~~~~~~

`sphinx-intl`_ is a useful tool to work with Sphinx translation flow.  This
section describe an easy way to translate with *sphinx-intl*.

#. Install `sphinx-intl`_.

   .. code-block:: console

      $ pip install sphinx-intl

#. Add configurations to ``conf.py``.

   ::

      locale_dirs = ['locale/']   # path is example but recommended.
      gettext_compact = False     # optional.

   This case-study assumes that BUILDDIR is set to ``_build``,
   :confval:`locale_dirs` is set to ``locale/`` and :confval:`gettext_compact`
   is set to ``False`` (the Sphinx document is already configured as such).

#. Extract translatable messages into pot files.

   .. code-block:: console

      $ make gettext

   The generated pot files will be placed in the ``_build/gettext`` directory.

#. Generate po files.

   We'll use the pot files generated in the above step.

   .. code-block:: console

      $ sphinx-intl update -p _build/gettext -l de -l ja

   Once completed, the generated po files will be placed in the below
   directories:

   * ``./locale/de/LC_MESSAGES/``
   * ``./locale/ja/LC_MESSAGES/``

#. Translate po files.

   As noted above, these are located in the ``./locale/<lang>/LC_MESSAGES``
   directory.  An example of one such file, from Sphinx, ``builders.po``, is
   given below.

   .. code-block:: po

      # a5600c3d2e3d48fc8c261ea0284db79b
      #: ../../builders.rst:4
      msgid "Available builders"
      msgstr "<FILL HERE BY TARGET LANGUAGE>"

   Another case, msgid is multi-line text and contains reStructuredText syntax:

   .. code-block:: po

      # 302558364e1d41c69b3277277e34b184
      #: ../../builders.rst:9
      msgid ""
      "These are the built-in Sphinx builders. More builders can be added by "
      ":ref:`extensions <extensions>`."
      msgstr ""
      "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
      "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."

   Please be careful not to break reST notation.  Most po-editors will help you
   with that.

#. Build translated document.

   You need a :confval:`language` parameter in ``conf.py`` or you may also
   specify the parameter on the command line.

   For BSD/GNU make, run:

   .. code-block:: console

      $ make -e SPHINXOPTS="-D language='de'" html

   For Windows :command:`cmd.exe`, run:

   .. code-block:: console

      > set SPHINXOPTS=-D language=de
      > .\make.bat html

   For PowerShell, run:

   .. code-block:: console

      > Set-Item env:SPHINXOPTS "-D language=de"
      > .\make.bat html

Congratulations! You got the translated documentation in the ``_build/html``
directory.

.. versionadded:: 1.3

   :program:`sphinx-build` that is invoked by make command will build po files
   into mo files.

   If you are using 1.2.x or earlier, please invoke :command:`sphinx-intl build`
   command before :command:`make` command.

Translating
~~~~~~~~~~~

Update your po files by new pot files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If a document is updated, it is necessary to generate updated pot files and to
apply differences to translated po files.  In order to apply the updates from a
pot file to the po file, use the :command:`sphinx-intl update` command.

.. code-block:: console

   $ sphinx-intl update -p _build/gettext


Using Transifex service for team translation
--------------------------------------------

Transifex_ is one of several services that allow collaborative translation via a
web interface.  It has a nifty Python-based command line client that makes it
easy to fetch and push translations.

.. TODO: why use transifex?


#. Install `transifex-client`_.

   You need :command:`tx` command to upload resources (pot files).

   .. code-block:: console

      $ pip install transifex-client

   .. seealso:: `Transifex Client documentation`_

#. Create your Transifex_ account and create new project for your document.

   Currently, Transifex does not allow for a translation project to have more
   than one version of the document, so you'd better include a version number in
   your project name.

   For example:

   :Project ID: ``sphinx-document-test_1_0``
   :Project URL: ``https://www.transifex.com/projects/p/sphinx-document-test_1_0/``

#. Create config files for :command:`tx` command.

   This process will create ``.tx/config`` in the current directory, as well as
   a ``~/.transifexrc`` file that includes auth information.

   .. code-block:: console

      $ tx init
      Creating .tx folder...
      Transifex instance [https://www.transifex.com]:
      ...
      Please enter your transifex username: <transifex-username>
      Password: <transifex-password>
      ...
      Done.

#. Upload pot files to Transifex service.

   Register pot files to ``.tx/config`` file:

   .. code-block:: console

      $ cd /your/document/root
      $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
        --transifex-project-name sphinx-document-test_1_0

   and upload pot files:

   .. code-block:: console

      $ tx push -s
      Pushing translations for resource sphinx-document-test_1_0.builders:
      Pushing source file (locale/pot/builders.pot)
      Resource does not exist.  Creating...
      ...
      Done.

#. Forward the translation on Transifex.

   .. TODO: write this section

#. Pull translated po files and make translated HTML.

   Get translated catalogs and build mo files. For example, to build mo files
   for German (de):

   .. code-block:: console

      $ cd /your/document/root
      $ tx pull -l de
      Pulling translations for resource sphinx-document-test_1_0.builders (...)
       -> de: locale/de/LC_MESSAGES/builders.po
      ...
      Done.

   Invoke :command:`make html` (for BSD/GNU make):

   .. code-block:: console

      $ make -e SPHINXOPTS="-D language='de'" html

That's all!

.. tip:: Translating locally and on Transifex

   If you want to push all language's po files, you can be done by using
   :command:`tx push -t` command.  Watch out! This operation overwrites
   translations in Transifex.

   In other words, if you have updated each in the service and local po files,
   it would take much time and effort to integrate them.


Using Weblate service for team translation
------------------------------------------

Read more in `Weblate's documentation`_.


Contributing to Sphinx reference translation
--------------------------------------------

The recommended way for new contributors to translate Sphinx reference is to
join the translation team on Transifex.

There is a `sphinx translation page`_ for Sphinx (master) documentation.

1. Login to Transifex_ service.
2. Go to `sphinx translation page`_.
3. Click ``Request language`` and fill form.
4. Wait acceptance by Transifex sphinx translation maintainers.
5. (After acceptance) Translate on Transifex.

Detail is here: https://docs.transifex.com/getting-started-1/translators


Translation progress and statistics
-----------------------------------

.. versionadded:: 7.1.0

During the rendering process,
Sphinx marks each translatable node with a ``translated`` attribute,
indicating if a translation was found for the text in that node.

The :confval:`translation_progress_classes` configuration value
can be used to add a class to each element,
depending on the value of the ``translated`` attribute.

The ``|translation progress|`` substitution can be used to display the
percentage of nodes that have been translated on a per-document basis.

.. rubric:: Footnotes

.. [1] See the `GNU gettext utilities
       <https://www.gnu.org/software/gettext/manual/gettext.html#Introduction>`_
       for details on that software suite.
.. [2] Because nobody expects the Spanish Inquisition!

.. _`transifex-client`: https://pypi.org/project/transifex-client/
.. _`sphinx-intl`: https://pypi.org/project/sphinx-intl/
.. _Transifex: https://www.transifex.com/
.. _Weblate's documentation: https://docs.weblate.org/en/latest/devel/sphinx.html
.. _`sphinx translation page`: https://www.transifex.com/sphinx-doc/sphinx-doc/
.. _`Transifex Client documentation`: https://docs.transifex.com/client/introduction/