From 257ba5f31e097fe2bfc4a0a25ffd4c915044d9f0 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Mon, 8 Sep 2025 20:09:46 +0100 Subject: [PATCH 1/4] Commit --- documentation/translations/coordinating.rst | 4 +- documentation/translations/translating.rst | 49 ++++++++++++++++++++- 2 files changed, 48 insertions(+), 5 deletions(-) diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index aaed4b831..f28b59bd1 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -175,9 +175,7 @@ Translating Sphinx Some messages that appear in the docs must be translated in the `Sphinx project `__ (`sphinx-doc on Transifex `__) or in -the `python-docs-theme `_ -(currently this is not possible; see this -`issue `__). +the :ref:`python-docs-theme `_. Coordinators should direct some translators there, so that the documentation is fully translated. diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index ebd0dc631..c676f004b 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -209,7 +209,7 @@ Some general guidelines for deciding on a translation: Dialects -------- -Some translation receive contributions from people of several different dialects, +Some translations receive contributions from people of several different dialects, understandably the language will differ. It is recommended however that translators try to keep files and sections consistent. @@ -234,6 +234,8 @@ is provided below: print(kw, ":", keywords[kw]) +.. _transifex-use: + Transifex ========= @@ -241,7 +243,7 @@ Transifex There are many translations in the `python-doc organization on Transifex `_, some of which, however, are not used or do not have a coordination team. - Confirm this is not the case before you begin translating. + Confirm that a coordination team exists before you begin translation. Several language projects use Transifex as their translation interface. Translations on Transifex are carried out via a web interface, similar to Weblate. @@ -258,6 +260,9 @@ through the following resources from the Transifex documentation: - `Starting with the basics `__: A group of documents with basic information. +Within the organization, a project for translating the +`python-docs-theme `_ can also be +found. For further information about Transifex see our `documentation `_. @@ -287,6 +292,46 @@ be the latest non-alpha branch), the translations should then be propagated by your languages coordination team. +.. _python-docs-theme-i18n: + +How do I translate ``python-docs-theme``? +----------------------------------------- + +The Sphinx theme for the Python documentation supports internationalization. + +You can translate either on +`Transifex `_ +(see :ref:`translating on Transifex ` for more information) +or locally by following the steps outlined below. + +To translate locally, clone the ``python-docs-theme`` +`repository `_ and run the following +commands to generate the PO files. Replace ``LANG`` with the same language code +that is used for the docs translation: + +.. code-block:: bash + + python babel_runner.py extract + python babel_runner.py init -l LANG + +The file can then be found at: + +.. code-block:: text + + python-docs-theme/locale/LANG/LC_MESSAGES/python-docs-theme.po + +After translating, submit your PO file via a pull request to the +`repository `_. +See our :ref:`git-boot-camp` for more information about using Git. + +To update an existing translation after source changes, run: + +.. code-block:: bash + + python babel_runner.py update # To update source for all languages + python babel_runner.py update -l LANG # To update source just for LANG + + The coordination team for my language is inactive, what do I do? ---------------------------------------------------------------- From 2fcf57b61309fb1d7a7fdb6af0eb649b9515ca91 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Tue, 9 Sep 2025 14:15:39 +0100 Subject: [PATCH 2/4] Revert wording change Co-authored-by: Lysandros Nikolaou --- documentation/translations/translating.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index c676f004b..e99014d0a 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -243,7 +243,7 @@ Transifex There are many translations in the `python-doc organization on Transifex `_, some of which, however, are not used or do not have a coordination team. - Confirm that a coordination team exists before you begin translation. + Confirm that a coordination team exists before you begin translating. Several language projects use Transifex as their translation interface. Translations on Transifex are carried out via a web interface, similar to Weblate. From 6cf0bf59a5329af661e5fd1ace71fc891c340455 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Tue, 9 Sep 2025 18:40:44 +0100 Subject: [PATCH 3/4] Fix link Co-authored-by: Rafael Fontenelle --- documentation/translations/coordinating.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index f28b59bd1..f6c8dc3db 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -175,7 +175,7 @@ Translating Sphinx Some messages that appear in the docs must be translated in the `Sphinx project `__ (`sphinx-doc on Transifex `__) or in -the :ref:`python-docs-theme `_. +the :ref:`python-docs-theme `. Coordinators should direct some translators there, so that the documentation is fully translated. From 4e4724e7e203980a4094374460105948f64485f1 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Wed, 10 Sep 2025 16:19:24 +0100 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- documentation/translations/coordinating.rst | 2 +- documentation/translations/translating.rst | 13 ++++++------- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index f6c8dc3db..31ab4359e 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -175,7 +175,7 @@ Translating Sphinx Some messages that appear in the docs must be translated in the `Sphinx project `__ (`sphinx-doc on Transifex `__) or in -the :ref:`python-docs-theme `. +the :ref:`Python Docs Sphinx Theme `. Coordinators should direct some translators there, so that the documentation is fully translated. diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index e99014d0a..af86ca803 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -261,7 +261,7 @@ through the following resources from the Transifex documentation: A group of documents with basic information. Within the organization, a project for translating the -`python-docs-theme `_ can also be +:github:`Python Docs Sphinx Theme ` can also be found. For further information about Transifex see our `documentation `_. @@ -294,18 +294,17 @@ your languages coordination team. .. _python-docs-theme-i18n: -How do I translate ``python-docs-theme``? ------------------------------------------ +How do I translate the Python Docs Sphinx Theme? +------------------------------------------------ -The Sphinx theme for the Python documentation supports internationalization. +The Sphinx theme for the Python documentation supports localization. You can translate either on `Transifex `_ (see :ref:`translating on Transifex ` for more information) or locally by following the steps outlined below. -To translate locally, clone the ``python-docs-theme`` -`repository `_ and run the following +To translate locally, clone the :github:`Python Docs Sphinx Theme repository ` and run the following commands to generate the PO files. Replace ``LANG`` with the same language code that is used for the docs translation: @@ -321,7 +320,7 @@ The file can then be found at: python-docs-theme/locale/LANG/LC_MESSAGES/python-docs-theme.po After translating, submit your PO file via a pull request to the -`repository `_. +:github:`repository `. See our :ref:`git-boot-camp` for more information about using Git. To update an existing translation after source changes, run: