Maciek's review

python · willingc · Jun 20, 2025 · Jun 16, 2025 · Jun 16, 2025 · Jun 17, 2025
commit 6f22c6507b713c045978584f2ee19e29b1bd6767
diff --git 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 <translation_ml_>`_,
 and introduce yourself and the translation you're starting.
 
-Then you can bootstrap your new translation by using `cookiecutter
-<https://github.com/JulienPalard/python-docs-cookiecutter>`__ or
+Then you can bootstrap your new translation by using the `cookiecutter
+<https://github.com/python-docs-translations/python-docs-cookiecutter>`__ or
 `bootstrapper <https://github.com/python-docs-translations/python-docs-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
@@ -3,7 +3,7 @@ Translations
 ============
 
 .. toctree::
-   :maxdepth: 6
+   :maxdepth: 3
 
    translating
    coordinating
diff --git 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 <Abdur-rahmaanJ/python-docs-ar>`
-   * - `Bengali (bn_IN) <https://docs.python.org/bn-in/>`__
+   * - `Bengali (bn-IN) <https://docs.python.org/bn-in/>`__
      - Kushal Das (:github-user:`kushaldas`)
      - :github:`GitHub <python/python-docs-bn-in>`
    * - `French (fr) <https://docs.python.org/fr/>`__
      - Julien Palard (:github-user:`JulienPalard`)
      - `AFPy/python-docs-fr <https://git.afpy.org/AFPy/python-docs-fr/>`_,
        :github:`Mirror <python/python-docs-fr>`
-   * - `Greek (gr) <https://docs.python.org/gr/>`__
+   * - `Greek (gr) <https://docs.python.org/el/>`__
      - | Lysandros Nikolaou (:github-user:`lysnikolaou`),
        | Fanis Petkos (:github-user:`thepetk`),
        | Panagiotis Skias (:github-user:`skpanagiotis`)
-     - :github:`GitHub <pygreece/python-docs-gr>`
+     - :github:`GitHub <python/python-docs-el>`
    * - Hindi (hi-IN)
      - Sanyam Khurana (:github-user:`CuriousLearner`)
      - :github:`GitHub <CuriousLearner/python-docs-hi-in>`
-   * - `Hungarian (hu) <https://docs.python.org/hu/>`__ XXX This should probably be added
+   * - Hungarian (hu)
      - Tamás Bajusz (:github-user:`gbtami`)
      - :github:`GitHub <python/python-docs-hu>`,
        `Mailing list <https://mail.python.org/pipermail/python-hu>`__
@@ -69,7 +69,8 @@ For more details about translations and their progress, see `the dashboard
      - Alireza Shabani (:github-user:`revisto`)
      - :github:`GitHub <revisto/python-docs-fa>`
    * - `Polish (pl) <https://docs.python.org/pl/>`__
-     - Maciej Olko (:github-user:`m-aciek`)
+     - | Maciej Olko (:github-user:`m-aciek`)
+       | Stan Ulbrych (:github-user:`StanFromIreland`)
      - :github:`GitHub <python/python-docs-pl>`,
        `Transifex <tx_>`_,
        `Original announcement <https://mail.python.org/pipermail/doc-sig/2019-April/004106.html>`__
@@ -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 <target>``` 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 <target>`_``) should be handled similarly. If possible, the target
 should be updated to match the language.
@@ -163,34 +166,14 @@ 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 <https://docs.python.org/3/tutorial/controlflow.html#keyword-arguments>`_
-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
+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 <https://docs.python.org/3/tutorial/controlflow.html#keyword-arguments>`_
+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 <tx_>`_,
-   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 <tx_>`_ 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: