Add a section on building a docs translation (python#1661)

StanFromIreland · AA-Turner · rffontenelle · web-flow · commit 622083ee26ef · 2025-10-18T11:58:51.000+03:00
Co-authored-by: Adam Turner &lt;9087854+AA-Turner@users.noreply.github.com&gt;
Co-authored-by: Rafael Fontenelle &lt;rffontenelle@users.noreply.github.com&gt;
Co-authored-by: Hugo van Kemenade &lt;1324225+hugovk@users.noreply.github.com&gt;
diff --git 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 <docs-build-translation>`.
 
 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
@@ -283,6 +283,32 @@ Some useful resources:
 Translation FAQ
 ===============
 
+.. _docs-build-translation:
+
+How do I build a docs translation?
+----------------------------------
+
+To build a documentation translation for a specific language,
+you need to have Python installed and a
+local copy of the :github:`CPython repository <python/cpython>` 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 <doc-build-make>` by adding
+a ``SPHINXOPTS="-D language=LANG"`` variable before the target
+or by using :ref:`Sphinx directly <doc-build-sphinx>` and adding a
+``-D language=LANG`` option. 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?
 -----------------------------------------------------------
 
