Update `translations/coordinating.rst` #1587

StanFromIreland · 2025-06-23T09:37:51Z

This page is aimed at coordinators, so I assume some git/gh knowledge etc.

Some things that need to be discussed:

Use Discourse for announcements as it is public (more accessibly for translators), and has more readers nowadays?
Add some general point for when translations are moved under the python org, because this is quite important it should be noted?
Issue: Add version requirements to the translation section of the dev guide #1586

📚 Documentation preview 📚: https://cpython-devguide--1587.org.readthedocs.build/

StanFromIreland · 2025-06-24T09:37:52Z

documentation/translations/coordinating.rst

+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


EB It would be nice to note something here.

StanFromIreland · 2025-06-24T19:06:34Z

While this has to wait for a pending issue, other discussion should continue. These are comments I left in the file in the format, XXX thought.

Requesting @rffontenelle and @m-aciek

rffontenelle

Thanks for improving the docs. Please find some notes below

documentation/translations/coordinating.rst

rffontenelle · 2025-06-24T20:00:52Z

documentation/translations/coordinating.rst

+.. XXX https://github.com/python/devguide/issues/1586
+
+Once the following resources have been fully translated on the XXX branch:


I guess these XXX requires closing that issue before merging this? Alternatively, you could use a text that doesn't mention which branch, and leave the branch requirement for another PR.

rffontenelle · 2025-06-24T20:02:35Z

documentation/translations/coordinating.rst

+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?


XXX to be solved before merging

Yes that is the goal

If we cannot find a resolution in reasonable time, I'll fallback to neutral wording and we'll do it in a follow up.

hugovk

Partial review

documentation/translations/coordinating.rst

StanFromIreland · 2025-06-27T13:46:16Z

Thanks for the review.

I should have my editor highlight it in red:-)

ezio-melotti · 2025-06-28T12:18:28Z

documentation/translations/coordinating.rst

+.. figure:: translator-workload.svg
+   :class: invert-in-dark-mode
+   :align: center
+   :alt: An exaggerated chart showing that individual translator workload
+         decreases with the amount of translators.
+


I'm not sure we need an image to explain the concept of "translating is easier if there are more people to do it" (and after a certain point it might get more difficult again if there are too many translators to coordinate).

I added it for emphasis, but if the general consensus is against it I am happy to remove it.

I think I personally like the figure, a bit of exaggeration here may be suggestive, to motivate to form a team. I think I remember Julien writing on some mailing list, that for one person translating whole documentation is a work for 40 years, or similar?

I would add arrows on the axes, to express the direction of growth, as there's no scale.

And change Translators to Number of translators?

documentation/translations/coordinating.rst

ezio-melotti · 2025-06-28T12:34:26Z

documentation/translations/coordinating.rst

+The branch name should be the version, for example, ``3.14``, and the files
+should be structured like the source files in `CPython/Doc <https://github.com/python/cpython/tree/main/Doc>`_.
+A correctly set up repository looks like this: `python-docs-pl <https://github.com/python/python-docs-pl/>`_


