Update translations/coordinating.rst (GH-1587)

Author: StanFromIreland

contrib/index.rst

@@ -75,7 +75,7 @@ major section at the top of each column.]*
        * :ref:`documenting`
        * :ref:`style-guide`
        * :ref:`rst-primer`
-       * :doc:`documentation/translations`
+       * :ref:`translating`
        * :ref:`devguide`
      -
        * :ref:`setup`

documentation/translations/coordinating.rst

@@ -3,79 +3,186 @@ Coordinating
 ============
 
 Information about the Python documentation translation processes is
-found in this devguide and :PEP:`545`.
-Translations are built by `docsbuild-scripts
-<https://github.com/python/docsbuild-scripts/>`__ and hosted on
-docs.python.org. Translations
-are overseen by the `Editorial Board <EB_>`_
+found on this page and in :PEP:`545`. Translations are overseen by the
+`Editorial Board <EB_>`_.
+
+.. _translation-help:
+
+Communication/help channels
+===========================
+
+Discussions about translations occur on the Python Docs Discord
+`#translations channel <https://discord.gg/h3qDwgyzga>`_, `translation
+mailing list <translation_ml_>`_, and the
+`translations category <trans_disc_>`_ of the Python Discourse.
+
+For administrative issues, ping ``@python/editorial-board``.
+
 
 Starting a new translation
 ==========================
 
-First subscribe to the `translation mailing list <translation_ml_>`_,
-and introduce yourself and the translation you're starting.
+Coordination is not a one-off task, it is a long-term commitment. Before
+you start your translation, carefully consider if you will be able to commit
+to this.
+Every coordinator should be familiar with translating: see :ref:`translating`.
+
+The following sections will guide you through setting up your translation.
+If you have any questions or need help, ask in one of the
+:ref:`help channels <translation-help>`.
+
+
+Announcement
+------------
+
+Post an announcement introducing yourself and the translation you're
+starting on `Discourse <trans_disc>`_. Also join the other communication
+channels, if possible.
+
+
+Coordination team
+-----------------
+
+Each translation team will decide on the number of coordinators.
+While initially one person is fine, we recommend expanding to having two or
+three coordinators. You can find more on choosing coordinators in the FAQ
+section on this page.
+
+
+Translation team
+----------------
+
+.. figure:: translator-workload.svg
+   :class: invert-in-dark-mode
+   :align: center
+   :alt: An exaggerated chart showing that individual translator workload
+         decreases with the number of translators.
+
+
+Gather people to translate with you. You can't do it alone.
+Update :ref:`this table <translation-coordinators>` via a PR on the devguide
+to make your translation easier to find. In the entry you can also include links
+to guides or other resources for translators.
+
+
+Repository
+----------
+
+To start your translation create a GitHub repository, under any
+account, with the correct Git hierarchy and folder structure. This can be done
+in several ways, and depends on what translation process you plan to use.
+
+Each translation is assigned an appropriate lowercase
+`IETF language tag <https://datatracker.ietf.org/doc/html/rfc5646.html>`_.
+The tag may have an optional subtag, joined with a dash.
+For example, ``pt`` (Portuguese) or ``pt-br`` (Brazilian Portuguese).
+The repository name is then: ``python-docs-TAG``
+
+The name of each branch should be the Python version it holds translations
+for, for example, ``3.14``. The files should be structured like the source files
+in `CPython/Doc <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/>`_
+
+Below, the recommended ways for starting your repository are described. You can
+choose another way if you like; it’s up to you.
+
+
+Cookiecutter/bootstrapper
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Then you can bootstrap your new translation by using the `cookiecutter
+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>`__.
-You can also start your translation using `Transifex <https://explore.transifex.com/python-doc/python-newest/>`_
-following this `guide <https://python-docs-transifex-automation.readthedocs.io/commands.html>`_.
+The repository can then be used with a pull-request based translation process.
 
-The important steps look like this:
 
-- Create the GitHub repo (any account) with the correct hierarchy by using one
-  of the bootstrappers or Transifex.
-- Gather people to help you translate. You can't do it alone.
-- You can use any tool to translate, as long as you can synchronize with Git.
-  Some use Transifex, and some use only GitHub. You can choose another
-  way if you like; it's up to you.
-- Update :doc:`this page <translating>` to reflect your work and progress, either via a
-  PR or by asking on the `translation mailing list <translation_ml_>`_.
-- When ``bugs``, ``tutorial``, and ``library/functions`` are 100%
-  completed, ask on the `translation mailing list <translation_ml_>`_ for
-  your language to be added in the language switcher on docs.python.org.
+Translation platform
+~~~~~~~~~~~~~~~~~~~~
 
+You can also start your translation using
+`Transifex <https://explore.transifex.com/python-doc/python-newest/>`_.
+This will allow you to translate via the web interface, and to use shared
+automatically updated source files.
 
