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..9df1f73ed 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 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 3d64858ad..b041115e9 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -2,15 +2,21 @@ Coordinating ============ +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 +are overseen by 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 `_ +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: @@ -28,6 +34,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 the +`translations category `_ +of the Python Discourse. + + PEP 545 summary =============== @@ -50,6 +66,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 ================ @@ -73,7 +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 @@ -113,11 +138,30 @@ 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? +--------------------------------------------------------------- + +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 +--------------------------------------------------------- + +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 Python translations. +See this `Discourse thread `_ +for updates. -Ask on the `translation mailing list `_, or better, make a PR on the `devguide -`__. -.. _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/index.rst b/documentation/translations/index.rst index 67ab049f9..2f5cfe0f4 100644 --- a/documentation/translations/index.rst +++ b/documentation/translations/index.rst @@ -3,7 +3,7 @@ Translations ============ .. toctree:: - :maxdepth: 2 + :maxdepth: 3 translating coordinating diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index 47f04cef8..7d1e2f251 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -1,40 +1,43 @@ -.. _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 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. + +For more details about translations and their progress, see `the dashboard +`__. + +.. _translation-coordinators: .. list-table:: :header-rows: 1 * - Language - - Contact + - Coordination team - Links * - 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`) - - :github:`GitHub ` - * - Hindi (hi_IN) + - `AFPy/python-docs-fr `_, + :github:`mirror ` + * - `Greek (el) `__ + - | 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) @@ -42,16 +45,16 @@ details. - :github:`GitHub `, `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,43 +64,44 @@ details. - :github:`GitHub ` * - Lithuanian (lt) - Albertas Gimbutas (:github-user:`albertas`, `email `__) - - `Original mail `__ + - `original announcement `__ * - Persian (fa) - 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 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 `__, + `guide `__, `Telegram `__, `article `__ - * - Romanian (ro) + * - `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`) + - | 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`) @@ -108,33 +112,175 @@ details. - :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! +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 category <_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. + + +Translate the meaning +--------------------- + +Try to stay as close as possible to the original text. Focus on translating its +meaning in the best possible way. + + +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 +--------------- + +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. + +.. seealso:: + :doc:`../markup` + + +Translation quality +------------------- + +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. + +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. + + +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. +Translation teams should keep the translations of these terms +consistent, which is done with glossaries. + +Some general guidelines for deciding on a translation: + +- 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. +- 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 +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, 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. +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 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 `__: + This covers the history, glossary, comments, keyboard shortcuts, and more. +- `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 =============== -Which version of the Python documentation should be translated? ---------------------------------------------------------------- +Which version of the Python documentation should I work on? +----------------------------------------------------------- + +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. -Consensus is to work on the current stable version. You can then propagate your -translation from one branch to another using :pypi:`pomerge`. +The coordination team for my language is inactive, what do I do? +---------------------------------------------------------------- -How should I translate code examples? -------------------------------------- +If you would like to coordinate, open a pull request in the +`devguide `_ adding yourself, and ping +``@python/editorial-board``. -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_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/