From db9df08b4c17b0e738f04618724e0a1e6aaafe6a Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Mon, 24 Nov 2025 20:40:14 +0000 Subject: [PATCH 1/2] Add FAQ entry on merging --- documentation/translations/translating.rst | 46 ++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index 6252add5a..abe69ca5f 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -361,5 +361,51 @@ If you would like to coordinate, open a pull request in the at the top of this page, and ping ``@python/editorial-board``. +How do I merge translations back in after docs are moved? +--------------------------------------------------------- + +When docs are moved in the CPython repository, translated messages are not +moved automatically and will be lost. +They can be recovered by merging them into the new locations. +Note that this is not necessary for Transifex-based translations, as Transifex's +translation memory will automatically copy them over. + +The :pypi:`pomerge` tool merges translations between PO files by matching +message, regardless of file paths. To use it, first install the package: + +.. code-block:: bash + + pip install pomerge + +Then, merge translations from a specific commit (replace :samp:`{COMMIT_HASH}` +with the commit hash from before the files were moved): + +.. TODO: Provide Windows instructions. + +.. tab:: Unix + + .. code-block:: bash + + # These commands are to be run in the root of the translation repo + + # Check out a commit before the move + git checkout COMMIT_HASH -- . + + # Copy translations to a temporary dir + cp -r . /tmp/old-po-files + + # Return to the current version + git checkout HEAD -- . + + # Merge translations from temporary dir back in + pomerge --from /tmp/old-po-files/**/*.po --to **/*.po --clear + + # Clean up temporary dir + rm -rf /tmp/old-po-files + +After running ``pomerge``, review the changes and commit the updated files. +You may also need to rewrap the lines (see :pypi:`powrap`). + + .. _discourse: https://discuss.python.org/c/documentation/translations/ .. _tx: https://explore.transifex.com/python-doc/python-newest/ From d1260185ddc688c2518c1838973b1fc362e2c871 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Mon, 24 Nov 2025 20:42:58 +0000 Subject: [PATCH 2/2] Fix typo --- 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 abe69ca5f..29ad01ebc 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -371,7 +371,7 @@ Note that this is not necessary for Transifex-based translations, as Transifex's translation memory will automatically copy them over. The :pypi:`pomerge` tool merges translations between PO files by matching -message, regardless of file paths. To use it, first install the package: +messages, regardless of file paths. To use it, first install the package: .. code-block:: bash