diff --git a/documentation/translations/overview.svg b/documentation/translations/overview.svg new file mode 100644 index 000000000..25442e2a8 --- /dev/null +++ b/documentation/translations/overview.svg @@ -0,0 +1,4 @@ + + +Extract stringsTranslateUploadBuild translationPublishDocumentationDocsbuild-scriptsTranslationrepositoryTranslationPO files diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index ab5409522..afa1bcf4d 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -6,8 +6,8 @@ Translating .. highlight:: rest -There are several documentation translations already -in production and can be found in the language switcher; others are works in +Several documentation translations are already in production and can be found +in the language switcher; others are works in progress. To get started read your repository's contributing guide, which is generally the ``README`` file, and this page. If your language isn’t listed below, feel free to start the translation! @@ -133,6 +133,31 @@ For more details about translations and their progress, see `Transifex `_ +Overview +======== + +.. figure:: overview.svg + :align: center + :alt: Strings are extracted from the documentation into PO files, + translated, uploaded to the translation repository, built by + docsbuild-scripts, and published. + +.. Drawn with Excalidraw: https://excalidraw.com/#json=BW3zGCjAbXv3-r77UZYwH,7wHyBLCvHV81DexlAiVrHA + +Roughly, translation works as follows: + +- Translators work on gettext PO file catalogs generated from the Python docs + by Sphinx, rather than editing the documentation directly. +- Teams work in different ways. For example, some have translators work + locally, while others use tools like :ref:`Transifex `. + Messages without a translation fall back to English, so a translation can be + published before it is complete. +- Translations are committed to the :ref:`translation repository `. +- Completed translations are automatically pulled in from the repository by + :github:`docsbuild-scripts ` and published to + docs.python.org. + + How to get help ===============