Skip to content

Commit

Permalink
DOCS: Improve Internationalization guide (#12377)
Browse files Browse the repository at this point in the history 
Documentation needs to mention the new Transifex CLI tool instead of the deprecated transifex-client

Co-authored-by: Chris Sewell <[email protected]>
  • Loading branch information
@rffontenelle @chrisjsewell
rffontenelle and chrisjsewell authored Jun 7, 2024
1 parent 20ec3bd commit da076d1
Showing 1 changed file with 83 additions and 40 deletions.
123 changes: 83 additions & 40 deletions doc/usage/advanced/intl.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ 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``.
these through invocation of :command:`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
Expand All @@ -51,13 +51,13 @@ 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
An example: you have a document :file:`usage.rst` in your Sphinx project. The
*gettext* builder will put its messages into :file:`usage.pot`. Imagine you have
Spanish translations [2]_ stored in :file:`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
ends up in :file:`./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"
Expand Down Expand Up @@ -101,7 +101,7 @@ section describe an easy way to translate with *sphinx-intl*.
$ pip install sphinx-intl
#. Add configurations to ``conf.py``.
#. Add configurations to :file:`conf.py`.

::

Expand Down Expand Up @@ -137,7 +137,7 @@ section describe an easy way to translate with *sphinx-intl*.
#. 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
directory. An example of one such file, from Sphinx, :file:`builders.po`, is
given below.

.. code-block:: po
Expand Down Expand Up @@ -165,7 +165,7 @@ section describe an easy way to translate with *sphinx-intl*.

#. Build translated document.

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

For BSD/GNU make, run:
Expand Down Expand Up @@ -218,69 +218,103 @@ 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
web interface. It has a nifty Go-based command line client that makes it
easy to fetch and push translations.

.. TODO: why use transifex?
#. Install `transifex-client`_.
#. Install the `Transifex CLI tool`_.

You need :command:`tx` command to upload resources (pot files).
You need the :command:`tx` command line tool for uploading resources (pot files).
The official installation process place the :file:`tx` binary file in
the current directory along with a README and a LICENSE file, and adds
the current directory to ``$PATH``.

.. code-block:: console
$ pip install transifex-client
$ curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash
.. seealso:: `Transifex Client documentation`_

#. Create your Transifex_ account and create new project for your document.
#. Create your Transifex_ account and create a new project and an organization
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:

:Organization ID: ``sphinx-document``
: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.
#. Create an API token to be used in the command-line.

This process will create ``.tx/config`` in the current directory, as well as
a ``~/.transifexrc`` file that includes auth information.
Go to your `Transifex API token`_ page and generate a token.
Copy the generated token now, as you will not be able to see it again later.

#. Set your Transifex API token in the user configuration file
:file:`$HOME/.transifexrc`.

.. code-block:: ini
[https://app.transifex.com]
rest_hostname = https://rest.api.transifex.com
token = paste_your_api_token_here
#. Alternatively, you can store your Transifex API token as the environment variable
``TX_TOKEN``, which is recognized and used by :command:`tx`.

.. code-block:: console
$ export TX_TOKEN=paste_your_api_token_here
#. Create the project's config file for :command:`tx` command.

This process will create ``.tx/config`` in the current directory.

.. code-block:: console
$ cd /your/document/root
$ tx init
Creating .tx folder...
Transifex instance [https://www.transifex.com]:
...
Please enter your transifex username: <transifex-username>
Password: <transifex-password>
...
Done.
Successful creation of '.tx/config' file
#. Upload pot files to Transifex service.

Register pot files to ``.tx/config`` file:
Register pot files to ``.tx/config`` file using
:command:`sphinx-intl update-txconfig-resources`, adjusting
``--pot-dir`` value to your project's pot files' directory:

.. code-block:: console
$ cd /your/document/root
$ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
--transifex-project-name sphinx-document-test_1_0
--transifex-organization-name=sphinx-document \
--transifex-project-name=sphinx-document-test_1_0
You can use the ``SPHINXINTL_TRANSIFEX_ORGANIZATION_NAME`` and
``SPHINXINTL_TRANSIFEX_PROJECT_NAME`` environment variables
instead of the respective command line arguments.

.. seealso:: `sphinx-intl update-txconfig-resources documentation`_

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.
# Getting info about resources
sphinx-document-test_1_0.builders - Getting info
sphinx-document-test_1_0.builders - Done
# Pushing source files
sphinx-document-test_1_0.builders - Uploading file
sphinx-document-test_1_0.builders - Done
#. Forward the translation on Transifex.

Expand All @@ -295,12 +329,18 @@ easy to fetch and push translations.
$ 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.
# Getting info about resources
sphinx-document-test_1_0.builders - Getting info
sphinx-document-test_1_0.builders - Done
# Pulling files
sphinx-document-test_1_0.builders [de] - Pulling file
sphinx-document-test_1_0.builders [de] - Creating download job
sphinx-document-test_1_0.builders [de] - Done
Invoke :command:`make html` (for BSD/GNU make):
Invoke :command:`make html` (for BSD/GNU make) passing the language code:

.. code-block:: console
Expand Down Expand Up @@ -338,7 +378,8 @@ There is a `sphinx translation page`_ for Sphinx (master) documentation.
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
Detail is here:
https://help.transifex.com/en/articles/6248698-getting-started-as-a-translator


Translation progress and statistics
Expand All @@ -364,9 +405,11 @@ percentage of nodes that have been translated on a per-document basis.
for details on that software suite.
.. [2] Because nobody expects the Spanish Inquisition!
.. _`transifex-client`: https://pypi.org/project/transifex-client/
.. _`Transifex CLI tool`: https://https://github.com/transifex/cli/
.. _`sphinx-intl`: https://pypi.org/project/sphinx-intl/
.. _Transifex: https://www.transifex.com/
.. _Transifex: https://app.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/
.. _`sphinx translation page`: https://app.transifex.com/sphinx-doc/sphinx-doc/
.. _`Transifex Client documentation`: https://developers.transifex.com/docs/using-the-client
.. _`Transifex API token`: https://app.transifex.com/user/settings/api/
.. _`sphinx-intl update-txconfig-resources documentation`: https://sphinx-intl.readthedocs.io/en/master/refs.html#sphinx-intl-update-txconfig-resources

0 comments on commit da076d1

Please sign in to comment.