Skip to content

Update translation contribution guidance #14083

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 25, 2025
+26 −15
Merged

Update translation contribution guidance #14083

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0509a8a
Update translation contribution guidance
AA-Turner Nov 25, 2025
6f889af
Update doc/internals/contributing.rst
AA-Turner Nov 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 22 additions & 12 deletions doc/internals/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -280,15 +280,34 @@ To do so, use `sphinx-autobuild`_ to run the following command:
.. _sphinx-autobuild: https://github.com/sphinx-doc/sphinx-autobuild

Translations
~~~~~~~~~~~~
------------

The parts of messages in Sphinx that go into builds are translated into several
locales. The translations are kept as gettext ``.po`` files translated from the
master template :file:`sphinx/locale/sphinx.pot`.

These Sphinx core messages are translated using the online `Transifex
<https://explore.transifex.com/sphinx-doc/sphinx-1//>`__ platform.

Translated strings from the platform are pulled into the Sphinx repository
by a maintainer before a new release.

We do not accept pull requests altering the translation files directly.
Instead, please contribute translations via the Transifex platform.

Translations notes for maintainers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The `transifex CLI <https://developers.transifex.com/docs/cli>`__ (``tx``)
can be used to pull translations in ``.po`` format from Transifex.
To do this, go to :file:`sphinx/locale` and then run ``tx pull -f -l LANG``
where ``LANG`` is an existing language identifier.
It is good practice to run ``python utils/babel_runner.py update`` afterwards
to make sure the ``.po`` file has the canonical Babel formatting.

Sphinx uses `Babel <https://babel.pocoo.org/en/latest/>`_ to extract messages
and maintain the catalog files. The :file:`utils` directory contains a helper
script, ``babel_runner.py``.
script, :file:`utils/babel_runner.py`.

* Use ``python babel_runner.py extract`` to update the ``.pot`` template.
* Use ``python babel_runner.py update`` to update all existing language
Expand All @@ -301,19 +320,10 @@ When an updated ``.po`` file is submitted, run
``python babel_runner.py compile`` to commit both the source and the compiled
catalogs.

When a new locale is submitted, add a new directory with the ISO 639-1 language
When a new locale is added, add a new directory with the ISO 639-1 language
identifier and put ``sphinx.po`` in there. Don't forget to update the possible
values for :confval:`language` in :file:`doc/usage/configuration.rst`.

The Sphinx core messages can also be translated on `Transifex
<https://www.transifex.com/sphinx-doc/sphinx-1/>`_. There ``tx`` client tool,
which is provided by the ``transifex_client`` Python package, can be used to
pull translations in ``.po`` format from Transifex. To do this, go to
:file:`sphinx/locale` and then run ``tx pull -f -l LANG`` where ``LANG`` is an
existing language identifier. It is good practice to run
``python babel_runner.py update`` afterwards to make sure the ``.po`` file has the
canonical Babel formatting.


Debugging tips
--------------
Expand Down
7 changes: 4 additions & 3 deletions doc/usage/advanced/intl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -375,10 +375,11 @@ 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.
There is a `Sphinx translation page`_ for Sphinx (master) documentation.

1. Login to Transifex_ service.
2. Go to `sphinx translation page`_.
2. Go to the `"Sphinx's documentation" translation project
<https://app.transifex.com/sphinx-doc/sphinx-doc/>`__.
3. Click ``Request language`` and fill form.
4. Wait acceptance by Transifex sphinx translation maintainers.
5. (After acceptance) Translate on Transifex.
Expand Down Expand Up @@ -414,7 +415,7 @@ percentage of nodes that have been translated on a per-document basis.
.. _`sphinx-intl`: https://pypi.org/project/sphinx-intl/
.. _Transifex: https://app.transifex.com/
.. _Weblate's documentation: https://docs.weblate.org/en/latest/devel/sphinx.html
.. _`sphinx translation page`: https://app.transifex.com/sphinx-doc/sphinx-doc/
.. _`Sphinx translation page`: https://explore.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
Loading