Translating¶

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.

Language	Contact	Links
Arabic (ar)	Abdur-Rahmaan Janhangeer (@Abdur-rahmaanJ)	GitHub
Bengali (bn_IN)	Kushal Das (@kushaldas)	GitHub
French (fr)	Julien Palard (@JulienPalard)	GitHub
Greek (gr)	Lysandros Nikolaou (@lysnikolaou), Fanis Petkos (@thepetk), Panagiotis Skias (@skpanagiotis)	GitHub
Hindi (hi_IN)	Sanyam Khurana (@CuriousLearner)	GitHub
Hungarian (hu)	Tamás Bajusz (@gbtami)	GitHub, mailing list
Indonesian (id)	Oon Arfiandwi (@oonid)	GitHub
Italian (it)	Alessandro Cucci (email)	GitHub, original mail
Japanese (ja)	Kinebuchi Tomohiko (@cocoatomo), Atsuo Ishimoto (@atsuoishimoto)	GitHub
Korean (ko)	오동권 (@flowdas)	GitHub
Marathi (mr)	Sanket Garade (@sanketgarade, email)	GitHub
Lithuanian (lt)	Albertas Gimbutas (@albertas, email)	Original mail
Persian (fa)	Alireza Shabani (@revisto)	GitHub
Polish (pl)	Maciej Olko (@m-aciek)	GitHub, Transifex, original mail
Portuguese (pt)	Gustavo Toffo
Brazilian Portuguese (pt-br)	Rafael Fontenelle (@rffontenelle), Marco Rougeth (@rougeth)	GitHub, wiki, Telegram, article
Romanian (ro)	Octavian Mustafa (@octaG-M, email)	GitHub
Russian (ru)	Daniil Kolesnikov (@MLGRussianXP, email)	GitHub, mail
Simplified Chinese (zh-cn)	Shengjing Zhu (@zhsj), Du, Meng (@dumeng)	GitHub, Transifex
Spanish (es)	Raúl Cumplido	GitHub
Traditional Chinese (zh-tw)	王威翔 Matt Wang (@mattwang44), Josix Wang	GitHub
Turkish (tr)	Ege Akman (@egeakman)	GitHub, RTD
Ukrainian (uk)	Dmytro Kazanzhy (@kazanzhy, email)	GitHub, Transifex

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

Then you can bootstrap your new translation by using cookiecutter or bootstrapper.

The important steps look like this:

Create the GitHub repo (anywhere) with the right hierarchy (using one of the bootstrappers).
Gather people to help you translate. You can’t do it alone.
You can use any tool to translate, as long as you can synchronize with Git. Some use Transifex, and some use only GitHub. You can choose another way if you like; it’s up to you.
Ensure we update this page to reflect your work and progress, either via a PR or by asking on the translation mailing list.
When bugs, tutorial, and library/functions are 100% completed, ask on the translation mailing list for your language to be added in the language switcher on docs.python.org.

PEP 545 summary¶

Here are the essential points of PEP 545:

Each translation is assigned an appropriate lowercased language tag, with an optional region subtag, and joined with a dash, like pt-br or fr.
Each translation is under CC0 and marked as such in the README (as in the cookiecutter).
Translation files are hosted on https://github.com/python/python-docs-{LANGUAGE_TAG} (not mandatory to start a translation, but mandatory to land on docs.python.org).
Translations having completed tutorial/, library/stdtypes and library/functions are hosted on https://docs.python.org/{LANGUAGE_TAG}/{VERSION_TAG}/.

How to get help¶

Discussions about translations occur on the Python Docs Discord #translations channel, translation mailing list, and there’s a Libera.Chat IRC channel, #python-doc.

Translation FAQ¶

Which version of the Python documentation should be translated?¶

Consensus is to work on the current stable version. You can then propagate your translation from one branch to another using pomerge.

Are there tools to help in managing the repo?¶

Here’s what we’re using:

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 is a coordinator elected?¶

There is no election; each translation has to sort this out. Here are some 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 their say on the choice.
Anyone who wants to become coordinator for their native language and shows motivation by translating and building a community will be named coordinator.
In case of concurrency between two persons, no one will sort this out for you. It is up to you two to organize a local election or whatever is needed to sort this out.
If a coordinator becomes inactive or unreachable for a long period of time, someone else can ask for a takeover on the translation mailing list.

The entry for my translation is missing/not up to date on this page¶

Ask on the translation mailing list, or better, make a PR on the devguide.

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

You can ask for help on the translation mailing list, 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 we’ll all 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 on the translation mailing list 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.

How should I translate code examples?¶

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.