Add a section on building a docs translation

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

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 <python/cpython>` 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.
+
+You can then build with :ref:`make <doc-build-make>` by adding
+a ``SPHINXOPTS="-D language=LANG"`` argument before the target
+or by using :ref:`Sphinx directly <doc-build-sphinx>` 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?
 -----------------------------------------------------------