From 366ab56854c53daa745afa03268228ea0772ac54 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Wed, 1 Oct 2025 16:24:36 +0100 Subject: [PATCH 1/6] Commit --- documentation/start-documenting.rst | 2 ++ documentation/translations/translating.rst | 24 ++++++++++++++++++++++ 2 files changed, 26 insertions(+) diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index 7515992ec..7865f125d 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -162,6 +162,8 @@ To build the docs as HTML, run: * Replace ``html`` with ``htmllive`` to rebuild the docs, start a local server, and automatically reload the page in your browser when you make changes to reST files (Unix only). + * To build a documentation translation, see this + :ref:`guide `. It is also possible to build only certain pages of the documentation in order to save time during the build process. Following is an example for building two diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index 7ed46b1bd..4dffbd918 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -283,6 +283,30 @@ Some useful resources: Translation FAQ =============== +.. _docs-build-translation: + +How do I build a docs translation? +---------------------------------- + +To build a documentation translation, you need to have Python installed, and a +local copy of the :github:`CPython repository ` and your +translation's repository (see table above). The PO files must be placed +in a ``locale/LANG/LC_MESSAGES/`` (replacing ``LANG`` with your translation's +language code) folder inside the ``Doc/`` directory of the CPython repository. + +You can then build with :ref:`make ` by adding +a ``SPHINXOPTS="-D language=LANG" argument before the target +or using :ref:`Sphinx directly ` and adding a +``-D language LANG`` argument. For example: + +.. code-block:: bash + + # build the html format of the Polish translation using make + make SPHINXOPTS="-D language=pl" html + # build the html format of the Romanian translation using Sphinx directly + python -m sphinx -b html . build/html -D language=ro + + Which version of the Python documentation should I work on? ----------------------------------------------------------- From 8ba265b4c75c3d910e19299d4b28e03dc69a9bec Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Wed, 1 Oct 2025 16:25:48 +0100 Subject: [PATCH 2/6] Commit --- 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 4dffbd918..380cc7227 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -295,7 +295,7 @@ in a ``locale/LANG/LC_MESSAGES/`` (replacing ``LANG`` with your translation's language code) folder inside the ``Doc/`` directory of the CPython repository. You can then build with :ref:`make ` by adding -a ``SPHINXOPTS="-D language=LANG" argument before the target +a ``SPHINXOPTS="-D language=LANG"`` argument before the target or using :ref:`Sphinx directly ` and adding a ``-D language LANG`` argument. For example: From 1e5aa0362f60969518d270079a943bfc0d108c54 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Thu, 2 Oct 2025 07:23:00 +0100 Subject: [PATCH 3/6] Update documentation/translations/translating.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- documentation/translations/translating.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index 380cc7227..470684555 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -296,8 +296,8 @@ language code) folder inside the ``Doc/`` directory of the CPython repository. You can then build with :ref:`make ` by adding a ``SPHINXOPTS="-D language=LANG"`` argument before the target -or using :ref:`Sphinx directly ` and adding a -``-D language LANG`` argument. For example: +or by using :ref:`Sphinx directly ` and adding a +``-D language=LANG`` argument. For example: .. code-block:: bash From 213a4e9bcf4a66a7290f5177321d1fc2780fb664 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Thu, 2 Oct 2025 07:38:15 +0100 Subject: [PATCH 4/6] Use documented default instead `locale/` works, but `locales/` is documented. Co-authored-by: Rafael Fontenelle --- 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 470684555..136384319 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -291,7 +291,7 @@ How do I build a docs translation? To build a documentation translation, you need to have Python installed, and a local copy of the :github:`CPython repository ` and your translation's repository (see table above). The PO files must be placed -in a ``locale/LANG/LC_MESSAGES/`` (replacing ``LANG`` with your translation's +in a ``locales/LANG/LC_MESSAGES/`` (replacing ``LANG`` with your translation's language code) folder inside the ``Doc/`` directory of the CPython repository. You can then build with :ref:`make ` by adding From 7d5af8c29735c5d2a6217ddd6e8d4e215c1864c4 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Thu, 2 Oct 2025 08:24:30 +0100 Subject: [PATCH 5/6] Update translating.rst Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- 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 136384319..310022b1c 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -288,7 +288,7 @@ Translation FAQ How do I build a docs translation? ---------------------------------- -To build a documentation translation, you need to have Python installed, and a +To build a documentation translation, you need to have Python installed, a local copy of the :github:`CPython repository ` and your translation's repository (see table above). The PO files must be placed in a ``locales/LANG/LC_MESSAGES/`` (replacing ``LANG`` with your translation's From f0ca13aea712b327d58f867a20fefa0ec1e1e5b6 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 4 Oct 2025 16:22:53 +0100 Subject: [PATCH 6/6] Review --- documentation/translations/translating.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index 310022b1c..5f071aa6d 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -288,16 +288,16 @@ Translation FAQ How do I build a docs translation? ---------------------------------- -To build a documentation translation, you need to have Python installed, a -local copy of the :github:`CPython repository ` and your -translation's repository (see table above). The PO files must be placed -in a ``locales/LANG/LC_MESSAGES/`` (replacing ``LANG`` with your translation's -language code) folder inside the ``Doc/`` directory of the CPython repository. +To build a documentation translation, you need to have Python installed and a +local copy of the :github:`CPython repository ` and +translation repository (see table above). The PO files must be placed +in a :samp:`locales/{LANG}/LC_MESSAGES/` (replacing :samp:`{LANG}` with the translation's +language code) folder inside the :file:`Doc/` directory of the CPython repository. You can then build with :ref:`make ` by adding -a ``SPHINXOPTS="-D language=LANG"`` argument before the target +a ``SPHINXOPTS="-D language=LANG"`` variable before the target or by using :ref:`Sphinx directly ` and adding a -``-D language=LANG`` argument. For example: +``-D language=LANG`` option. For example: .. code-block:: bash