The first sentence is not very clear. Should there be only one branch? Should it match the latest released version, or the in-development version? Should it replace main or be created in addition to main? Can there be multiple branches?
In addition, I think it might be worth specifying the name of the repo as well (python-docs-xx, where xx is the language code.

Should there be only one branch?

I will try to find a better wording, though this is for a new translation, so they will most likely start with one anyway.

Should it match the latest released version, or the in-development version?

That is an ongoing discussion in the linked issue, and is currently covered in the FAQ.

Should it replace main or be created in addition to main?

I don't think there is a need to cover that, whether they want to keep it or not is up to them, only the location for the actual translation files is required for it to be built.

documentation/translations/coordinating.rst

ezio-melotti · 2025-06-28T13:00:57Z

documentation/translations/coordinating.rst

+is fully translated.
+
+.. Where should this go? Coordinators or Translators
+.. Should we share coordinators?


 Transifex
 =========


There's already a section about Transifex above, maybe the two could be merged or this could become a subsection/aside?

Yes, though that one falls under Starting a new translation, whereas this section is relevant for all coordinators. I will wait and see what the others think. I'm just worried people (existing coordinators) will miss/ignore it if it is merged.

I would also merge those.

documentation/translations/coordinating.rst

m-aciek · 2025-06-28T21:42:08Z

documentation/translations/coordinating.rst

+         decreases with the amount of translators.
+
+
+Gather people to help you translate. You can't do it alone.


Suggested change

Gather people to help you translate. You can't do it alone.

Gather people to translate with you. You can't do it alone.

m-aciek · 2025-06-28T21:47:10Z

documentation/translations/coordinating.rst

+.. figure:: translator-workload.svg
+   :class: invert-in-dark-mode
+   :align: center
+   :alt: An exaggerated chart showing that individual translator workload
+         decreases with the amount of translators.
+


I think I personally like the figure, a bit of exaggeration here may be suggestive, to motivate to form a team. I think I remember Julien writing on some mailing list, that for one person translating whole documentation is a work for 40 years, or similar?

I would add arrows on the axes, to express the direction of growth, as there's no scale.

And change Translators to Number of translators?

m-aciek · 2025-06-28T21:47:34Z

documentation/translations/coordinating.rst

+
+
+Gather people to help you translate. You can't do it alone.
+Update :ref:`this table <translation-coordinators>` via a PR to make


Suggested change

Update :ref:`this table <translation-coordinators>` via a PR to make

Update :ref:`this table <translation-coordinators>` via a devguide PR to make

m-aciek · 2025-06-28T21:54:29Z

documentation/translations/coordinating.rst

+account, with the correct Git hierarchy and folder structure. This can be done
+in several ways, and will dictate the translation process you use.


Suggested change

account, with the correct Git hierarchy and folder structure. This can be done

in several ways, and will dictate the translation process you use.

account, with the correct Git hierarchy and folder structure. This can be done

in several ways, depending of what translation process you use.

I don't think that the way of spawning the file structure really dictates you the flow. Only when you start translation in a given flow, then you are dependent. In case of translation platform, not to lose translators work, or not to override with empty data.

m-aciek · 2025-06-28T21:57:28Z

documentation/translations/coordinating.rst

+
+Each translation is assigned an appropriate lowercase
+`IETF language tag <https://datatracker.ietf.org/doc/html/rfc5646.html>`_.
+The tag may have an optional region subtag, joined with a dash.


Suggested change

The tag may have an optional region subtag, joined with a dash.

The tag may have an optional subtag, joined with a dash.

the subtag doesn't need to be related to a region, it may be for a script variants (e.g. zh-hant and zh-hans that are used in Django docs translations)

m-aciek · 2025-06-28T22:42:03Z

documentation/translations/coordinating.rst

+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`.


Suggested change

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`.

We encourage each translation team to 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`.

Spanish translation doesn't have a glossary as far as I'm concerned.

m-aciek · 2025-06-28T22:56:57Z

documentation/translations/coordinating.rst

+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 <https://github.com/python/python-docs-theme/issues/194>`__),
+they are part of Sphinx, which requires them to be translated in the
+`sphinx-doc Transifex <https://app.transifex.com/sphinx-doc/>`__.
+Coordinators should direct some translators there, so that the documentation
+is fully translated.


Suggested change

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 <https://github.com/python/python-docs-theme/issues/194>`__),

they are part of Sphinx, which requires them to be translated in the

`sphinx-doc Transifex <https://app.transifex.com/sphinx-doc/>`__.

Coordinators should direct some translators there, so that the documentation

is fully translated.

Translating Sphinx and the theme

================================

Some messages that appear in the docs should be translated in

`Sphinx project <https://www.sphinx-doc.org/en/master/internals/contributing.html#translations>`__

(`sphinx-doc on Transifex <https://app.transifex.com/sphinx-doc/>`__)