-How to get help
-===============
+This is best done with a workflow that periodically checks for translations.
+An example with instructions can be found in the
+`python-docs-tx-automations documentation <https://python-docs-transifex-automation.readthedocs.io/workflows.html>`__.
+An in-depth guide for manually doing this can also be found
+in the same documentation's
+`commands page <https://python-docs-transifex-automation.readthedocs.io/commands.html>`__.
 
-Discussions about translations occur on the Python Docs Discord
-`#translations channel <https://discord.gg/h3qDwgyzga>`_, `translation
-mailing list <translation_ml_>`_, and the
-`translations category <https://discuss.python.org/c/documentation/translations/>`_
-of the Python Discourse.
+To be added as coordinators on Transifex for your language, open an issue
+in the `tracker <https://github.com/python-docs-translations/transifex-automations/issues>`__.
+
+
+Glossary
+--------
+
+Each translation team should have a way to store translations of terms to ensure
+consistency. This is often done with a glossary. More information about the use
+of glossaries can be found in the :ref:`translation-style-guide`.
+
+
+Moving the repo to the ``python`` org
+-------------------------------------
+
+This will allow you to plug your translation into docsbuild-scripts_, and it
+will be found at ``docs.python.org/LANG/``, but not in the switcher.
+
+.. TODO Give a general milestone when this will be done.
+
+Adding to the language switcher
+-------------------------------
+
+.. TODO Specify branch: https://github.com/python/devguide/issues/1586
+
+Once the following resources have been fully translated:
+
+- ``bugs.po``, with proper links to the language repository issue tracker
+- all files in the ``tutorial/`` folder
+- ``library/functions.po``, the page documenting builtins
+
+the translation can be added to the language switcher. This can be done with a
+pull request to docsbuild-scripts_, like `this commit <https://github.com/python/docsbuild-scripts/commit/e4a8aff9772738a63d0945042777d18c3d926930>`__
+if your translation was previously built but not in the switcher, or like
+`this commit <https://github.com/python/docsbuild-scripts/commit/a601ce67c6c2f3be7fde3376d3e5d3851f19950b>`__
+if this is it's initial addition.
 
 
 PEP 545 summary
 ===============
 
 Here are the essential points of :PEP:`545`:
 
-- Each translation is assigned an appropriate lowercased language tag,
-  with an optional region subtag, and joined with a dash, like
-  ``pt-br`` or ``fr``.
+- Each translation is assigned an appropriate lowercase
+  `IETF language tag <https://datatracker.ietf.org/doc/html/rfc5646.html>`_.
+  The tag may have an optional region subtag, joined with a dash.
+  For example, ``pt`` (Portuguese) or ``pt-br`` (Brazilian Portuguese).
 
-- Each translation is under CC0 and marked as such in the README (as in
-  the cookiecutter).
+- Each translation is under CC0 and is marked as such in the README.
 
-- Translation files are hosted on
-  ``https://github.com/python/python-docs-{LANGUAGE_TAG}`` (not
-  mandatory to start a translation, but mandatory to land on
-  ``docs.python.org``).
+- Translation files are hosted in repositories under the Python org:
+  ``https://github.com/python/python-docs-{LANGUAGE_TAG}``
 
-- Translations having completed ``tutorial/``, ``library/stdtypes``
-  and ``library/functions`` are hosted on
-  ``https://docs.python.org/{LANGUAGE_TAG}/{VERSION_TAG}/``.
+- Translations having completed ``bugs``, ``tutorial/``
+  and ``library/functions`` are added to the language switcher.
 
 
-Transifex
-=========
+Translating Sphinx
+==================
 
-If you need help from a Transifex administrator, open an issue on the
-`tracker <https://github.com/python-docs-translations/transifex-automations/issues>`_.
+Some messages that appear in the docs must be translated in the
+`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 `python-docs-theme <https://github.com/python/python-docs-theme>`_
+(currently this is not possible; see this
+`issue <https://github.com/python/python-docs-theme/issues/194>`__).
+Coordinators should direct some translators there, so that the documentation
+is fully translated.
 
 
-Coordinating FAQ
+Coordination FAQ
 ================
 
 Are there tools to help in managing the repo?
@@ -98,12 +205,26 @@ More related tools and projects can be found in the
 
 __ https://github.com/python-docs-translations
 
-How is a coordinator elected?
------------------------------
+
+How should I test my translation?
+---------------------------------
+
+Testing should ideally be set up in your repository, and will help catch errors
+early and ensure translation quality. Testing generally consists of building, and
+linting with :pypi:`sphinx-lint`.
+
+See `this documentation <https://python-docs-transifex-automation.readthedocs.io/workflows.html#test-build-workflow>`_
+for sample workflows with usage guides.
+
+The `dashboard <https://python-docs-translations.github.io/dashboard/metadata.html>`_
+also tests translations and uploads error logs.
+
+
+How is a coordination team chosen?
+----------------------------------
 
 Each translation team will decide on the number of coordinators.
 We recommend two or three coordinators, though you may begin with one.
-Here are some general suggestions.
 
 -  Coordinator requests are to be public on the `translation mailing list <translation_ml_>`_.
 -  If the given language has a native core team member, they have input
