Translate the meaning¶

Try to stay as close as possible to the original text. Focus on translating itsmeaning in the best possible way.

Gender neutrality¶

Many languages use grammatical gender. When possible and natural, prefergender-neutral or inclusive forms. Aim to reflect the inclusive tone ofthe English documentation.

Roles and links¶

The Python docs contain many roles (:role:`target`) that link to other partsof 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 generallyshould be translated. You can also introduce alternate text for translation ifthe target is not a name or term.

Links (`text<target>`_) should be handled similarly. If possible, the targetshould be updated to match the language.

Translation quality¶

Translators should know both English and the language they aretranslating to. Translators should aim for a similar level of quality as thatof the English documentation.

Do not rely solely on machine translation. These tools can be useful to speed upwork, but often produce inaccurate or misleading results and should be reviewedby a human.

Terminology¶

The documentation is full of technical terms, some are common in generalprogramming and have translations, whereas others are specific to Pythonand previous translations are not available.Translation teams should keep the translations of these termsconsistent, 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 familiarwith 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 tohelp fellow translators and ensure consistency.

Dialects¶

Some translations receive contributions from people of several different dialects,understandably the language will differ. It is recommended however thattranslators 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 thetutorialis provided below:

defcheeseshop(kind,*arguments,**keywords):print("-- Czy jest może",kind,"?")print("-- Przykro mi, nie mamy już sera",kind)forarginarguments:print(arg)print("-"*40)forkwinkeywords:print(kw,":",keywords[kw])

How do I build a docs translation?¶

To build a documentation translation for a specific language,you need to have Python installed and alocal copy of theCPython repository andtranslation repository (see table above). The PO files must be placedin alocales/LANG/LC_MESSAGES/ (replacingLANG with the translation’slanguage code) folder inside theDoc/ directory of the CPython repository.

You can then build withmake by addingaSPHINXOPTS="-Dlanguage=LANG" variable before the targetor by usingSphinx directly and adding a-Dlanguage=LANG option. For example:

# Build the HTML format of the Polish translation using makemakeSPHINXOPTS="-D language=pl"html# Build the HTML format of the Romanian translation using Sphinx directlypython-msphinx-bhtml.build/html-Dlanguage=ro

Which version of the Python documentation should I work on?¶

You should work on the latest branch available to you for translation (this shouldbe the latest non-alpha branch), the translations should then be propagated byyour languages coordination team.

How do I translate the Python Docs Sphinx Theme?¶

The Sphinx theme for the Python documentation supports localization.

You can translate either onTransifex(seetranslating on Transifex for more information)or locally by following the steps outlined below.

To translate locally, clone thePython Docs Sphinx Theme repository and run the followingcommands to generate the PO files. ReplaceLANG with the same language codethat is used for the docs translation:

pythonbabel_runner.pyextractpythonbabel_runner.pyinit-lLANG

The file can then be found at:

python-docs-theme/locale/LANG/LC_MESSAGES/python-docs-theme.po

After translating, submit your PO file via a pull request to therepository.See ourGit bootcamp and cheat sheet for more information about using Git.

To update an existing translation after source changes, run:

pythonbabel_runner.pyupdate# To update source for all languagespythonbabel_runner.pyupdate-lLANG# To update source just for LANG

The coordination team for my language is inactive, what do I do?¶

If you would like to coordinate, open a pull request in thedevguide adding yourself to the tableat the top of this page, and ping@python/editorial-board.