From c485c9de618e54ebfd5ff9f3f001de81f803d242 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Fri, 13 Jun 2025 14:13:42 +0100 Subject: [PATCH 1/4] Big Split --- conf.py | 4 + documentation/index.rst | 2 +- documentation/translations/coordinating.rst | 120 ++++++++++++++++++ documentation/translations/index.rst | 9 ++ .../{ => translations}/translating.rst | 115 ----------------- 5 files changed, 134 insertions(+), 116 deletions(-) create mode 100644 documentation/translations/coordinating.rst create mode 100644 documentation/translations/index.rst rename documentation/{ => translations}/translating.rst (55%) diff --git a/conf.py b/conf.py index ba7ee6040c..bedd99c42f 100644 --- a/conf.py +++ b/conf.py @@ -127,6 +127,10 @@ # Documentation "docquality.rst": "documentation/help-documenting.rst", "documenting.rst": "documentation/start-documenting.rst", + # Translating + "documentation/translating.rst": "documentation/translations/translating.rst", + "translating.rst": "documentation/translations/translating.rst", + "coordinating.rst": "documentation/translations/coordinating.rst", # Getting Started "fixingissues.rst": "getting-started/fixing-issues.rst", "help.rst": "getting-started/getting-help.rst", diff --git a/documentation/index.rst b/documentation/index.rst index 3f2512bcfb..eaa9e1a967 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -9,5 +9,5 @@ Documentation help-documenting style-guide markup - translating + translations/index devguide diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst new file mode 100644 index 0000000000..37888065f0 --- /dev/null +++ b/documentation/translations/coordinating.rst @@ -0,0 +1,120 @@ +============ +Coordinating +============ + +Starting a new translation +========================== + +First subscribe to the `translation mailing list `_, +and introduce yourself and the translation you're starting. Translations +fall under the aegis of the `PSF Translation Workgroup `_ + +Then you can bootstrap your new translation by using `cookiecutter +`__ or +`bootstrapper `__. + +The important steps look like this: + +- Create the GitHub repo (anywhere) with the right hierarchy (using one + of the bootstrappers). +- 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. +- Ensure we update 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. + + +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 under CC0 and marked as such in the README (as in + the cookiecutter). + +- 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``). + +- Translations having completed ``tutorial/``, ``library/stdtypes`` + and ``library/functions`` are hosted on + ``https://docs.python.org/{LANGUAGE_TAG}/{VERSION_TAG}/``. + + +Coordinating FAQ +================ + +Are there tools to help in managing the repo? +--------------------------------------------- + +Here's what we're using: + +- :pypi:`pomerge` to propagate translations from one file to others. +- :pypi:`pospell` to check for typos in ``.po`` files. +- :pypi:`powrap` to rewrap the ``.po`` files + before committing. This helps keep Git diffs short. +- :pypi:`potodo` to list what needs to be translated. +- :pypi:`sphinx-lint` to validate reST syntax in translation files. + +More related tools and projects can be found in the +`python-docs-translations`__ organisation on GitHub. + +__ https://github.com/python-docs-translations + +How is a coordinator elected? +----------------------------- + +There is no election; each translation has to sort this out. Here are some 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 their + say on the choice. +- Anyone who wants to become coordinator for their native language and shows + motivation by translating and building a community will be named + coordinator. +- In case of concurrency between two persons, no one will sort this out + for you. It is up to you two to organize a local election or whatever is + needed to sort this out. +- If a coordinator becomes inactive or unreachable for a long + period of time, someone else can ask for a takeover on the `translation mailing list `_. + +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. + + +My Git hierarchy does not match yours. Can I keep it? +----------------------------------------------------- + +No, inside the ``github.com/python`` organization we’ll all 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. + + +What hierarchy should I use in my GitHub repository? +---------------------------------------------------- + +As for every project, we have a *branch* per version. We store ``.po`` +files in the root of the repository using the ``gettext_compact=0`` +style. + + +The entry for my translation is missing/not up to date on this page +------------------------------------------------------------------- + +Ask on the `translation mailing list `_, or better, make a PR on the `devguide +`__. diff --git a/documentation/translations/index.rst b/documentation/translations/index.rst new file mode 100644 index 0000000000..67ab049f99 --- /dev/null +++ b/documentation/translations/index.rst @@ -0,0 +1,9 @@ +============ +Translations +============ + +.. toctree:: + :maxdepth: 2 + + translating + coordinating diff --git a/documentation/translating.rst b/documentation/translations/translating.rst similarity index 55% rename from documentation/translating.rst rename to documentation/translations/translating.rst index abbd2c74f5..67fd2a00f5 100644 --- a/documentation/translating.rst +++ b/documentation/translations/translating.rst @@ -110,53 +110,6 @@ details. .. _tx: https://explore.transifex.com/python-doc/python-newest/ -Starting a new translation -========================== - -First subscribe to the `translation mailing list `_, -and introduce yourself and the translation you're starting. Translations -fall under the aegis of the `PSF Translation Workgroup `_ - -Then you can bootstrap your new translation by using `cookiecutter -`__ or -`bootstrapper `__. - -The important steps look like this: - -- Create the GitHub repo (anywhere) with the right hierarchy (using one - of the bootstrappers). -- 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. -- Ensure we update 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. - - -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 under CC0 and marked as such in the README (as in - the cookiecutter). - -- 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``). - -- Translations having completed ``tutorial/``, ``library/stdtypes`` - and ``library/functions`` are hosted on - ``https://docs.python.org/{LANGUAGE_TAG}/{VERSION_TAG}/``. - How to get help =============== @@ -177,74 +130,6 @@ Consensus is to work on the current stable version. You can then propagate your translation from one branch to another using :pypi:`pomerge`. -Are there tools to help in managing the repo? ---------------------------------------------- - -Here's what we're using: - -- :pypi:`pomerge` to propagate translations from one file to others. -- :pypi:`pospell` to check for typos in ``.po`` files. -- :pypi:`powrap` to rewrap the ``.po`` files - before committing. This helps keep Git diffs short. -- :pypi:`potodo` to list what needs to be translated. -- :pypi:`sphinx-lint` to validate reST syntax in translation files. - -More related tools and projects can be found in the -`python-docs-translations`__ organisation on GitHub. - -__ https://github.com/python-docs-translations - -How is a coordinator elected? ------------------------------ - -There is no election; each translation has to sort this out. Here are some 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 their - say on the choice. -- Anyone who wants to become coordinator for their native language and shows - motivation by translating and building a community will be named - coordinator. -- In case of concurrency between two persons, no one will sort this out - for you. It is up to you two to organize a local election or whatever is - needed to sort this out. -- If a coordinator becomes inactive or unreachable for a long - period of time, someone else can ask for a takeover on the `translation mailing list `_. - - -The entry for my translation is missing/not up to date on this page -------------------------------------------------------------------- - -Ask on the `translation mailing list `_, or better, make a PR on the `devguide -`__. - - -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. - - -My Git hierarchy does not match yours. Can I keep it? ------------------------------------------------------ - -No, inside the ``github.com/python`` organization we’ll all 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. - - -What hierarchy should I use in my GitHub repository? ----------------------------------------------------- - -As for every project, we have a *branch* per version. We store ``.po`` -files in the root of the repository using the ``gettext_compact=0`` -style. - - How should I translate code examples? ------------------------------------- From d92b90f8472d0bcd12096b7d0e8a29e6946a347f Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Fri, 13 Jun 2025 20:10:08 +0100 Subject: [PATCH 2/4] Move links --- documentation/translations/coordinating.rst | 3 +++ documentation/translations/translating.rst | 3 --- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index 37888065f0..64dc7ddc61 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -118,3 +118,6 @@ The entry for my translation is missing/not up to date on this page Ask on the `translation mailing list `_, or better, make a PR on the `devguide `__. + +.. _translation_wg: https://wiki.python.org/psf/TranslationWG/Charter +.. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/ diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index 67fd2a00f5..b96f45d2cf 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -136,6 +136,3 @@ How should I translate code examples? Translate values in code examples (i.e. string literals) and comments. Don't translate keywords or names, including variable, function, class, argument, and attribute names. - -.. _translation_wg: https://wiki.python.org/psf/TranslationWG/Charter -.. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/ From 6bc60e4fe942cbe394afa12f748bb1a40cf9eaa3 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 14 Jun 2025 19:24:18 +0100 Subject: [PATCH 3/4] Fix link --- documentation/translations/translating.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index b96f45d2cf..47f04cef89 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -136,3 +136,5 @@ How should I translate code examples? Translate values in code examples (i.e. string literals) and comments. Don't translate keywords or names, including variable, function, class, argument, and attribute names. + +.. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/ From 652fca8cd077cc036267b489ad66a63aad82494c Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Sat, 14 Jun 2025 20:54:28 +0100 Subject: [PATCH 4/4] Apply suggestions from willingc Co-authored-by: Carol Willing --- documentation/translations/coordinating.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index 64dc7ddc61..3d64858ad8 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -15,13 +15,13 @@ Then you can bootstrap your new translation by using `cookiecutter The important steps look like this: -- Create the GitHub repo (anywhere) with the right hierarchy (using one - of the bootstrappers). +- Create the GitHub repo (any account) with the correct hierarchy by using one + of the bootstrappers. - 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. -- Ensure we update this page to reflect your work and progress, either via a +- 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 @@ -73,19 +73,19 @@ __ https://github.com/python-docs-translations How is a coordinator elected? ----------------------------- -There is no election; each translation has to sort this out. Here are some suggestions. +There is no election. Each translation will sort out the number of coordinators. We recommend 2 or 3 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 their - say on the choice. +- If the given language has a native core dev, the core dev has input + on the coordinator request. - Anyone who wants to become coordinator for their native language and shows motivation by translating and building a community will be named coordinator. -- In case of concurrency between two persons, no one will sort this out - for you. It is up to you two to organize a local election or whatever is - needed to sort this out. +- 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 for a takeover on the `translation mailing list `_. + 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? ------------------------------------------------------------