From 9ca670ab4961e74fa0ffc501b18fb530ec474384 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Mon, 16 Jun 2025 13:24:23 +0100 Subject: [PATCH 1/9] Initial --- contrib/index.rst | 2 +- core-developers/experts.rst | 5 +- documentation/translations/coordinating.rst | 42 +++- documentation/translations/translating.rst | 222 +++++++++++++++----- 4 files changed, 218 insertions(+), 53 deletions(-) diff --git a/contrib/index.rst b/contrib/index.rst index f9b54bc56..b93d36504 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` - * :ref:`translating` + * :doc:`documentation/translations` * :ref:`devguide` - * :ref:`setup` diff --git a/core-developers/experts.rst b/core-developers/experts.rst index 54f7fd373..afee5039a 100644 --- a/core-developers/experts.rst +++ b/core-developers/experts.rst @@ -372,4 +372,7 @@ version control merwok, ezio-melotti Documentation translations ========================== -For a list of translators, see :ref:`this table about translations `. +Translations fall under the aegis of the +`Editorial Board `_. +For a list of translations and their coordinators, see +:ref:`this table of translations `. diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index 3d64858ad..a833eea44 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -2,6 +2,11 @@ Coordinating ============ +Python documentation translations are governed by :PEP:`545`. +They are built by `docsbuild-scripts +`__ and hosted on +docs.python.org. + Starting a new translation ========================== @@ -9,6 +14,8 @@ 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 `_ +.. https://github.com/python/editorial-board/issues/32 + Then you can bootstrap your new translation by using `cookiecutter `__ or `bootstrapper `__. @@ -28,6 +35,16 @@ The important steps look like this: your language to be added in the language switcher on docs.python.org. +How to get help +=============== + +Discussions about translations occur on the Python Docs Discord +`#translations channel `_, `translation +mailing list `_, and and the +`translations subsection `_ +of the Python Discourse. + + PEP 545 summary =============== @@ -73,7 +90,8 @@ __ https://github.com/python-docs-translations How is a coordinator elected? ----------------------------- -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. +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 input @@ -113,11 +131,29 @@ 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 -------------------------------------------------------------------- +.. XXX Explain necessary folder structure + + +Which version of the Python documentation should be translated? +--------------------------------------------------------------- + +Consensus is to work on the current stable version. You can then propagate your +translation from one branch to another using :pypi:`pomerge`. + + +The entry for my translation is missing/not up to date +------------------------------------------------------ Ask on the `translation mailing list `_, or better, make a PR on the `devguide `__. + +Is there a Weblate instance we can translate on? +------------------------------------------------ + +There is currently no Weblate instance for use by Python translations because of +certain limitations, these include word count limits and organization of +translation source. + .. _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 47f04cef8..bdd24452e 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -1,18 +1,22 @@ -.. _translating: - =========== Translating =========== .. highlight:: rest -Python documentation translations are governed by :PEP:`545`. -They are built by `docsbuild-scripts -`__ and hosted on -docs.python.org. There are several documentation translations already -in production; others are works in progress. See `the dashboard -`__ for -details. +There are several documentation translations already +in production; others are works in progress. To get started read your +repositories 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` on how to get started. + +For more details about translations and their progress, see `the dashboard +`__. + +.. _translation-coordinators: + +.. XXX Add explicit links to README/CONTRIBUTING? .. list-table:: :header-rows: 1 @@ -23,35 +27,36 @@ details. * - Arabic (ar) - Abdur-Rahmaan Janhangeer (:github-user:`Abdur-rahmaanJ`) - :github:`GitHub ` - * - Bengali (bn_IN) + * - `Bengali (bn_IN) `__ - Kushal Das (:github-user:`kushaldas`) - :github:`GitHub ` * - `French (fr) `__ - Julien Palard (:github-user:`JulienPalard`) - - :github:`GitHub ` - * - Greek (gr) - - Lysandros Nikolaou (:github-user:`lysnikolaou`), - Fanis Petkos (:github-user:`thepetk`), - Panagiotis Skias (:github-user:`skpanagiotis`) + - `AFPy/python-docs-fr `_ + :github:`Mirror ` + * - `Greek (gr) `__ XXX Should be added soonish + - | Lysandros Nikolaou (:github-user:`lysnikolaou`), + | Fanis Petkos (:github-user:`thepetk`), + | Panagiotis Skias (:github-user:`skpanagiotis`) - :github:`GitHub ` * - Hindi (hi_IN) - Sanyam Khurana (:github-user:`CuriousLearner`) - - :github:`GitHub ` - * - Hungarian (hu) + - :github:`GitHub ` XXX Message user in issue tracker https://github.com/CuriousLearner/python-docs-hi-in/issues/5 + * - `Hungarian (hu) `__ XXX This should probably be added - Tamás Bajusz (:github-user:`gbtami`) - :github:`GitHub `, - `mailing list `__ + `Mailing list `__ * - `Indonesian (id) `__ - - Irvan Putra (:github-user:`irvan-putra`), - Jeff Jacobson (:github-user:`jwjacobson`) + - | Irvan Putra (:github-user:`irvan-putra`), + | Jeff Jacobson (:github-user:`jwjacobson`) - :github:`GitHub ` - * - Italian (it) + * - `Italian (it) `__ - Alessandro Cucci (`email `__) - :github:`GitHub `, - `original mail `__ + `Original announcement `__ * - `Japanese (ja) `__ - - Kinebuchi Tomohiko (:github-user:`cocoatomo`), - Atsuo Ishimoto (:github-user:`atsuoishimoto`) + - | Kinebuchi Tomohiko (:github-user:`cocoatomo`), + | Atsuo Ishimoto (:github-user:`atsuoishimoto`) - :github:`GitHub ` * - `Korean (ko) `__ - 오동권 (:github-user:`flowdas`) @@ -61,7 +66,7 @@ details. - :github:`GitHub ` * - Lithuanian (lt) - Albertas Gimbutas (:github-user:`albertas`, `email `__) - - `Original mail `__ + - `Original announcement `__ * - Persian (fa) - Alireza Shabani (:github-user:`revisto`) - :github:`GitHub ` @@ -69,24 +74,24 @@ details. - Maciej Olko (:github-user:`m-aciek`) - :github:`GitHub `, `Transifex `_, - `original mail `__ + `Original announcement `__ * - Portuguese (pt) - Gustavo Toffo - * - `Brazilian Portuguese (pt-br) `__ - - Rafael Fontenelle (:github-user:`rffontenelle`), - Marco Rougeth (:github-user:`rougeth`) + - | Rafael Fontenelle (:github-user:`rffontenelle`), + | Marco Rougeth (:github-user:`rougeth`) - :github:`GitHub `, - `wiki `__, + `Wiki `__, `Telegram `__, - `article `__ - * - Romanian (ro) + `Article `__ + * - `Romanian (ro) `__ - Octavian Mustafa (:github-user:`octaG-M`, `email `__) - - :github:`GitHub ` + - :github:`GitHub ` * - Russian (ru) - Daniil Kolesnikov (:github-user:`MLGRussianXP`, `email `__) - :github:`GitHub `, - `mail `__ + `Original announcement `__ * - `Simplified Chinese (zh-cn) `__ - Shengjing Zhu (:github-user:`zhsj`), Du, Meng (:github-user:`dumeng`) @@ -102,39 +107,160 @@ details. * - `Turkish (tr) `__ - Ege Akman (:github-user:`egeakman`) - :github:`GitHub `, - `RTD `__ + `RTD `__ XXX Why keep this with python build? Ask Ege * - `Ukrainian (uk) `__ - Dmytro Kazanzhy (:github-user:`kazanzhy`, `email `__) - :github:`GitHub `, `Transifex `_ -.. _tx: https://explore.transifex.com/python-doc/python-newest/ - How to get help =============== -Discussions about translations occur on the Python Docs Discord +If there is already a repository for your language team (there may be links to +Telegrams/Discords in the ``README``), join and introduce +yourself, your fellow translators will be more than happy to help! XXX sounds off +General discussions about translations occur on the Python Docs Discord `#translations channel `_, `translation -mailing list `_, and there's a `Libera.Chat IRC -`_ channel, ``#python-doc``. +mailing list `_, and the `translations subsection <_discourse>`_ +of the Python Discourse. + + +Style Guide +=========== + +Before translating, you should familiarize yourself with the general +documentation :doc:`style guide<../style-guide>`. Some translation specific +guidelines are explained below. + + +Roles and links +--------------- + +The Python docs contain many roles (``:role:`target```) +to other parts of the documentation. +Leave reStructuredText roles such as ``:func:`print``` or ``:ref:`some-section``` in +place, even if they contain section titles, because it will break the link. +If alternate text (``:role:`text ``` is provided, it can be translated. + +Links (```text `_``) should be handled similarly. + +.. XXX do we want to switch links to target language if possible, ES translation does this (and I do too sometimes...)? + +.. seealso:: + :doc:`../markup` + + +Code examples +------------- + +Translate values in code examples, that is string literals, and comments. +These may be lines from Monty Python skits or other references, they are, however, +sometimes obscure and lose meaning when translated, so do not feel pressured +to get them perfect. + +.. XXX Ask EB can we do this QOL improvement?/Reword too + +Don't translate keywords or names, including variable, function, class, argument, +and attribute names. An example of a translated codeblock from the `tutorial `_ +is provided below: + +.. code-block:: python + + def cheeseshop(kind, *arguments, **keywords): + print("-- Czy jest może", kind, "?") + print("-- Przykro mi, nie mamy już sera", kind) + for arg in arguments: + print(arg) + print("-" * 40) + for kw in keywords: + print(kw, ":", keywords[kw]) + + +Translation quality +------------------- + +Translators should be proficient in both English and the language they are +translating to. Translators should aim for a similar level of quality as that +of the English documentation. + +Avoid relying solely on machine translation. These tools can be useful to speed up +work, but often produce inaccurate or misleading results and should be reviewed. +.. XXX ask EB about permission for this section or maybe https://github.com/python/peps/pull/4296/ to ref + + +Vocabulary +---------- + +The documentation is full of technical terms, some are common in general +programming and have translations, whereas others are specific to Python. +Translations should keep the translations of these terms consistent, which is +done with glossaries/translation memory. + +.. XXX Reword above +.. XXX note that in coordinating.rst + +Some general guidelines for deciding on a translation: + +.. XXX todo (a lot) + +- Use existing community conventions over inventing new terms. +- Use hybrid form +- Use English for common terms ... maybe hard to desc this case +- Use your best judgment +- Use other translations for reference as to what to do +- Be careful to not translate names +- Record in glossary to help peers!!!!!!!!!!!!!!!!! + + +Dialects +-------- + +Some translation receive contributions from people of many different dialects, +understandably the language will differ, it is recommended however that +translators try to keep files/large sections consistent. + + +Transifex +========= + +.. XXX maybe add quickstart? + +.. important:: + + There are many translations in the `python transifex `_, some of which, + however, not used anymore or do not have a coordinator, please confirm this + is not the case before you begin translating. + +Translations on Transifex are carried out via a web interface, similar to Weblate. +For further information about Transifex, and our guides on getting started, see +our `documentation `_. +.. XXX Move stuff here, discuss w Rafael? + +If you need help from a Transifex administrator, open an issue on the +`tracker `_. +.. XXX explain that it is not same as coordinator Translation FAQ =============== -Which version of the Python documentation should be translated? ---------------------------------------------------------------- +Which version of the Python documentation should I work on? +----------------------------------------------------------- -Consensus is to work on the current stable version. You can then propagate your -translation from one branch to another using :pypi:`pomerge`. +You should work on the latest branch available for you translation, the translations +should then be propagated by the languages coordinator. -How should I translate code examples? -------------------------------------- +The coordinator for my language is inactive, what do I do? +---------------------------------------------------------- -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. +If you would like to coordinate, follow the (necessary) steps outlined in +:doc:`coordinating` and open an issue in the +`EB issue tracker `_. + +.. XXX Ask EB if this is ok .. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/ +.. _discourse: https://discuss.python.org/c/documentation/translations/ +.. _tx: https://explore.transifex.com/python-doc/python-newest/ From 8960469ed9e8cc3b23a1b45e9b55e4729d06bdc2 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Mon, 16 Jun 2025 18:21:02 +0100 Subject: [PATCH 2/9] Rafael's feedback --- documentation/translations/coordinating.rst | 19 +++++++---- documentation/translations/translating.rst | 38 ++++++++++++--------- 2 files changed, 33 insertions(+), 24 deletions(-) diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index a833eea44..2524e9177 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -5,16 +5,14 @@ Coordinating Python documentation translations are governed by :PEP:`545`. They are built by `docsbuild-scripts `__ and hosted on -docs.python.org. +docs.python.org. Translations +fall under the aegis of the `Editorial Board `_ 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 `_ - -.. https://github.com/python/editorial-board/issues/32 +and introduce yourself and the translation you're starting. Then you can bootstrap your new translation by using `cookiecutter `__ or @@ -40,7 +38,7 @@ How to get help Discussions about translations occur on the Python Docs Discord `#translations channel `_, `translation -mailing list `_, and and the +mailing list `_, and the `translations subsection `_ of the Python Discourse. @@ -67,6 +65,13 @@ Here are the essential points of :PEP:`545`: ``https://docs.python.org/{LANGUAGE_TAG}/{VERSION_TAG}/``. +Transifex +========= + +If you need help from a Transifex administrator, open an issue on the +`tracker `_. + + Coordinating FAQ ================ @@ -155,5 +160,5 @@ There is currently no Weblate instance for use by Python translations because of certain limitations, these include word count limits and organization of translation source. -.. _translation_wg: https://wiki.python.org/psf/TranslationWG/Charter +.. _EB: https://python.github.io/editorial-board/ .. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/ diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index bdd24452e..470d63ccb 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -22,7 +22,7 @@ For more details about translations and their progress, see `the dashboard :header-rows: 1 * - Language - - Contact + - Coordination team - Links * - Arabic (ar) - Abdur-Rahmaan Janhangeer (:github-user:`Abdur-rahmaanJ`) @@ -32,7 +32,7 @@ For more details about translations and their progress, see `the dashboard - :github:`GitHub ` * - `French (fr) `__ - Julien Palard (:github-user:`JulienPalard`) - - `AFPy/python-docs-fr `_ + - `AFPy/python-docs-fr `_, :github:`Mirror ` * - `Greek (gr) `__ XXX Should be added soonish - | Lysandros Nikolaou (:github-user:`lysnikolaou`), @@ -224,22 +224,25 @@ translators try to keep files/large sections consistent. Transifex ========= -.. XXX maybe add quickstart? - .. important:: - There are many translations in the `python transifex `_, some of which, - however, not used anymore or do not have a coordinator, please confirm this - is not the case before you begin translating. + There are many translations in the `python-doc organization on transifex `_, + some of which, however, not used anymore or do not have a coordination team, + please confirm this is not the case before you begin translating. Translations on Transifex are carried out via a web interface, similar to Weblate. -For further information about Transifex, and our guides on getting started, see -our `documentation `_. -.. XXX Move stuff here, discuss w Rafael? +You should translate the **python-newest** project. +If you are new to Transifex, it is recommended that you take the time to read +through the following resources from the Transifex documentation: -If you need help from a Transifex administrator, open an issue on the -`tracker `_. -.. XXX explain that it is not same as coordinator +- `Getting started as a translator `_: + This covers signing up for an account and joining translation team. +- `Translating with the Web Editor `_: + This covers getting to the editor, searching and filtering strings, and translating strings. +- `Other Tools in the Editor `_: + This covers the history, glossary, comments, keyboard shortcuts, and more. +- `Starting with the basics `_: + A group of documents with basic information. Translation FAQ @@ -248,12 +251,13 @@ Translation FAQ Which version of the Python documentation should I work on? ----------------------------------------------------------- -You should work on the latest branch available for you translation, the translations -should then be propagated by the languages coordinator. +You should work on the latest branch available to you for translation (this should +be the latest non-alpha branch), the translations should then be propagated by +your languages coordination team. -The coordinator for my language is inactive, what do I do? ----------------------------------------------------------- +The coordination team for my language is inactive, what do I do? +---------------------------------------------------------------- If you would like to coordinate, follow the (necessary) steps outlined in :doc:`coordinating` and open an issue in the From b42731ad318e1e0d444208b7a303fe132a0d3971 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 17 Jun 2025 11:17:50 +0100 Subject: [PATCH 3/9] Further updates and amendments --- core-developers/experts.rst | 2 +- documentation/translations/coordinating.rst | 25 +++-- documentation/translations/index.rst | 2 +- documentation/translations/translating.rst | 113 +++++++++++--------- 4 files changed, 79 insertions(+), 63 deletions(-) diff --git a/core-developers/experts.rst b/core-developers/experts.rst index afee5039a..9df1f73ed 100644 --- a/core-developers/experts.rst +++ b/core-developers/experts.rst @@ -372,7 +372,7 @@ version control merwok, ezio-melotti Documentation translations ========================== -Translations fall under the aegis of the +Translations are within the charter of `Editorial Board `_. For a list of translations and their coordinators, see :ref:`this table of translations `. diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index 2524e9177..cfc9debd8 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -2,7 +2,8 @@ Coordinating ============ -Python documentation translations are governed by :PEP:`545`. +Current information about the Python documentation translation processes is +found in this devguide, and Process :PEP:`545`, adopted in 2018. They are built by `docsbuild-scripts `__ and hosted on docs.python.org. Translations @@ -95,8 +96,9 @@ __ https://github.com/python-docs-translations How is a coordinator elected? ----------------------------- -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. +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 @@ -142,23 +144,24 @@ style. Which version of the Python documentation should be translated? --------------------------------------------------------------- -Consensus is to work on the current stable version. You can then propagate your +It's best to work on Python's current stable version. You can then propagate your translation from one branch to another using :pypi:`pomerge`. -The entry for my translation is missing/not up to date ------------------------------------------------------- +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 -`__. +Ask on the `translation mailing list `_, or better, make a PR +on the `devguide `__. Is there a Weblate instance we can translate on? ------------------------------------------------ -There is currently no Weblate instance for use by Python translations because of -certain limitations, these include word count limits and organization of -translation source. +There is currently no Weblate instance for Python translations. +See this `discourse thread `_ +for updates. + .. _EB: https://python.github.io/editorial-board/ .. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/ diff --git a/documentation/translations/index.rst b/documentation/translations/index.rst index 67ab049f9..e4224bc53 100644 --- a/documentation/translations/index.rst +++ b/documentation/translations/index.rst @@ -3,7 +3,7 @@ Translations ============ .. toctree:: - :maxdepth: 2 + :maxdepth: 6 translating coordinating diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index 470d63ccb..5996df076 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -5,19 +5,17 @@ Translating .. highlight:: rest There are several documentation translations already -in production; others are works in progress. To get started read your -repositories contributing guide, which is generally the ``README`` -file, and this page. +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` on how to get started. +See :doc:`coordinating` guide to get started. For more details about translations and their progress, see `the dashboard `__. .. _translation-coordinators: -.. XXX Add explicit links to README/CONTRIBUTING? - .. list-table:: :header-rows: 1 @@ -34,14 +32,14 @@ For more details about translations and their progress, see `the dashboard - Julien Palard (:github-user:`JulienPalard`) - `AFPy/python-docs-fr `_, :github:`Mirror ` - * - `Greek (gr) `__ XXX Should be added soonish + * - `Greek (gr) `__ - | Lysandros Nikolaou (:github-user:`lysnikolaou`), | Fanis Petkos (:github-user:`thepetk`), | Panagiotis Skias (:github-user:`skpanagiotis`) - :github:`GitHub ` - * - Hindi (hi_IN) + * - Hindi (hi-IN) - Sanyam Khurana (:github-user:`CuriousLearner`) - - :github:`GitHub ` XXX Message user in issue tracker https://github.com/CuriousLearner/python-docs-hi-in/issues/5 + - :github:`GitHub ` * - `Hungarian (hu) `__ XXX This should probably be added - Tamás Bajusz (:github-user:`gbtami`) - :github:`GitHub `, @@ -82,7 +80,7 @@ For more details about translations and their progress, see `the dashboard - | Rafael Fontenelle (:github-user:`rffontenelle`), | Marco Rougeth (:github-user:`rougeth`) - :github:`GitHub `, - `Wiki `__, + `Guide `__, `Telegram `__, `Article `__ * - `Romanian (ro) `__ @@ -93,21 +91,21 @@ For more details about translations and their progress, see `the dashboard - :github:`GitHub `, `Original announcement `__ * - `Simplified Chinese (zh-cn) `__ - - Shengjing Zhu (:github-user:`zhsj`), - Du, Meng (:github-user:`dumeng`) + - | Shengjing Zhu (:github-user:`zhsj`), + | Du, Meng (:github-user:`dumeng`) - :github:`GitHub `, `Transifex `_ * - `Spanish (es) `__ - Raúl Cumplido - :github:`GitHub ` * - `Traditional Chinese (zh-tw) `__ - - 王威翔 Matt Wang (:github-user:`mattwang44`), - Josix Wang + - | 王威翔 Matt Wang (:github-user:`mattwang44`), + | Josix Wang - :github:`GitHub ` * - `Turkish (tr) `__ - Ege Akman (:github-user:`egeakman`) - :github:`GitHub `, - `RTD `__ XXX Why keep this with python build? Ask Ege + `RTD `__ * - `Ukrainian (uk) `__ - Dmytro Kazanzhy (:github-user:`kazanzhy`, `email `__) - :github:`GitHub `, @@ -119,7 +117,7 @@ How to get help If there is already a repository for your language team (there may be links to Telegrams/Discords in the ``README``), join and introduce -yourself, your fellow translators will be more than happy to help! XXX sounds off +yourself. Your fellow translators will be more than happy to help! General discussions about translations occur on the Python Docs Discord `#translations channel `_, `translation mailing list `_, and the `translations subsection <_discourse>`_ @@ -130,10 +128,25 @@ 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. +Translate, don't rewrite +------------------------ + +Try to stay as close as possible to the original text. Focus on translating its +meaning rather than rephrasing or rewriting it. + + +Gender neutrality +----------------- + +Many languages use grammatical gender. When possible and natural, prefer +gender-neutral or inclusive forms. Aim to reflect the inclusive tone of +the English documentation. + + Roles and links --------------- @@ -143,9 +156,8 @@ Leave reStructuredText roles such as ``:func:`print``` or ``:ref:`some-section`` place, even if they contain section titles, because it will break the link. If alternate text (``:role:`text ``` is provided, it can be translated. -Links (```text `_``) should be handled similarly. - -.. XXX do we want to switch links to target language if possible, ES translation does this (and I do too sometimes...)? +Links (```text `_``) should be handled similarly. If possible, the target +should be updated to match the language. .. seealso:: :doc:`../markup` @@ -155,12 +167,6 @@ Code examples ------------- Translate values in code examples, that is string literals, and comments. -These may be lines from Monty Python skits or other references, they are, however, -sometimes obscure and lose meaning when translated, so do not feel pressured -to get them perfect. - -.. XXX Ask EB can we do this QOL improvement?/Reword too - Don't translate keywords or names, including variable, function, class, argument, and attribute names. An example of a translated codeblock from the `tutorial `_ is provided below: @@ -185,40 +191,39 @@ translating to. Translators should aim for a similar level of quality as that of the English documentation. Avoid relying solely on machine translation. These tools can be useful to speed up -work, but often produce inaccurate or misleading results and should be reviewed. -.. XXX ask EB about permission for this section or maybe https://github.com/python/peps/pull/4296/ to ref +work, but often produce inaccurate or misleading results and should be reviewed +by a human. -Vocabulary ----------- +Terminology +----------- The documentation is full of technical terms, some are common in general -programming and have translations, whereas others are specific to Python. -Translations should keep the translations of these terms consistent, which is -done with glossaries/translation memory. - -.. XXX Reword above -.. XXX note that in coordinating.rst +programming and have translations, whereas others are specific to Python +and previous translations are not available (remember to check your languages +glossary). Translations should keep the translations of these terms consistent, +which is done with glossaries and or translation memory. Some general guidelines for deciding on a translation: -.. XXX todo (a lot) - -- Use existing community conventions over inventing new terms. -- Use hybrid form -- Use English for common terms ... maybe hard to desc this case +- Avoid neologism when possible, use existing community conventions over + inventing new terms. +- You can use a hybrid English form if users are generally familiar + with the English word. +- For common terms, the English word may be best. +- Use other translations as a reference as to what they did for the word. +- Be careful to not translate names. - Use your best judgment -- Use other translations for reference as to what to do -- Be careful to not translate names -- Record in glossary to help peers!!!!!!!!!!!!!!!!! +- When you translate a specific term, record in glossary to help fellow + translators and ensure consistency. Dialects -------- -Some translation receive contributions from people of many different dialects, +Some translation receive contributions from people of several different dialects, understandably the language will differ, it is recommended however that -translators try to keep files/large sections consistent. +translators try to keep files and sections consistent. Transifex @@ -244,6 +249,15 @@ through the following resources from the Transifex documentation: - `Starting with the basics `_: A group of documents with basic information. +For further information about Transifex see our `documentation `_. + + +Pull requests +============= + +Several translations accept contributions by pull requests. Most have their +own guide for how to do this, and for general tips see our :ref:`git-boot-camp`. + Translation FAQ =============== @@ -259,11 +273,10 @@ your languages coordination team. The coordination team for my language is inactive, what do I do? ---------------------------------------------------------------- -If you would like to coordinate, follow the (necessary) steps outlined in -:doc:`coordinating` and open an issue in the -`EB issue tracker `_. +If you would like to coordinate, open a pull request in the +`devguide `_ adding yourself, and ping +``@python/editorial-board``. -.. XXX Ask EB if this is ok .. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/ .. _discourse: https://discuss.python.org/c/documentation/translations/ From d4e50f7410409d189f4c7f86edc43db5da4b99cb Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Wed, 18 Jun 2025 17:56:51 +0100 Subject: [PATCH 4/9] Rafael's review --- documentation/translations/translating.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index 5996df076..5e114eabf 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -201,8 +201,8 @@ Terminology The documentation is full of technical terms, some are common in general programming and have translations, whereas others are specific to Python and previous translations are not available (remember to check your languages -glossary). Translations should keep the translations of these terms consistent, -which is done with glossaries and or translation memory. +glossary). Translation teams should keep the translations of these terms +consistent, which is done with glossaries and or translation memory. Some general guidelines for deciding on a translation: @@ -231,7 +231,7 @@ Transifex .. important:: - There are many translations in the `python-doc organization on transifex `_, + There are many translations in the `python-doc organization on Transifex `_, some of which, however, not used anymore or do not have a coordination team, please confirm this is not the case before you begin translating. From 7e0bbc72f99da52f14df169e5e5fe330391b46d4 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Thu, 19 Jun 2025 21:58:11 +0100 Subject: [PATCH 5/9] =?UTF-8?q?Carol=E2=80=99s=20suggestion?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Carol Willing --- documentation/translations/coordinating.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index cfc9debd8..32e61ce0d 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -4,7 +4,7 @@ Coordinating Current information about the Python documentation translation processes is found in this devguide, and Process :PEP:`545`, adopted in 2018. -They are built by `docsbuild-scripts +Translations are built by `docsbuild-scripts `__ and hosted on docs.python.org. Translations fall under the aegis of the `Editorial Board `_ From 6f22c6507b713c045978584f2ee19e29b1bd6767 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Fri, 20 Jun 2025 09:24:40 +0100 Subject: [PATCH 6/9] Maciek's review --- documentation/translations/coordinating.rst | 8 +-- documentation/translations/index.rst | 2 +- documentation/translations/translating.rst | 73 +++++++++++---------- 3 files changed, 43 insertions(+), 40 deletions(-) diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index 32e61ce0d..ac6af1a68 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -15,8 +15,8 @@ Starting a new translation First subscribe to the `translation mailing list `_, and introduce yourself and the translation you're starting. -Then you can bootstrap your new translation by using `cookiecutter -`__ or +Then you can bootstrap your new translation by using the `cookiecutter +`__ or `bootstrapper `__. The important steps look like this: @@ -144,8 +144,8 @@ style. Which version of the Python documentation should be translated? --------------------------------------------------------------- -It's best to work on Python's current stable version. You can then propagate your -translation from one branch to another using :pypi:`pomerge`. +It's best to work on Python's current stable or beta version. You can then +propagate your translation from one branch to another using :pypi:`pomerge`. The entry for my translation is missing or not up to date diff --git a/documentation/translations/index.rst b/documentation/translations/index.rst index e4224bc53..2f5cfe0f4 100644 --- a/documentation/translations/index.rst +++ b/documentation/translations/index.rst @@ -3,7 +3,7 @@ Translations ============ .. toctree:: - :maxdepth: 6 + :maxdepth: 3 translating coordinating diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index 5e114eabf..306c193c5 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -25,22 +25,22 @@ For more details about translations and their progress, see `the dashboard * - Arabic (ar) - Abdur-Rahmaan Janhangeer (:github-user:`Abdur-rahmaanJ`) - :github:`GitHub ` - * - `Bengali (bn_IN) `__ + * - `Bengali (bn-IN) `__ - Kushal Das (:github-user:`kushaldas`) - :github:`GitHub ` * - `French (fr) `__ - Julien Palard (:github-user:`JulienPalard`) - `AFPy/python-docs-fr `_, :github:`Mirror ` - * - `Greek (gr) `__ + * - `Greek (gr) `__ - | Lysandros Nikolaou (:github-user:`lysnikolaou`), | Fanis Petkos (:github-user:`thepetk`), | Panagiotis Skias (:github-user:`skpanagiotis`) - - :github:`GitHub ` + - :github:`GitHub ` * - Hindi (hi-IN) - Sanyam Khurana (:github-user:`CuriousLearner`) - :github:`GitHub ` - * - `Hungarian (hu) `__ XXX This should probably be added + * - Hungarian (hu) - Tamás Bajusz (:github-user:`gbtami`) - :github:`GitHub `, `Mailing list `__ @@ -69,7 +69,8 @@ For more details about translations and their progress, see `the dashboard - Alireza Shabani (:github-user:`revisto`) - :github:`GitHub ` * - `Polish (pl) `__ - - Maciej Olko (:github-user:`m-aciek`) + - | Maciej Olko (:github-user:`m-aciek`) + | Stan Ulbrych (:github-user:`StanFromIreland`) - :github:`GitHub `, `Transifex `_, `Original announcement `__ @@ -136,7 +137,7 @@ Translate, don't rewrite ------------------------ Try to stay as close as possible to the original text. Focus on translating its -meaning rather than rephrasing or rewriting it. +meaning in the best possible way, rather than rephrasing or rewriting it. Gender neutrality @@ -155,6 +156,8 @@ to other parts of the documentation. Leave reStructuredText roles such as ``:func:`print``` or ``:ref:`some-section``` in place, even if they contain section titles, because it will break the link. If alternate text (``:role:`text ``` is provided, it can be translated. +You can also introduce alternate text for translation if the target is not a +name or term. Links (```text `_``) should be handled similarly. If possible, the target should be updated to match the language. @@ -163,26 +166,6 @@ should be updated to match the language. :doc:`../markup` -Code examples -------------- - -Translate values in code examples, that is string literals, and comments. -Don't translate keywords or names, including variable, function, class, argument, -and attribute names. An example of a translated codeblock from the `tutorial `_ -is provided below: - -.. code-block:: python - - def cheeseshop(kind, *arguments, **keywords): - print("-- Czy jest może", kind, "?") - print("-- Przykro mi, nie mamy już sera", kind) - for arg in arguments: - print(arg) - print("-" * 40) - for kw in keywords: - print(kw, ":", keywords[kw]) - - Translation quality ------------------- @@ -190,7 +173,7 @@ Translators should be proficient in both English and the language they are translating to. Translators should aim for a similar level of quality as that of the English documentation. -Avoid relying solely on machine translation. These tools can be useful to speed up +Do not rely solely on machine translation. These tools can be useful to speed up work, but often produce inaccurate or misleading results and should be reviewed by a human. @@ -200,20 +183,19 @@ Terminology The documentation is full of technical terms, some are common in general programming and have translations, whereas others are specific to Python -and previous translations are not available (remember to check your languages -glossary). Translation teams should keep the translations of these terms -consistent, which is done with glossaries and or translation memory. +and previous translations are not available. +Translation teams should keep the translations of these terms +consistent, which is done with glossaries. Some general guidelines for deciding on a translation: -- Avoid neologism when possible, use existing community conventions over - inventing new terms. +- Use existing community conventions over inventing new terms. - You can use a hybrid English form if users are generally familiar with the English word. - For common terms, the English word may be best. - Use other translations as a reference as to what they did for the word. - Be careful to not translate names. -- Use your best judgment +- Use your best judgment. - When you translate a specific term, record in glossary to help fellow translators and ensure consistency. @@ -226,17 +208,38 @@ understandably the language will differ, it is recommended however that translators try to keep files and sections consistent. +Code examples +------------- + +Translate values in code examples, that is string literals, and comments. +Don't translate keywords or names, including variable, function, class, argument, +and attribute names. An example of a translated codeblock from the `tutorial `_ +is provided below: + +.. code-block:: python + + def cheeseshop(kind, *arguments, **keywords): + print("-- Czy jest może", kind, "?") + print("-- Przykro mi, nie mamy już sera", kind) + for arg in arguments: + print(arg) + print("-" * 40) + for kw in keywords: + print(kw, ":", keywords[kw]) + + Transifex ========= .. important:: There are many translations in the `python-doc organization on Transifex `_, - some of which, however, not used anymore or do not have a coordination team, + some of which, however, are not used or do not have a coordination team, please confirm this is not the case before you begin translating. +Several language projects use Transifex as their translation interface. Translations on Transifex are carried out via a web interface, similar to Weblate. -You should translate the **python-newest** project. +You should translate the `python-newest `_ project. If you are new to Transifex, it is recommended that you take the time to read through the following resources from the Transifex documentation: From 3b00bddae33abc6672b0ac98879750c427de8f52 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Fri, 20 Jun 2025 11:35:22 +0100 Subject: [PATCH 7/9] Reviews --- documentation/translations/coordinating.rst | 6 +- documentation/translations/translating.rst | 62 ++++++++++----------- 2 files changed, 34 insertions(+), 34 deletions(-) diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index ac6af1a68..2da49d90b 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -7,7 +7,7 @@ found in this devguide, and Process :PEP:`545`, adopted in 2018. Translations are built by `docsbuild-scripts `__ and hosted on docs.python.org. Translations -fall under the aegis of the `Editorial Board `_ +are overseen by the `Editorial Board `_ Starting a new translation ========================== @@ -40,7 +40,7 @@ How to get help Discussions about translations occur on the Python Docs Discord `#translations channel `_, `translation mailing list `_, and the -`translations subsection `_ +`translations category `_ of the Python Discourse. @@ -159,7 +159,7 @@ Is there a Weblate instance we can translate on? ------------------------------------------------ There is currently no Weblate instance for Python translations. -See this `discourse thread `_ +See this `Discourse thread `_ for updates. diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index 306c193c5..dacec9dd8 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -31,7 +31,7 @@ For more details about translations and their progress, see `the dashboard * - `French (fr) `__ - Julien Palard (:github-user:`JulienPalard`) - `AFPy/python-docs-fr `_, - :github:`Mirror ` + :github:`mirror ` * - `Greek (gr) `__ - | Lysandros Nikolaou (:github-user:`lysnikolaou`), | Fanis Petkos (:github-user:`thepetk`), @@ -43,7 +43,7 @@ For more details about translations and their progress, see `the dashboard * - Hungarian (hu) - Tamás Bajusz (:github-user:`gbtami`) - :github:`GitHub `, - `Mailing list `__ + `mailing list `__ * - `Indonesian (id) `__ - | Irvan Putra (:github-user:`irvan-putra`), | Jeff Jacobson (:github-user:`jwjacobson`) @@ -51,7 +51,7 @@ For more details about translations and their progress, see `the dashboard * - `Italian (it) `__ - Alessandro Cucci (`email `__) - :github:`GitHub `, - `Original announcement `__ + `original announcement `__ * - `Japanese (ja) `__ - | Kinebuchi Tomohiko (:github-user:`cocoatomo`), | Atsuo Ishimoto (:github-user:`atsuoishimoto`) @@ -64,7 +64,7 @@ For more details about translations and their progress, see `the dashboard - :github:`GitHub ` * - Lithuanian (lt) - Albertas Gimbutas (:github-user:`albertas`, `email `__) - - `Original announcement `__ + - `original announcement `__ * - Persian (fa) - Alireza Shabani (:github-user:`revisto`) - :github:`GitHub ` @@ -73,7 +73,7 @@ For more details about translations and their progress, see `the dashboard | Stan Ulbrych (:github-user:`StanFromIreland`) - :github:`GitHub `, `Transifex `_, - `Original announcement `__ + `original announcement `__ * - Portuguese (pt) - Gustavo Toffo - @@ -81,16 +81,16 @@ For more details about translations and their progress, see `the dashboard - | Rafael Fontenelle (:github-user:`rffontenelle`), | Marco Rougeth (:github-user:`rougeth`) - :github:`GitHub `, - `Guide `__, + `guide `__, `Telegram `__, - `Article `__ + `article `__ * - `Romanian (ro) `__ - Octavian Mustafa (:github-user:`octaG-M`, `email `__) - :github:`GitHub ` * - Russian (ru) - Daniil Kolesnikov (:github-user:`MLGRussianXP`, `email `__) - :github:`GitHub `, - `Original announcement `__ + `original announcement `__ * - `Simplified Chinese (zh-cn) `__ - | Shengjing Zhu (:github-user:`zhsj`), | Du, Meng (:github-user:`dumeng`) @@ -121,11 +121,11 @@ Telegrams/Discords in the ``README``), join and introduce yourself. Your fellow translators will be more than happy to help! General discussions about translations occur on the Python Docs Discord `#translations channel `_, `translation -mailing list `_, and the `translations subsection <_discourse>`_ +mailing list `_, and the `translations category <_discourse>`_ of the Python Discourse. -Style Guide +Style guide =========== Before translating, you should familiarize yourself with the general @@ -133,11 +133,11 @@ documentation :doc:`style guide<../style-guide>`. Some translation-specific guidelines are explained below. -Translate, don't rewrite ------------------------- +Translate the meaning +--------------------- Try to stay as close as possible to the original text. Focus on translating its -meaning in the best possible way, rather than rephrasing or rewriting it. +meaning in the best possible way. Gender neutrality @@ -151,13 +151,13 @@ the English documentation. Roles and links --------------- -The Python docs contain many roles (``:role:`target```) -to other parts of the documentation. -Leave reStructuredText roles such as ``:func:`print``` or ``:ref:`some-section``` in -place, even if they contain section titles, because it will break the link. -If alternate text (``:role:`text ``` is provided, it can be translated. -You can also introduce alternate text for translation if the target is not a -name or term. +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 +should be translated. You can also introduce alternate text for translation if +the target is not a name or term. Links (```text `_``) should be handled similarly. If possible, the target should be updated to match the language. @@ -169,7 +169,7 @@ should be updated to match the language. Translation quality ------------------- -Translators should be proficient in both English and the language they are +Translators should know both English and the language they are translating to. Translators should aim for a similar level of quality as that of the English documentation. @@ -196,15 +196,15 @@ Some general guidelines for deciding on a translation: - Use other translations as a reference as to what they did for the word. - Be careful to not translate names. - Use your best judgment. -- When you translate a specific term, record in glossary to help fellow - translators and ensure consistency. +- When you translate a specific term, record it in your translations glossary to + help fellow translators and ensure consistency. Dialects -------- Some translation receive contributions from people of several different dialects, -understandably the language will differ, it is recommended however that +understandably the language will differ. It is recommended however that translators try to keep files and sections consistent. @@ -234,8 +234,8 @@ Transifex .. important:: There are many translations in the `python-doc organization on Transifex `_, - some of which, however, are not used or do not have a coordination team, - please confirm this is not the case before you begin translating. + some of which, however, are not used or do not have a coordination team. + Confirm this is not the case before you begin translating. Several language projects use Transifex as their translation interface. Translations on Transifex are carried out via a web interface, similar to Weblate. @@ -243,13 +243,13 @@ You should translate the `python-newest `_ project. If you are new to Transifex, it is recommended that you take the time to read through the following resources from the Transifex documentation: -- `Getting started as a translator `_: - This covers signing up for an account and joining translation team. -- `Translating with the Web Editor `_: +- `Getting started as a translator `__: + This covers signing up for an account and joining a translation team. +- `Translating with the Web Editor `__: This covers getting to the editor, searching and filtering strings, and translating strings. -- `Other Tools in the Editor `_: +- `Other Tools in the Editor `__: This covers the history, glossary, comments, keyboard shortcuts, and more. -- `Starting with the basics `_: +- `Starting with the basics `__: A group of documents with basic information. For further information about Transifex see our `documentation `_. From 487809c8aa4cbe9ff90228b845ba743be2c20752 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Fri, 20 Jun 2025 14:47:01 +0100 Subject: [PATCH 8/9] Maciek's review + comma --- documentation/translations/translating.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index dacec9dd8..7d1e2f251 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -32,7 +32,7 @@ For more details about translations and their progress, see `the dashboard - Julien Palard (:github-user:`JulienPalard`) - `AFPy/python-docs-fr `_, :github:`mirror ` - * - `Greek (gr) `__ + * - `Greek (el) `__ - | Lysandros Nikolaou (:github-user:`lysnikolaou`), | Fanis Petkos (:github-user:`thepetk`), | Panagiotis Skias (:github-user:`skpanagiotis`) @@ -69,7 +69,7 @@ For more details about translations and their progress, see `the dashboard - Alireza Shabani (:github-user:`revisto`) - :github:`GitHub ` * - `Polish (pl) `__ - - | Maciej Olko (:github-user:`m-aciek`) + - | Maciej Olko (:github-user:`m-aciek`), | Stan Ulbrych (:github-user:`StanFromIreland`) - :github:`GitHub `, `Transifex `_, From 0035845a8522c900e1f4d43679c9623c7ee0efc4 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Fri, 20 Jun 2025 20:12:02 +0100 Subject: [PATCH 9/9] =?UTF-8?q?Hugo=E2=80=99s=20suggestions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- 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 2da49d90b..b041115e9 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -2,8 +2,8 @@ Coordinating ============ -Current information about the Python documentation translation processes is -found in this devguide, and Process :PEP:`545`, adopted in 2018. +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