Initial

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`
-       * :ref:`translating`
+       * :doc:`documentation/translations`
        * :ref:`devguide`
      -
        * :ref:`setup`

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 <translating>`.
+Translations fall under the aegis of the
+`Editorial Board <https://python.github.io/editorial-board/>`_.
+For a list of translations and their coordinators, see
+:ref:`this table of translations <translation-coordinators>`.

documentation/translations/coordinating.rst

@@ -2,13 +2,20 @@
 Coordinating
 ============
 
+Python documentation translations are governed by :PEP:`545`.
+They are built by `docsbuild-scripts
+<https://github.com/python/docsbuild-scripts/>`__ and hosted on
+docs.python.org.
+
 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_>`_
 
+.. https://github.com/python/editorial-board/issues/32
+
 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>`__.
@@ -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 <https://discord.gg/h3qDwgyzga>`_, `translation
+mailing list <translation_ml_>`_, and and the
+`translations subsection <https://discuss.python.org/c/documentation/translations/>`_
+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 <translation_ml_>`_.
 -  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 <translation_ml_>`_, or better, make a PR on the `devguide
 <https://github.com/python/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/

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
-<https://github.com/python/docsbuild-scripts/>`__ and hosted on
-docs.python.org. There are several documentation translations already
-in production; others are works in progress. See `the dashboard
-<https://python-docs-translations.github.io/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
+<https://python-docs-translations.github.io/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 <Abdur-rahmaanJ/python-docs-ar>`
-   * - Bengali (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`)
-     - :github:`GitHub <python/python-docs-fr>`
-   * - Greek (gr)
-     - Lysandros Nikolaou (:github-user:`lysnikolaou`),
-       Fanis Petkos (:github-user:`thepetk`),
-       Panagiotis Skias (:github-user:`skpanagiotis`)
+     - `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/>`__ XXX Should be added soonish
+     - | Lysandros Nikolaou (:github-user:`lysnikolaou`),
+       | Fanis Petkos (:github-user:`thepetk`),
+       | Panagiotis Skias (:github-user:`skpanagiotis`)
      - :github:`GitHub <pygreece/python-docs-gr>`
    * - Hindi (hi_IN)
      - Sanyam Khurana (:github-user:`CuriousLearner`)
-     - :github:`GitHub <CuriousLearner/python-docs-hi-in>`
-   * - Hungarian (hu)
+     - :github:`GitHub <CuriousLearner/python-docs-hi-in>` XXX Message user in issue tracker https://github.com/CuriousLearner/python-docs-hi-in/issues/5
+   * - `Hungarian (hu) <https://docs.python.org/hu/>`__ XXX This should probably be added
      - Tamás Bajusz (:github-user:`gbtami`)
      - :github:`GitHub <python/python-docs-hu>`,
-       `mailing list <https://mail.python.org/pipermail/python-hu>`__
+       `Mailing list <https://mail.python.org/pipermail/python-hu>`__
    * - `Indonesian (id) <https://docs.python.org/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 <python/python-docs-id>`
-   * - Italian (it)
+   * - `Italian (it) <https://docs.python.org/it/>`__
      - Alessandro Cucci (`email <mailto:alessandro.cucci@gmail.com>`__)
      - :github:`GitHub <python/python-docs-it>`,
-       `original mail <https://mail.python.org/pipermail/doc-sig/2019-April/004114.html>`__
+       `Original announcement <https://mail.python.org/pipermail/doc-sig/2019-April/004114.html>`__
    * - `Japanese (ja) <https://docs.python.org/ja/>`__
-     - Kinebuchi Tomohiko (:github-user:`cocoatomo`),
-       Atsuo Ishimoto (:github-user:`atsuoishimoto`)
+     - | Kinebuchi Tomohiko (:github-user:`cocoatomo`),
+       | Atsuo Ishimoto (:github-user:`atsuoishimoto`)
      - :github:`GitHub <python/python-docs-ja>`
    * - `Korean (ko) <https://docs.python.org/ko/>`__
      - 오동권 (:github-user:`flowdas`)
@@ -61,32 +66,32 @@ details.
      - :github:`GitHub <sanketgarade/python-doc-mr>`
    * - Lithuanian (lt)
      - Albertas Gimbutas (:github-user:`albertas`, `email <mailto:albertasgim@gmail.com>`__)
-     - `Original mail <https://mail.python.org/pipermail/doc-sig/2019-July/004138.html>`__
+     - `Original announcement <https://mail.python.org/pipermail/doc-sig/2019-July/004138.html>`__
    * - Persian (fa)
      - Alireza Shabani (:github-user:`revisto`)
      - :github:`GitHub <revisto/python-docs-fa>`
    * - `Polish (pl) <https://docs.python.org/pl/>`__
      - Maciej Olko (:github-user:`m-aciek`)
      - :github:`GitHub <python/python-docs-pl>`,
        `Transifex <tx_>`_,
-       `original mail <https://mail.python.org/pipermail/doc-sig/2019-April/004106.html>`__
+       `Original announcement <https://mail.python.org/pipermail/doc-sig/2019-April/004106.html>`__
    * - Portuguese (pt)
      - Gustavo Toffo
      -
    * - `Brazilian Portuguese (pt-br) <https://docs.python.org/pt-br/>`__
-     - Rafael Fontenelle (:github-user:`rffontenelle`),
-       Marco Rougeth (:github-user:`rougeth`)
+     - | Rafael Fontenelle (:github-user:`rffontenelle`),
+       | Marco Rougeth (:github-user:`rougeth`)
      - :github:`GitHub <python/python-docs-pt-br>`,
-       `wiki <https://python.org.br/traducao/>`__,
+       `Wiki <https://python.org.br/traducao/>`__,
        `Telegram <https://t.me/pybr_i18n>`__,
-       `article <https://rgth.co/blog/python-ptbr-cenario-atual/>`__
-   * - Romanian (ro)
+       `Article <https://rgth.co/blog/python-ptbr-cenario-atual/>`__
+   * - `Romanian (ro)  <https://docs.python.org/ro/>`__
      - Octavian Mustafa (:github-user:`octaG-M`, `email <mailto:octawian@yahoo.com>`__)
-     - :github:`GitHub <octaG-M/python-docs-ro>`
+     - :github:`GitHub <python/python-docs-ro>`
    * - Russian (ru)
      - Daniil Kolesnikov (:github-user:`MLGRussianXP`, `email <mailto:mlgrussianxp@gmail.com>`__)
      - :github:`GitHub <MLGRussianXP/python-docs-ru>`,
-       `mail <https://mail.python.org/pipermail/doc-sig/2019-May/004131.html>`__
+       `Original announcement <https://mail.python.org/pipermail/doc-sig/2019-May/004131.html>`__
    * - `Simplified Chinese (zh-cn) <https://docs.python.org/zh-cn/>`__
      - Shengjing Zhu (:github-user:`zhsj`),
        Du, Meng (:github-user:`dumeng`)
@@ -102,39 +107,160 @@ details.
    * - `Turkish (tr) <https://docs.python.org/tr/>`__
      - Ege Akman (:github-user:`egeakman`)
      - :github:`GitHub <python/python-docs-tr>`,
-       `RTD <https://python-docs-tr.readthedocs.io/>`__
+       `RTD <https://python-docs-tr.readthedocs.io/>`__ XXX Why keep this with python build? Ask Ege
    * - `Ukrainian (uk) <https://docs.python.org/uk/>`__
      - Dmytro Kazanzhy (:github-user:`kazanzhy`, `email <mailto:dkazanzhy@gmail.com>`__)
      - :github:`GitHub <python/python-docs-uk>`,
        `Transifex <tx_>`_
 
-.. _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 <https://discord.gg/h3qDwgyzga>`_, `translation
-mailing list <translation_ml_>`_, and there's a `Libera.Chat IRC
-<https://libera.chat/>`_ channel, ``#python-doc``.
+mailing list <translation_ml_>`_, 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 <target>``` is provided, it can be translated.
+
+Links (```text <target>`_``) 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 <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
+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 <tx_>`_, 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 <https://python-docs-transifex-automation.readthedocs.io/new-translators.html>`_.
+.. XXX Move stuff here, discuss w Rafael?
+
+If you need help from a Transifex administrator, open an issue on the
+`tracker <https://github.com/python-docs-translations/transifex-automations/issues>`_.
+.. 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 <https://github.com/python/editorial-board/issues>`_.
+
+.. 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/