From 0509a8ae42aa8cf07282b7c9b52819a62ec82095 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Tue, 25 Nov 2025 03:34:13 +0000 Subject: [PATCH 1/2] Update translation contribution guidance --- doc/internals/contributing.rst | 34 ++++++++++++++++++++++------------ doc/usage/advanced/intl.rst | 7 ++++--- 2 files changed, 26 insertions(+), 15 deletions(-) diff --git a/doc/internals/contributing.rst b/doc/internals/contributing.rst index 90d7600866d..671fae07797 100644 --- a/doc/internals/contributing.rst +++ b/doc/internals/contributing.rst @@ -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 +`__ 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 `__ (``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 `_ 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 @@ -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 -`_. 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 -------------- diff --git a/doc/usage/advanced/intl.rst b/doc/usage/advanced/intl.rst index 4d52c34debe..4ae26f943fb 100644 --- a/doc/usage/advanced/intl.rst +++ b/doc/usage/advanced/intl.rst @@ -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 + `__. 3. Click ``Request language`` and fill form. 4. Wait acceptance by Transifex sphinx translation maintainers. 5. (After acceptance) Translate on Transifex. @@ -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 From 6f889afe6a41b83cfd603700e8cb5b9a210f1b0d Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Tue, 25 Nov 2025 03:35:22 +0000 Subject: [PATCH 2/2] Update doc/internals/contributing.rst --- doc/internals/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/internals/contributing.rst b/doc/internals/contributing.rst index 671fae07797..1a846259461 100644 --- a/doc/internals/contributing.rst +++ b/doc/internals/contributing.rst @@ -287,7 +287,7 @@ 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 -`__ platform. +`__ platform. Translated strings from the platform are pulled into the Sphinx repository by a maintainer before a new release.