For visibility, @Stanfromireland has opened a PR to the devguide that proposes following translation guide:
How to get help
===============
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 <https://discord.gg/h3qDwgyzga>`_, `translation
mailing list <translation_ml_>`_, 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 <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.
Links (```text <target>`_``) 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 <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, 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 <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:
- `Getting started as a translator <https://help.transifex.com/en/articles/6248698-getting-started-as-a-translator>`__:
This covers signing up for an account and joining a translation team.
- `Translating with the Web Editor <https://help.transifex.com/en/articles/6318216-translating-with-the-web-editor>`__:
This covers getting to the editor, searching and filtering strings, and translating strings.
- `Other Tools in the Editor <https://help.transifex.com/en/articles/6318944-other-tools-in-the-editor>`__:
This covers the history, glossary, comments, keyboard shortcuts, and more.
- `Starting with the basics <https://help.transifex.com/en/collections/3441044-starting-with-the-basics>`__:
A group of documents with basic information.
For further information about Transifex see our `documentation <https://python-docs-transifex-automation.readthedocs.io/>`_.
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 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.
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``.
.. _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/
It can be reviewed at https://github.com/python/devguide/pull/1576.
