Split translating.rst into pages for Translators and Coordinators (#1575)

* Big Split

* Move links

* Fix link

* Apply suggestions from willingc

Co-authored-by: Carol Willing <[email protected]>

---------

Co-authored-by: Carol Willing <[email protected]>

Author: StanFromIreland

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",

documentation/index.rst

@@ -9,5 +9,5 @@ Documentation
    help-documenting
    style-guide
    markup
-   translating
+   translations/index
    devguide

documentation/translations/coordinating.rst

@@ -0,0 +1,123 @@
+============
+Coordinating
+============
+
+Starting a new translation
+==========================
+
+First subscribe to the `translation mailing list <translation_ml_>`_,
+and introduce yourself and the translation you're starting. Translations
+fall under the aegis of the `PSF Translation Workgroup <translation_wg_>`_
+
+Then you can bootstrap your new translation by using `cookiecutter
+<https://github.com/JulienPalard/python-docs-cookiecutter>`__ or
+`bootstrapper <https://github.com/python-docs-translations/python-docs-bootstrapper>`__.
+
+The important steps look like this:
+
+- 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.
+- 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.
+
+
+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 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 <translation_ml_>`_.
+-  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.
+-  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.
+
+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.
+
+
+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 <translation_ml_>`_ 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 <translation_ml_>`_, or better, make a PR on the `devguide
+<https://github.com/python/devguide/>`__.
+
+.. _translation_wg: https://wiki.python.org/psf/TranslationWG/Charter
+.. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/

documentation/translations/index.rst

@@ -0,0 +1,9 @@
+============
+Translations
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   translating
+   coordinating

documentation/translating.rst renamed to 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 <translation_ml_>`_,
-and introduce yourself and the translation you're starting. Translations
-fall under the aegis of the `PSF Translation Workgroup <translation_wg_>`_
-
-Then you can bootstrap your new translation by using `cookiecutter
-<https://github.com/JulienPalard/python-docs-cookiecutter>`__ or
-`bootstrapper <https://github.com/python-docs-translations/python-docs-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 <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.
-
-
-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,80 +130,11 @@ 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 <translation_ml_>`_.
--  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 <translation_ml_>`_.
-
-
-The entry for my translation is missing/not up to date on this page
--------------------------------------------------------------------
-
-Ask on the `translation mailing list <translation_ml_>`_, or better, make a PR on the `devguide
-<https://github.com/python/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 <translation_ml_>`_, 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 <translation_ml_>`_ 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?
 -------------------------------------
 
 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/