mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
doc: Rework "internationalization" document
Shuffle some things around, add some additional markup, and fix header styles. Signed-off-by: Stephen Finucane <stephen@that.guru>
This commit is contained in:
Stephen Finucane
parent
6c94801ec2
commit
b7ff889050
182
doc/intl.rst
182
doc/intl.rst
@ -46,14 +46,14 @@ 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.
|
||||
*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]_ on your hands in ``usage.po`` --- for your builds to
|
||||
*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
|
||||
@ -63,7 +63,8 @@ be translated you need to follow these instructions:
|
||||
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>`).
|
||||
* Set :confval:`language` to ``es`` (also possible via
|
||||
:option:`-D <sphinx-build -D>`).
|
||||
* Run your desired build.
|
||||
|
||||
|
||||
@ -71,84 +72,55 @@ 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.
|
||||
`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`_ by :command:`pip install sphinx-intl`.
|
||||
#. Install `sphinx-intl`_.
|
||||
|
||||
#. Add configurations to your `conf.py`::
|
||||
.. 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 :confval:`locale_dirs` is set to 'locale/' and
|
||||
:confval:`gettext_compact` is set to `False` (the Sphinx document is
|
||||
This case-study assumes that :confval:`locale_dirs` is set to ``locale/`` and
|
||||
:confval:`gettext_compact` is set to ``False`` (the Sphinx document is
|
||||
already configured as such).
|
||||
|
||||
#. Extract document's translatable messages into pot files:
|
||||
#. Extract translatable messages into pot files.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make gettext
|
||||
|
||||
As a result, many pot files are generated under ``_build/gettext``
|
||||
directory.
|
||||
The generated pot files will be placed in the ``_build/gettext`` directory.
|
||||
|
||||
#. Setup/Update your `locale_dir`:
|
||||
#. 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
|
||||
|
||||
Done. You got these directories that contain po files:
|
||||
Once completed, the generated po files will be placed in the below
|
||||
directories:
|
||||
|
||||
* `./locale/de/LC_MESSAGES/`
|
||||
* `./locale/ja/LC_MESSAGES/`
|
||||
* ``./locale/de/LC_MESSAGES/``
|
||||
* ``./locale/ja/LC_MESSAGES/``
|
||||
|
||||
#. Translate your po files under `./locale/<lang>/LC_MESSAGES/`.
|
||||
#. Translate po files.
|
||||
|
||||
#. make 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):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make -e SPHINXOPTS="-D language='de'" html
|
||||
|
||||
command line (for Windows cmd.exe):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
> set SPHINXOPTS=-D language=de
|
||||
> .\make.bat html
|
||||
|
||||
command line (for PowerShell):
|
||||
|
||||
.. 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
|
||||
|
||||
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 ``sphinx-intl build`` command
|
||||
before make command.
|
||||
|
||||
|
||||
Translating
|
||||
^^^^^^^^^^^
|
||||
|
||||
Translate po file under ``./locale/de/LC_MESSAGES`` directory.
|
||||
The case of builders.po file for sphinx document:
|
||||
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
|
||||
|
||||
@ -157,8 +129,7 @@ The case of builders.po file for sphinx document:
|
||||
msgid "Available builders"
|
||||
msgstr "<FILL HERE BY TARGET LANGUAGE>"
|
||||
|
||||
Another case, msgid is multi-line text and contains reStructuredText
|
||||
syntax:
|
||||
Another case, msgid is multi-line text and contains reStructuredText syntax:
|
||||
|
||||
.. code-block:: po
|
||||
|
||||
@ -174,14 +145,51 @@ syntax:
|
||||
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 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 updating difference of a pot file to po file,
|
||||
use the :command:`sphinx-intl update` command.
|
||||
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
|
||||
|
||||
@ -198,7 +206,7 @@ easy to fetch and push translations.
|
||||
.. TODO: why use transifex?
|
||||
|
||||
|
||||
#. Install `transifex-client`_
|
||||
#. Install `transifex-client`_.
|
||||
|
||||
You need :command:`tx` command to upload resources (pot files).
|
||||
|
||||
@ -208,8 +216,7 @@ easy to fetch and push translations.
|
||||
|
||||
.. seealso:: `Transifex Client documentation`_
|
||||
|
||||
|
||||
#. Create your transifex_ account and create new project for your document
|
||||
#. 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
|
||||
@ -220,8 +227,7 @@ easy to fetch and push translations.
|
||||
:Project ID: ``sphinx-document-test_1_0``
|
||||
:Project URL: ``https://www.transifex.com/projects/p/sphinx-document-test_1_0/``
|
||||
|
||||
|
||||
#. Create config files for tx command
|
||||
#. 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.
|
||||
@ -237,7 +243,7 @@ easy to fetch and push translations.
|
||||
...
|
||||
Done.
|
||||
|
||||
#. Upload pot files to transifex service
|
||||
#. Upload pot files to transifex service.
|
||||
|
||||
Register pot files to ``.tx/config`` file:
|
||||
|
||||
@ -258,15 +264,14 @@ easy to fetch and push translations.
|
||||
...
|
||||
Done.
|
||||
|
||||
|
||||
#. Forward the translation on transifex
|
||||
#. Forward the translation on transifex.
|
||||
|
||||
.. TODO: write this section
|
||||
|
||||
#. Pull translated po files and make translated HTML.
|
||||
|
||||
#. Pull translated po files and make translated html
|
||||
|
||||
Get translated catalogs and build mo files (ex. for 'de'):
|
||||
Get translated catalogs and build mo files. For example, to build mo files
|
||||
for German (de):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@ -277,32 +282,29 @@ easy to fetch and push translations.
|
||||
...
|
||||
Done.
|
||||
|
||||
Invoke make html (for BSD/GNU make):
|
||||
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.
|
||||
: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.
|
||||
|
||||
|
||||
|
||||
Contributing to Sphinx reference translation
|
||||
--------------------------------------------
|
||||
|
||||
The recommended way for new contributors to translate Sphinx reference
|
||||
is to join the translation team on Transifex.
|
||||
The recommended way for new contributors to translate Sphinx reference is to
|
||||
join the translation team on Transifex.
|
||||
|
||||
There is `sphinx translation page`_ for Sphinx (master) documentation.
|
||||
|
||||
@ -310,8 +312,7 @@ There is `sphinx translation page`_ for Sphinx (master) documentation.
|
||||
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.
|
||||
|
||||
5. (After acceptance) Translate on transifex.
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
@ -320,7 +321,6 @@ There is `sphinx translation page`_ for Sphinx (master) documentation.
|
||||
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/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user