Coordinating

Information about the Python documentation translation processes is found on this page and in PEP 545. Translations are overseen by the Editorial Board.

Communication/help channels

Discussions about translations occur on the Python Docs Discord #translations channel, translation mailing list, and the translations category of the Python Discourse.

For administrative issues, ping @python/editorial-board.

Starting a new translation

Coordination is not a one-off task, it is a long-term commitment. Before you start your translation, carefully consider if you will be able to commit to this. Every coordinator should be familiar with translating: see Translating.

The following sections will guide you through setting up your translation. If you have any questions or need help, ask in one of the help channels.

Announcement

Post an announcement introducing yourself and the translation you’re starting on Discourse. Also join the other communication channels, if possible.

Coordination team

Each translation team will decide on the number of coordinators. While initially one person is fine, we recommend expanding to having two or three coordinators. You can find more on choosing coordinators in the FAQ section on this page.

Translation team

Gather people to translate with you. You can’t do it alone. Update this table via a PR on the devguide to make your translation easier to find. In the entry you can also include links to guides or other resources for translators.

Repository

To start your translation create a GitHub repository, under any account, with the correct Git hierarchy and folder structure. This can be done in several ways, and depends on what translation process you plan to use.

Each translation is assigned an appropriate lowercase IETF language tag. The tag may have an optional subtag, joined with a dash. For example, pt (Portuguese) or pt-br (Brazilian Portuguese). The repository name is then: python-docs-TAG

The name of each branch should be the Python version it holds translations for, for example, 3.14. The files should be structured like the source files in CPython/Doc. A correctly set up repository looks like this: python-docs-pl

Below, the recommended ways for starting your repository are described. You can choose another way if you like; it’s up to you.

Cookiecutter/bootstrapper

You can bootstrap your new translation by using the cookiecutter or bootstrapper. The repository can then be used with a pull-request based translation process.

Translation platform

You can also start your translation using Transifex. This will allow you to translate via the web interface, and to use shared automatically updated source files.

This is best done with a workflow that periodically checks for translations. An example with instructions can be found in the python-docs-tx-automations documentation. An in-depth guide for manually doing this can also be found in the same documentation’s commands page.

To be added as coordinators on Transifex for your language, open an issue in the tracker.

Glossary

Each translation team should have a way to store translations of terms to ensure consistency. This is often done with a glossary. More information about the use of glossaries can be found in the Style guide.

Moving the repo to the python org

This will allow you to plug your translation into docsbuild-scripts, and it will be found at docs.python.org/LANG/, but not in the switcher.

Adding to the language switcher

Once the following resources have been fully translated:

• bugs.po, with proper links to the language repository issue tracker

• all files in the tutorial/ folder

• library/functions.po, the page documenting builtins

the translation can be added to the language switcher. This can be done with a pull request to docsbuild-scripts, like this commit if your translation was previously built but not in the switcher, or like this commit if this is it’s initial addition.

PEP 545 summary

Here are the essential points of PEP 545:

• Each translation is assigned an appropriate lowercase IETF language tag. The tag may have an optional region subtag, joined with a dash. For example, pt (Portuguese) or pt-br (Brazilian Portuguese).

• Each translation is under CC0 and is marked as such in the README.

• Translation files are hosted in repositories under the Python org: https://github.com/python/python-docs-{LANGUAGE_TAG}

• Translations having completed bugs, tutorial/ and library/functions are added to the language switcher.

Translating Sphinx

Some messages that appear in the docs must be translated in the Sphinx project (sphinx-doc on Transifex) or in the python-docs-theme (currently this is not possible; see this issue). Coordinators should direct some translators there, so that the documentation is fully translated.

Coordination FAQ

Are there tools to help in managing the repo?

Here’s what we’re using:

• poutils which includes:

  • pomerge to propagate translations from one file to others.

  • pospell to check for typos in .po files.

  • powrap to rewrap the .po files before committing. This helps keep Git diffs short.

  • potodo to list what needs to be translated.

• sphinx-lint to validate reST syntax in translation files.

More related tools and projects can be found in the python-docs-translations organisation on GitHub.

How should I test my translation?

Testing should ideally be set up in your repository, and will help catch errors early and ensure translation quality. Testing generally consists of building, and linting with sphinx-lint.

See this documentation for sample workflows with usage guides.

The dashboard also tests translations and uploads error logs.

How is a coordination team chosen?

Each translation team will decide on the number of coordinators. We recommend two or three coordinators, though you may begin with one.

• Coordinator requests are to be public on the translation mailing list.

• If the given language has a native core team member, they have input on the coordinator request.

• Anyone who wants to become coordinator for their native language and shows motivation by translating and building a community will be named coordinator.

• We expect the local community to self-organize coordinators and contributors. If you have questions, please ask on the mailing list or Discourse.

• If a coordinator becomes inactive or unreachable for a long period of time, someone else can ask to be added as a primary coordinator on the translation mailing list. As a community resource, we aim to keep translations up to date with active contributors, including coordinators.

I have a translation, but it’s not in Git. What should I do?

You can ask for help in one of the Communication/help channels, and the team will help you create an appropriate repository. You can still use tools like Transifex, if you like.

My Git hierarchy does not match yours. Can I keep it?

No, inside the github.com/python organization all repositories must have the exact same hierarchy so bots will be able to build all of our translations. So, you may have to convert from one hierarchy to another. Ask for help in one of the Communication/help channels if you’re not sure on how to do it.

What hierarchy should I use in my GitHub repository?

As for every project, we have a branch per version. We store .po files in the root of the repository using the gettext_compact=0 style.

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 pomerge.

The entry for my translation is missing or not up to date

Make a PR on the devguide to update it.

How are translations built?

Translations are built by docsbuild-scripts and hosted on docs.python.org.

Is there a Weblate instance we can translate on?

There is currently no Weblate instance for Python translations. See this Discourse thread for updates.