or in `the theme project <https://github.com/python/python-docs-theme/issues/194>`__.

suggestion:

make it less time-dependent (the status of 194 issue in theme)

link to the official documentation

m-aciek · 2025-06-28T23:02:22Z

documentation/translations/coordinating.rst

+Cookiecutter/bootstrapper
+~~~~~~~~~~~~~~~~~~~~~~~~~


I'd make this and Translations platform / Transifex sections have the same level as Repository

m-aciek · 2025-06-28T23:03:31Z

documentation/translations/coordinating.rst

+is fully translated.
+
+.. Where should this go? Coordinators or Translators
+.. Should we share coordinators?


 Transifex
 =========


I would also merge those.

m-aciek · 2025-06-28T23:06:00Z

documentation/translations/coordinating.rst

+---------------------------------
+
+The `dashboard <https://python-docs-translations.github.io/dashboard/metadata.html>`_
+tests translations and uploads error logs.


Suggested change

tests translations and uploads error logs.

provides build warnings and lint errors for translation projects.

I'd move this sentence at the end of the section, as it doesn't really answer the question.

Init

af9fcbc

StanFromIreland requested a review from willingc June 23, 2025 09:37

StanFromIreland mentioned this pull request Jun 23, 2025

Update translation/translators.rst #1576

Merged

StanFromIreland commented Jun 24, 2025

View reviewed changes

Some cleanup

9b7cbd2

StanFromIreland marked this pull request as ready for review June 24, 2025 19:06

rffontenelle suggested changes Jun 24, 2025

View reviewed changes

StanFromIreland added 3 commits June 25, 2025 09:02

Review + Lint

9992fe7

Add Sphinx-core TX section

538d9e6

Grammar

9960fd3

StanFromIreland linked an issue Jun 27, 2025 that may be closed by this pull request

Move docs build scripts info from intro paragraph to the Coordinating FAQ for translations #1585

Open

hugovk reviewed Jun 27, 2025

View reviewed changes

Hugo's Review

acdfd0a

StanFromIreland requested a review from hugovk June 27, 2025 13:46

ezio-melotti reviewed Jun 28, 2025

View reviewed changes

Ezio's review

04d3761

StanFromIreland requested a review from ezio-melotti June 28, 2025 15:09

m-aciek suggested changes Jun 28, 2025

View reviewed changes

		.. XXX https://github.com/python/devguide/issues/1586

		Once the following resources have been fully translated on the XXX branch:

		decreases with the amount of translators.


		Gather people to help you translate. You can't do it alone.

	Gather people to help you translate. You can't do it alone.
	Gather people to translate with you. You can't do it alone.



		Gather people to help you translate. You can't do it alone.
		Update :ref:`this table <translation-coordinators>` via a PR to make

		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 tag may have an optional region subtag, joined with a dash.
	The tag may have an optional subtag, joined with a dash.

	tests translations and uploads error logs.
	provides build warnings and lint errors for translation projects.

		Cookiecutter/bootstrapper
		~~~~~~~~~~~~~~~~~~~~~~~~~

Uh oh!

Update translations/coordinating.rst #1587

Are you sure you want to change the base?

Update translations/coordinating.rst #1587

Uh oh!

Conversation

StanFromIreland commented Jun 23, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

StanFromIreland Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

StanFromIreland commented Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

rffontenelle left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

StanFromIreland Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

hugovk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

StanFromIreland commented Jun 27, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

StanFromIreland Jun 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Update `translations/coordinating.rst` #1587

Update `translations/coordinating.rst` #1587

StanFromIreland commented Jun 23, 2025 •

edited by github-actions bot

Loading

StanFromIreland Jun 24, 2025 •

edited

Loading

StanFromIreland commented Jun 24, 2025 •

edited

Loading

StanFromIreland Jun 24, 2025 •

edited

Loading

StanFromIreland Jun 28, 2025 •

edited

Loading