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.
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 the translations category
of the Python Discourse.
Before translating, you should familiarize yourself with the general documentation :doc:`style guide<../style-guide>`. Some translation-specific guidelines are explained below.
Try to stay as close as possible to the original text. Focus on translating its meaning in the best possible way.
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.
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`
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.
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.
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.
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:
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])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.
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`.
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.
If you would like to coordinate, open a pull request in the
devguide adding yourself, and ping
@python/editorial-board.