@@ -114,25 +235,28 @@ Here are some general suggestions.
 -  We expect the local community to self-organize coordinators and contributors.
    If you have questions, please ask on the mailing list or Discourse.
 -  If a coordinator becomes inactive or unreachable for a long
-   period of time, someone else can ask to be added as a primary coordinator on the `translation mailing list <translation_ml_>`_.
-   As a community resource, we aim to keep translations up to date with active contributors, including coordinators.
+   period of time, someone else can ask to be added as a primary coordinator on
+   the `translation mailing list <translation_ml_>`_.
+   As a community resource, we aim to keep translations up to date with active
+   contributors, including coordinators.
+
 
 I have a translation, but it's not in Git. What should I do?
 ------------------------------------------------------------
 
-You can ask for help on the `translation mailing list <translation_ml_>`_, and
-the team will help you create an appropriate repository. You can still use tools like transifex,
-if you like.
+You can ask for help in one of the :ref:`translation-help`, and
+the team will help you create an appropriate repository. You can still use tools
+like Transifex, if you like.
 
 
 My Git hierarchy does not match yours. Can I keep it?
 -----------------------------------------------------
 
-No, inside the ``github.com/python`` organization we’ll all have the
+No, inside the ``github.com/python`` organization all repositories must have the
 exact same hierarchy so bots will be able to build all of our
-translations. So you may have to convert from one hierarchy to another.
-Ask for help on the `translation mailing list <translation_ml_>`_ if you’re
-not sure on how to do it.
+translations. So, you may have to convert from one hierarchy to another.
+Ask for help in one of the :ref:`translation-help` if you’re not sure on how to
+do it.
 
 
 What hierarchy should I use in my GitHub repository?
@@ -143,9 +267,6 @@ files in the root of the repository using the ``gettext_compact=0``
 style.
 
 
-.. XXX Explain necessary folder structure
-
-
 Which version of the Python documentation should be translated?
 ---------------------------------------------------------------
 
@@ -156,8 +277,14 @@ propagate your translation from one branch to another using :pypi:`pomerge`.
 The entry for my translation is missing or not up to date
 ---------------------------------------------------------
 
-Ask on the `translation mailing list <translation_ml_>`_, or better, make a PR
-on the `devguide <https://github.com/python/devguide/>`__.
+Make a PR on the `devguide <https://github.com/python/devguide/>`__ to update it.
+
+
+How are translations built?
+---------------------------
+
+Translations are built by `docsbuild-scripts <https://github.com/python/docsbuild-scripts/>`__
+and hosted on docs.python.org.
 
 
 Is there a Weblate instance we can translate on?
@@ -170,3 +297,5 @@ for updates.
 
 .. _EB: https://python.github.io/editorial-board/
 .. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/
+.. _trans_disc: https://discuss.python.org/c/documentation/translations/
+.. _docsbuild-scripts: https://github.com/python/docsbuild-scripts

documentation/translations/index.rst

@@ -3,7 +3,7 @@ Translations
 ============
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 4
 
    translating
    coordinating

documentation/translations/translating.rst

@@ -11,7 +11,7 @@ in production and can be found in the language switcher; others are works in
 progress. To get started read your repository's contributing guide, which is
 generally the ``README`` file, and this page.
 If your language isn’t listed below, feel free to start the translation!
-See :doc:`coordinating` guide to get started.
+See :doc:`coordination <coordinating>` to get started.
 
 For more details about translations and their progress, see `the dashboard
 <https://python-docs-translations.github.io/dashboard/>`__.
@@ -126,12 +126,13 @@ General discussions about translations occur on the Python Docs Discord
 mailing list <translation_ml_>`_, and the `translations category <_discourse>`_
 of the Python Discourse.
 
+.. _translation-style-guide:
 
 Style guide
 ===========
 
 Before translating, you should familiarize yourself with the general
-documentation :doc:`style guide<../style-guide>`. Some translation-specific
+documentation :doc:`style guide <../style-guide>`. Some translation-specific
 guidelines are explained below.
 
 
@@ -157,7 +158,7 @@ The Python docs contain many roles (``:role:`target```) that link to other parts
 of the documentation.
 Do not translate reStructuredText roles targets, such as ``:func:`print``` or
 ``:ref:`some-section``` because it will break the link.
-If alternate text (``:role:`text <target>``` is provided, it generally
+If alternate text (``:role:`text <target>```) is provided, it generally
 should be translated. You can also introduce alternate text for translation if
 the target is not a name or term.
 
@@ -279,8 +280,8 @@ The coordination team for my language is inactive, what do I do?
 ----------------------------------------------------------------
 
 If you would like to coordinate, open a pull request in the
-`devguide <https://github.com/python/devguide>`_ adding yourself, and ping
-``@python/editorial-board``.
+`devguide <https://github.com/python/devguide>`_ adding yourself to the table
+at the top of this page, and ping ``@python/editorial-board``.
 
 
 .. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/