From af9fcbcb3c21d42f40e3105a69656daf3f1f9142 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Mon, 23 Jun 2025 10:31:15 +0100 Subject: [PATCH 1/8] Init --- contrib/index.rst | 2 +- documentation/translations/coordinating.rst | 248 +++++++++++++++----- documentation/translations/translating.rst | 11 +- 3 files changed, 198 insertions(+), 63 deletions(-) diff --git a/contrib/index.rst b/contrib/index.rst index b93d36504..f9b54bc56 100644 --- a/contrib/index.rst +++ b/contrib/index.rst @@ -75,7 +75,7 @@ major section at the top of each column.]* * :ref:`documenting` * :ref:`style-guide` * :ref:`rst-primer` - * :doc:`documentation/translations` + * :ref:`translating` * :ref:`devguide` - * :ref:`setup` diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index 4e78b9247..497927716 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -3,47 +3,151 @@ Coordinating ============ Information about the Python documentation translation processes is -found in this devguide and :PEP:`545`. -Translations are built by `docsbuild-scripts -`__ and hosted on -docs.python.org. Translations -are overseen by the `Editorial Board `_ +found on this page and in :PEP:`545`. Translations are overseen by the +`Editorial Board `_. + +.. _translation-help: + +Communication/Help channels +=========================== + +Discussions about translations occur on the Python Docs Discord +`#translations channel `_, `translation +mailing list `_, and the +`translations category `_ of the Python Discourse. + +For administrative issues, ping ``@python/editorial-board``. + +.. XXX May change to @python/translations + Starting a new translation ========================== -First subscribe to the `translation mailing list `_, -and introduce yourself and the translation you're starting. +Coordination is not a once-off task, it is a long term commitment. Before +you start your translation, ask carefully consider if you will be able to commit +to this. +Every coordinator should be familiar with translating, for this you should see +:ref:`translating`. + +The following sections will guide you through setting up your translation. +If you have any questions or need help, ask in one of the +:ref:`help channels `. + + +Announcement +------------ + +You should post an announcement introducing yourself and the translation you're +starting on `Discourse `_. You should also join the other communication +channels if possible. + +.. XXX Discourse is more read and public nowadays, it is probably a better place + +Coordination team +----------------- + +Each translation team will decide on the number of coordinators. +While initially one person is fine, we recommend expanding to having two or +three coordinators. You can find more on choosing coordinators in the FAQ below. + +.. XXX move stuff from the FAQ? + + +Translation team +---------------- + +.. figure:: translator-workload.svg + :class: invert-in-dark-mode + :align: center + :alt: Translator workload chart + +.. XXX chart for emphasis? + +Gather people to help you translate. You can't do it alone. +You should update :ref:`this table ` via a PR to make +your translation easier to find. In the entry you can also include links to +guides or other resources for translators. + + +Repository +---------- + +To start your translation you should create a GitHub repository, under any +account, with the correct git hierarchy and folder structure. This can be done +in several ways, and will dictate the translation process you use. + +The branch name should be the version, for example, ``3.14``, and the files +should be structured like the source files in `CPython/Doc `_. +A correctly set up repository should look like this: `python-docs-pl `_ + + +Cookiecutter/Bootstrapper +~~~~~~~~~~~~~~~~~~~~~~~~~ Then you can bootstrap your new translation by using the `cookiecutter `__ or `bootstrapper `__. -You can also start your translation using `Transifex `_ -following this `guide `_. +The repository can then be used with a pull-request based translation process. -The important steps look like this: -- Create the GitHub repo (any account) with the correct hierarchy by using one - of the bootstrappers or Transifex. -- Gather people to help you translate. You can't do it alone. -- You can use any tool to translate, as long as you can synchronize with Git. - Some use Transifex, and some use only GitHub. You can choose another - way if you like; it's up to you. -- Update :doc:`this page ` to reflect your work and progress, either via a - PR or by asking on the `translation mailing list `_. -- When ``bugs``, ``tutorial``, and ``library/functions`` are 100% - completed, ask on the `translation mailing list `_ for - your language to be added in the language switcher on docs.python.org. +Transifex +~~~~~~~~~ +You can also start your translation using `Transifex `_. +This will automate updating translations, and will allow you to translate via +the web interface. -How to get help -=============== +This is best done with a workflow that periodically checks for translations, +a sample one with instructions can be found `here `__. +An in depth guide for manually doing this can also be found `here `__. -Discussions about translations occur on the Python Docs Discord -`#translations channel `_, `translation -mailing list `_, and the -`translations category `_ -of the Python Discourse. +To be added as the coordinator(s) on Transifex for your language, open an issue +in the `tracker `__. + + +Others +~~~~~~ + +You can choose another way if you like; it’s up to you. Getting it right from +the start will prevent complications in the future when your translation +is built. If complications do occur more information about them can be found +in the FAQ section on this page. + + +Glossary +-------- + +Each translation team should have a way to store translations of terms to ensure +consistency. This is often done with a glossary. More information about the use +of glossaries can be found in the :ref:`translation-style-guide`. + + +Moving the repo to the python org +--------------------------------- + +This will allow you to plug your translation into docsbuild-scripts_, and it +will be found at ``docs.python.org/LANG/``, but not in the switcher. + +This will be done XXX + +.. XXX When ...? Discussion needed... +.. My idea: Time based, e.g. 2 months of activity, showing that they aren't going anywhere + +Adding to the language switcher +------------------------------- + +.. XXX https://github.com/python/devguide/issues/1586 + +Once the following resources have been fully translated on the XXX branch: + - ``bugs.po``, with proper links to the language repository issue tracker + - all files in the ``tutorial/`` folder + - ``library/functions.po``, the page documenting builtins +The translation can be added to the language switcher. This can be done with a +pull request to docsbuild-scripts_, like `this commit `_ +if your translation was previously built but not in the switcher, or like +`this commit `_ +if this is it's initial addition. PEP 545 summary @@ -51,31 +155,37 @@ PEP 545 summary Here are the essential points of :PEP:`545`: -- Each translation is assigned an appropriate lowercased language tag, - with an optional region subtag, and joined with a dash, like - ``pt-br`` or ``fr``. +- Each translation is assigned an appropriate lowercase + `IETF language tag `_. + The tag may have an optional region subtag, joined with a dash. + For example, ``pt`` (Portuguese) or ``pt-br`` (Brazilian Portuguese). -- Each translation is under CC0 and marked as such in the README (as in - the cookiecutter). +- Each translation is under CC0 and is marked as such in the README. - Translation files are hosted on - ``https://github.com/python/python-docs-{LANGUAGE_TAG}`` (not - mandatory to start a translation, but mandatory to land on - ``docs.python.org``). + ``https://github.com/python/python-docs-{LANGUAGE_TAG}`` -- Translations having completed ``tutorial/``, ``library/stdtypes`` - and ``library/functions`` are hosted on - ``https://docs.python.org/{LANGUAGE_TAG}/{VERSION_TAG}/``. +.. XXX this is the same as the "Moving the repo to the python org" question + +- Translations having completed ``bugs``, ``tutorial/`` + and ``library/functions`` are added to the language switcher. Transifex ========= -If you need help from a Transifex administrator, open an issue on the +`Transifex `_ is an +online translations platform, similar to Weblate. It is currently used by +several translations. + +If you need assistance from a Transifex administrator, open an issue on the `tracker `_. +.. seealso:: -Coordinating FAQ + `python-docs-transifex-automations: documentation `_ + +Coordination FAQ ================ Are there tools to help in managing the repo? @@ -96,12 +206,26 @@ More related tools and projects can be found in the __ https://github.com/python-docs-translations -How is a coordinator elected? ------------------------------ + +How should I test my translation? +--------------------------------- + +The `dashboard `_ +tests translations and uploads error logs. + +Testing should ideally be set up in your repository, and will help catch errors +early and ensure translation quality. Testing generally consists of building, and +linting with :pypi:`sphinx-lint`. + +See `this documentation `_ +for sample workflows with usage guides. + + +How is a coordination team chosen? +---------------------------------- Each translation team will decide on the number of coordinators. We recommend two or three coordinators, though you may begin with one. -Here are some general suggestions. - Coordinator requests are to be public on the `translation mailing list `_. - If the given language has a native core dev, the core dev has input @@ -112,25 +236,28 @@ Here are some general suggestions. - We expect the local community to self-organize coordinators and contributors. If you have questions, please ask on the mailing list or Discourse. - If a coordinator becomes inactive or unreachable for a long - period of time, someone else can ask to be added as a primary coordinator on the `translation mailing list `_. - As a community resource, we aim to keep translations up to date with active contributors, including coordinators. + period of time, someone else can ask to be added as a primary coordinator on + the `translation mailing list `_. + As a community resource, we aim to keep translations up to date with active + contributors, including coordinators. + I have a translation, but it's not in Git. What should I do? ------------------------------------------------------------ -You can ask for help on the `translation mailing list `_, and -the team will help you create an appropriate repository. You can still use tools like transifex, -if you like. +You can ask for help in one of the :ref:`translation-help`, and +the team will help you create an appropriate repository. You can still use tools +like transifex, if you like. My Git hierarchy does not match yours. Can I keep it? ----------------------------------------------------- -No, inside the ``github.com/python`` organization we’ll all have the +No, inside the ``github.com/python`` organization all repositories must have the exact same hierarchy so bots will be able to build all of our -translations. So you may have to convert from one hierarchy to another. -Ask for help on the `translation mailing list `_ if you’re -not sure on how to do it. +translations. So, you may have to convert from one hierarchy to another. +Ask for help in one of the :ref:`translation-help` if you’re not sure on how to +do it. What hierarchy should I use in my GitHub repository? @@ -141,9 +268,6 @@ files in the root of the repository using the ``gettext_compact=0`` style. -.. XXX Explain necessary folder structure - - Which version of the Python documentation should be translated? --------------------------------------------------------------- @@ -154,8 +278,14 @@ propagate your translation from one branch to another using :pypi:`pomerge`. The entry for my translation is missing or not up to date --------------------------------------------------------- -Ask on the `translation mailing list `_, or better, make a PR -on the `devguide `__. +Make a PR on the `devguide `__ to update it. + + +How are translations built? +--------------------------- + +Translations are built by `docsbuild-scripts `__ +and hosted on docs.python.org. Is there a Weblate instance we can translate on? @@ -168,3 +298,5 @@ for updates. .. _EB: https://python.github.io/editorial-board/ .. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/ +.. _trans_disc: https://discuss.python.org/c/documentation/translations/ +.. _docsbuild-scripts: https://github.com/python/docsbuild-scripts diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index 7d1e2f251..09e4e6f6c 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -1,3 +1,5 @@ +.. _translating: + =========== Translating =========== @@ -9,7 +11,7 @@ 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! -See :doc:`coordinating` guide to get started. +See :doc:`coordination ` to get started. For more details about translations and their progress, see `the dashboard `__. @@ -124,12 +126,13 @@ General discussions about translations occur on the Python Docs Discord mailing list `_, and the `translations category <_discourse>`_ of the Python Discourse. +.. _translation-style-guide: Style guide =========== Before translating, you should familiarize yourself with the general -documentation :doc:`style guide<../style-guide>`. Some translation-specific +documentation :doc:`style guide <../style-guide>`. Some translation-specific guidelines are explained below. @@ -277,8 +280,8 @@ The coordination team for my language is inactive, what do I do? ---------------------------------------------------------------- If you would like to coordinate, open a pull request in the -`devguide `_ adding yourself, and ping -``@python/editorial-board``. +`devguide `_ adding yourself to the table +at the top of this page, and ping ``@python/editorial-board``. .. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/ From 9b7cbd23a6cb6b07a4528ccce26aac56ce0fe2fb Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 24 Jun 2025 10:47:04 +0100 Subject: [PATCH 2/8] Some cleanup --- documentation/translations/coordinating.rst | 9 +- .../translations/translator-workload.svg | 9255 +++++++++++++++++ 2 files changed, 9257 insertions(+), 7 deletions(-) create mode 100644 documentation/translations/translator-workload.svg diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index 497927716..c0835cae4 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -18,8 +18,6 @@ mailing list `_, and the For administrative issues, ping ``@python/editorial-board``. -.. XXX May change to @python/translations - Starting a new translation ========================== @@ -42,7 +40,6 @@ You should post an announcement introducing yourself and the translation you're starting on `Discourse `_. You should also join the other communication channels if possible. -.. XXX Discourse is more read and public nowadays, it is probably a better place Coordination team ----------------- @@ -62,7 +59,6 @@ Translation team :align: center :alt: Translator workload chart -.. XXX chart for emphasis? Gather people to help you translate. You can't do it alone. You should update :ref:`this table ` via a PR to make @@ -162,11 +158,9 @@ Here are the essential points of :PEP:`545`: - Each translation is under CC0 and is marked as such in the README. -- Translation files are hosted on +- Translation files are hosted in repositories under the Python org: ``https://github.com/python/python-docs-{LANGUAGE_TAG}`` -.. XXX this is the same as the "Moving the repo to the python org" question - - Translations having completed ``bugs``, ``tutorial/`` and ``library/functions`` are added to the language switcher. @@ -185,6 +179,7 @@ If you need assistance from a Transifex administrator, open an issue on the `python-docs-transifex-automations: documentation `_ + Coordination FAQ ================ diff --git a/documentation/translations/translator-workload.svg b/documentation/translations/translator-workload.svg new file mode 100644 index 000000000..e0f00b2f6 --- /dev/null +++ b/documentation/translations/translator-workload.svg @@ -0,0 +1,9255 @@ + + + + + + + + 2025-06-22T11:16:20.092741 + image/svg+xml + + + Matplotlib v3.10.0, https://matplotlib.org/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From 9992fe7399195b99a7aabbeb8d127691f63ccd00 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Wed, 25 Jun 2025 09:02:39 +0100 Subject: [PATCH 3/8] Review + Lint --- documentation/translations/coordinating.rst | 16 +- .../translations/translator-workload.svg | 18220 ++++++++-------- 2 files changed, 9119 insertions(+), 9117 deletions(-) diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index c0835cae4..8cab46448 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -23,7 +23,7 @@ Starting a new translation ========================== Coordination is not a once-off task, it is a long term commitment. Before -you start your translation, ask carefully consider if you will be able to commit +you start your translation, carefully consider if you will be able to commit to this. Every coordinator should be familiar with translating, for this you should see :ref:`translating`. @@ -136,13 +136,15 @@ Adding to the language switcher .. XXX https://github.com/python/devguide/issues/1586 Once the following resources have been fully translated on the XXX branch: - - ``bugs.po``, with proper links to the language repository issue tracker - - all files in the ``tutorial/`` folder - - ``library/functions.po``, the page documenting builtins + +- ``bugs.po``, with proper links to the language repository issue tracker +- all files in the ``tutorial/`` folder +- ``library/functions.po``, the page documenting builtins + The translation can be added to the language switcher. This can be done with a -pull request to docsbuild-scripts_, like `this commit `_ +pull request to docsbuild-scripts_, like `this commit `__ if your translation was previously built but not in the switcher, or like -`this commit `_ +`this commit `__ if this is it's initial addition. @@ -242,7 +244,7 @@ I have a translation, but it's not in Git. What should I do? You can ask for help in one of the :ref:`translation-help`, and the team will help you create an appropriate repository. You can still use tools -like transifex, if you like. +like Transifex, if you like. My Git hierarchy does not match yours. Can I keep it? diff --git a/documentation/translations/translator-workload.svg b/documentation/translations/translator-workload.svg index e0f00b2f6..b0285378e 100644 --- a/documentation/translations/translator-workload.svg +++ b/documentation/translations/translator-workload.svg @@ -21,9228 +21,9228 @@ - - - - - - - - - - - - - - From 538d9e6bb8b0a8193dbd2d884c6f7e89dafcfda1 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Thu, 26 Jun 2025 11:23:19 +0100 Subject: [PATCH 4/8] Add Sphinx-core TX section --- documentation/translations/coordinating.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index 8cab46448..1adf5f443 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -167,6 +167,21 @@ Here are the essential points of :PEP:`545`: and ``library/functions`` are added to the language switcher. +Translating Sphinx +================== + +Some messages that appear in the docs can not be translated, this is because they +are either part of the theme, which currently cannot be translated (see this +`issue `__) or it is +part of Sphinx, which requires it to be translated in the +`sphinx-doc Transifex `__. +Coordinators should direct some translators there, so that the documentation +is fully translated. + +.. Where should this go? Coordinators or Translators +.. Should we share coordinators? + + Transifex ========= From 9960fd3e4d66811f66e894f14595e6a433c5594d Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Thu, 26 Jun 2025 11:28:33 +0100 Subject: [PATCH 5/8] Grammar --- documentation/translations/coordinating.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index 1adf5f443..8b09eeacc 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -172,8 +172,8 @@ Translating Sphinx Some messages that appear in the docs can not be translated, this is because they are either part of the theme, which currently cannot be translated (see this -`issue `__) or it is -part of Sphinx, which requires it to be translated in the +`issue `__), +they are part of Sphinx, which requires them to be translated in the `sphinx-doc Transifex `__. Coordinators should direct some translators there, so that the documentation is fully translated. From acdfd0a425c3b935421f7b44e79f9805962cb514 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Fri, 27 Jun 2025 14:45:30 +0100 Subject: [PATCH 6/8] Hugo's Review --- documentation/translations/coordinating.rst | 26 ++++++++++----------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index 8b09eeacc..91bcd9159 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -8,7 +8,7 @@ found on this page and in :PEP:`545`. Translations are overseen by the .. _translation-help: -Communication/Help channels +Communication/help channels =========================== Discussions about translations occur on the Python Docs Discord @@ -22,11 +22,10 @@ For administrative issues, ping ``@python/editorial-board``. Starting a new translation ========================== -Coordination is not a once-off task, it is a long term commitment. Before +Coordination is not a one-off task, it is a long-term commitment. Before you start your translation, carefully consider if you will be able to commit to this. -Every coordinator should be familiar with translating, for this you should see -:ref:`translating`. +Every coordinator should be familiar with translating: see :ref:`translating`. The following sections will guide you through setting up your translation. If you have any questions or need help, ask in one of the @@ -36,9 +35,9 @@ If you have any questions or need help, ask in one of the Announcement ------------ -You should post an announcement introducing yourself and the translation you're -starting on `Discourse `_. You should also join the other communication -channels if possible. +Post an announcement introducing yourself and the translation you're +starting on `Discourse `_. Also join the other communication +channels, if possible. Coordination team @@ -57,11 +56,12 @@ Translation team .. figure:: translator-workload.svg :class: invert-in-dark-mode :align: center - :alt: Translator workload chart + :alt: An exaggerated chart showing that individual translator workload + decreases with the amount of translators. Gather people to help you translate. You can't do it alone. -You should update :ref:`this table ` via a PR to make +Update :ref:`this table ` via a PR to make your translation easier to find. In the entry you can also include links to guides or other resources for translators. @@ -69,16 +69,16 @@ guides or other resources for translators. Repository ---------- -To start your translation you should create a GitHub repository, under any -account, with the correct git hierarchy and folder structure. This can be done +To start your translation create a GitHub repository, under any +account, with the correct Git hierarchy and folder structure. This can be done in several ways, and will dictate the translation process you use. The branch name should be the version, for example, ``3.14``, and the files should be structured like the source files in `CPython/Doc `_. -A correctly set up repository should look like this: `python-docs-pl `_ +A correctly set up repository looks like this: `python-docs-pl `_ -Cookiecutter/Bootstrapper +Cookiecutter/bootstrapper ~~~~~~~~~~~~~~~~~~~~~~~~~ Then you can bootstrap your new translation by using the `cookiecutter From 04d376108f38a6fd9faf17fdbf6fa68fcc3f24f3 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 28 Jun 2025 16:09:33 +0100 Subject: [PATCH 7/8] Ezio's review --- documentation/translations/coordinating.rst | 33 ++++++++++++++------- documentation/translations/translating.rst | 2 +- 2 files changed, 24 insertions(+), 11 deletions(-) diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index 91bcd9159..967c7aad1 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -73,15 +73,23 @@ To start your translation create a GitHub repository, under any account, with the correct Git hierarchy and folder structure. This can be done in several ways, and will dictate the translation process you use. -The branch name should be the version, for example, ``3.14``, and the files -should be structured like the source files in `CPython/Doc `_. -A correctly set up repository looks like this: `python-docs-pl `_ +Each translation is assigned an appropriate lowercase +`IETF language tag `_. +The tag may have an optional region subtag, joined with a dash. +For example, ``pt`` (Portuguese) or ``pt-br`` (Brazilian Portuguese). +The repository name is then: ``python-docs-TAG`` + +The name of each branch should be the Python version it holds translations +for, for example, ``3.14``. The files should be structured like the source files +in `CPython/Doc `_. +A correctly set up repository looks like this: +`python-docs-pl `_ Cookiecutter/bootstrapper ~~~~~~~~~~~~~~~~~~~~~~~~~ -Then you can bootstrap your new translation by using the `cookiecutter +You can bootstrap your new translation by using the `cookiecutter `__ or `bootstrapper `__. The repository can then be used with a pull-request based translation process. @@ -90,13 +98,17 @@ The repository can then be used with a pull-request based translation process. Transifex ~~~~~~~~~ -You can also start your translation using `Transifex `_. +You can also start your translation using +`Transifex `_. This will automate updating translations, and will allow you to translate via the web interface. This is best done with a workflow that periodically checks for translations, -a sample one with instructions can be found `here `__. -An in depth guide for manually doing this can also be found `here `__. +a sample one with instructions can be found in the +`python-docs-tx-automations documentation `__. +An in depth guide for manually doing this can also be found +python-docs-tx-automations documentation's +`commands page `__. To be added as the coordinator(s) on Transifex for your language, open an issue in the `tracker `__. @@ -119,8 +131,8 @@ consistency. This is often done with a glossary. More information about the use of glossaries can be found in the :ref:`translation-style-guide`. -Moving the repo to the python org ---------------------------------- +Moving the repo to the ``python`` org +------------------------------------- This will allow you to plug your translation into docsbuild-scripts_, and it will be found at ``docs.python.org/LANG/``, but not in the switcher. @@ -194,7 +206,8 @@ If you need assistance from a Transifex administrator, open an issue on the .. seealso:: - `python-docs-transifex-automations: documentation `_ + `python-docs-transifex-automations: documentation + `_ Coordination FAQ diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index 09e4e6f6c..dce6becfc 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -158,7 +158,7 @@ The Python docs contain many roles (``:role:`target```) that link to other parts of the documentation. Do not translate reStructuredText roles targets, such as ``:func:`print``` or ``:ref:`some-section``` because it will break the link. -If alternate text (``:role:`text ``` is provided, it generally +If alternate text (``:role:`text ```) is provided, it generally should be translated. You can also introduce alternate text for translation if the target is not a name or term. From cb2ef3b855b865e3ea24e79c9ccc62c47b8ba755 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sun, 29 Jun 2025 11:17:22 +0100 Subject: [PATCH 8/8] Maciej's review --- documentation/translations/coordinating.rst | 81 +- documentation/translations/index.rst | 2 +- .../translations/translator-workload.svg | 9438 +---------------- 3 files changed, 215 insertions(+), 9306 deletions(-) diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index 967c7aad1..9cb5e9828 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -45,9 +45,8 @@ Coordination team Each translation team will decide on the number of coordinators. While initially one person is fine, we recommend expanding to having two or -three coordinators. You can find more on choosing coordinators in the FAQ below. - -.. XXX move stuff from the FAQ? +three coordinators. You can find more on choosing coordinators in the FAQ +section on this page. Translation team @@ -60,10 +59,10 @@ Translation team decreases with the amount of translators. -Gather people to help you translate. You can't do it alone. -Update :ref:`this table ` via a PR to make -your translation easier to find. In the entry you can also include links to -guides or other resources for translators. +Gather people to translate with you. You can't do it alone. +Update :ref:`this table ` via a PR on the devguide +to make your translation easier to find. In the entry you can also include links +to guides or other resources for translators. Repository @@ -71,11 +70,11 @@ Repository To start your translation create a GitHub repository, under any account, with the correct Git hierarchy and folder structure. This can be done -in several ways, and will dictate the translation process you use. +in several ways, and depends on what translation process you plan to use. Each translation is assigned an appropriate lowercase `IETF language tag `_. -The tag may have an optional region subtag, joined with a dash. +The tag may have an optional subtag, joined with a dash. For example, ``pt`` (Portuguese) or ``pt-br`` (Brazilian Portuguese). The repository name is then: ``python-docs-TAG`` @@ -85,6 +84,9 @@ in `CPython/Doc `_. A correctly set up repository looks like this: `python-docs-pl `_ +Below, the recommended ways for starting your repository are described. You can +choose another way if you like; it’s up to you. + Cookiecutter/bootstrapper ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -95,34 +97,25 @@ You can bootstrap your new translation by using the `cookiecutter The repository can then be used with a pull-request based translation process. -Transifex -~~~~~~~~~ +Translation platform +~~~~~~~~~~~~~~~~~~~~ You can also start your translation using `Transifex `_. -This will automate updating translations, and will allow you to translate via -the web interface. +This will allow you to translate via the web interface, and to use shared +automatically updated source files. This is best done with a workflow that periodically checks for translations, a sample one with instructions can be found in the `python-docs-tx-automations documentation `__. An in depth guide for manually doing this can also be found -python-docs-tx-automations documentation's +in the same documentation's `commands page `__. To be added as the coordinator(s) on Transifex for your language, open an issue in the `tracker `__. -Others -~~~~~~ - -You can choose another way if you like; it’s up to you. Getting it right from -the start will prevent complications in the future when your translation -is built. If complications do occur more information about them can be found -in the FAQ section on this page. - - Glossary -------- @@ -137,17 +130,15 @@ Moving the repo to the ``python`` org This will allow you to plug your translation into docsbuild-scripts_, and it will be found at ``docs.python.org/LANG/``, but not in the switcher. -This will be done XXX - .. XXX When ...? Discussion needed... .. My idea: Time based, e.g. 2 months of activity, showing that they aren't going anywhere Adding to the language switcher ------------------------------- -.. XXX https://github.com/python/devguide/issues/1586 +.. XXX Specify branch: https://github.com/python/devguide/issues/1586 -Once the following resources have been fully translated on the XXX branch: +Once the following resources have been fully translated: - ``bugs.po``, with proper links to the language repository issue tracker - all files in the ``tutorial/`` folder @@ -182,33 +173,15 @@ Here are the essential points of :PEP:`545`: Translating Sphinx ================== -Some messages that appear in the docs can not be translated, this is because they -are either part of the theme, which currently cannot be translated (see this -`issue `__), -they are part of Sphinx, which requires them to be translated in the -`sphinx-doc Transifex `__. +Some messages that appear in the docs must be translated in the +`Sphinx project `__ +(`sphinx-doc on Transifex `__) or in +the `python-docs-theme `_ +(currently this is not possible; see this +`issue `__). Coordinators should direct some translators there, so that the documentation is fully translated. -.. Where should this go? Coordinators or Translators -.. Should we share coordinators? - - -Transifex -========= - -`Transifex `_ is an -online translations platform, similar to Weblate. It is currently used by -several translations. - -If you need assistance from a Transifex administrator, open an issue on the -`tracker `_. - -.. seealso:: - - `python-docs-transifex-automations: documentation - `_ - Coordination FAQ ================ @@ -235,9 +208,6 @@ __ https://github.com/python-docs-translations How should I test my translation? --------------------------------- -The `dashboard `_ -tests translations and uploads error logs. - Testing should ideally be set up in your repository, and will help catch errors early and ensure translation quality. Testing generally consists of building, and linting with :pypi:`sphinx-lint`. @@ -245,6 +215,9 @@ linting with :pypi:`sphinx-lint`. See `this documentation `_ for sample workflows with usage guides. +The `dashboard `_ +also tests translations and uploads error logs. + How is a coordination team chosen? ---------------------------------- diff --git a/documentation/translations/index.rst b/documentation/translations/index.rst index 2f5cfe0f4..a6d4dc4e7 100644 --- a/documentation/translations/index.rst +++ b/documentation/translations/index.rst @@ -3,7 +3,7 @@ Translations ============ .. toctree:: - :maxdepth: 3 + :maxdepth: 4 translating coordinating diff --git a/documentation/translations/translator-workload.svg b/documentation/translations/translator-workload.svg index b0285378e..e3e131861 100644 --- a/documentation/translations/translator-workload.svg +++ b/documentation/translations/translator-workload.svg @@ -1,9255 +1,191 @@ - - - - - - - - 2025-06-22T11:16:20.092741 - image/svg+xml - - - Matplotlib v3.10.0, https://matplotlib.org/ - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + 2025-06-29T10:46:39.952440 + image/svg+xml + + + Matplotlib v3.10.3, https://matplotlib.org/ + + + + + + + + + + + + - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - + + + + + + + + +