The intent of this PEP is to make existing translations of the PythonDocumentation more accessible and discoverable. By doing so, we hopeto attract and motivate new translators and new translations.
Translated documentation will be hosted on python.org. Examples oftwo active translation teams:
https://docs.python.org/en/ will redirect tohttps://docs.python.org/.
Sources of translated documentation will be hosted in the Pythonorganization on GitHub:https://github.com/python/. Contributors willhave to accept a Documentation Contribution Agreement.
On the French#python-fr IRC channel on freenode, it’s not rare tomeet people who don’t speak English and so are unable to read thePython official documentation. Python wants to be widely availableto all users in any language: this is also why Python 3 supportsany non-ASCII identifiers:PEP 3131
There are at least 4 groups of people who are translating the Pythondocumentation to their native language (French[16][17][18],Japanese[19][20], Spanish[21], Hungarian[26][27]) eventhough their translations are not visible on d.p.o. Other, lessvisible and less organized groups, are also translating thedocumentation, we’ve heard of Russian[25], Chinese andKorean. Others we haven’t found yet might also exist. This PEPdefines rules describing how to move translations on docs.python.orgso they can easily be found by developers, newcomers and potentialtranslators.
The Japanese team has (as of March 2017) translated ~80% of thedocumentation, the French team ~20%. French translation went from 6%to 23% in 2016[13] with 7 contributors[14], proving a translationteam can be faster than the rate the documentation mutates.
Quoting Xiang Zhang about Chinese translations:
I have seen several groups trying to translate part of our officialdoc. But their efforts are disperse and quickly become lost becausethey are not organized to work towards a single common result andtheir results are hold anywhere on the Web and hard to find. Anofficial one could help ease the pain.
Considering that issues opened about translations may be written inthe translation language, which can be considered noise but at leastis inconsistent, issues should not be placed in theCPython issue tracker.
As all translation must have their own GitHub project (seeRepositoryfor Po Files), they must use the associated GitHub issue tracker.
Considering the noise induced by translation issues redacted in anylanguages which may beyond every warnings land in the issue tracker, triage willhave to be done. Considering that translations already exist and arenot actually a source of noise in issue tracker, an unmanageable amount ofwork is not to be expected. Considering that Xiang Zhang and VictorStinner are already triaging, and Julien Palard is willing to help onthis task, noise on issue tracker is not to be expected.
Also, language team coordinators (seeLanguage Team) should helpwith triaging the issue tracker by properly indicating, in the language of theissue author if required, the right issue tracker.
Translation teams should focus on last stable versions, and use tools(scripts, translation memory, …) to automatically translate what isdone in one branch to other branches.
Note
Translation memories are a kind of database of previously translatedparagraphs, even removed ones. See alsoSphinx Internationalization.
The newest currently stable branch will be translated and translationscan be propagated to other branches. The scripts to build the documentation of olderbranches needs to be modified to support translation[12], whereasthese branches now only accept security-only fixes.
The development branch (main) should have a lower translation prioritythan stable branches. But docsbuild-scripts should build it anyway soit is possible for a team to work on it to be ready for the nextrelease.
Different translations can be identified by changing one of thefollowing: Country Code Top Level Domain (CCTLD),path segment, subdomain or content negotiation.
Buying a CCTLD for each translations is expensive, time-consuming, andsometimes almost impossible when already registered, this solutionshould be avoided.
Using subdomains like “es.docs.python.org” or “docs.es.python.org” ispossible but confusing (“is ites.docs.python.org ordocs.es.python.org?”). Hyphens in subdomains likept-br.doc.python.org is uncommon and SEOMoz[23] correlated thepresence of hyphens as a negative factor. Usage of underscores insubdomain is prohibited by theRFC 1123, section 2.1. Finally,using subdomains means creating TLS certificates for eachlanguage. This not only requires more maintenance but will also causeissues in language switcher if, as for version switcher, we want apreflight to check if the translation exists in the given version:preflight will probably be blocked by same-origin-policy. WildcardTLS certificates are very expensive.
Using content negotiation (HTTP headersAccept-Language in therequest andVary:Accept-Language) leads to a bad user experiencewhere they can’t easily change the language. According to Mozilla:“This header is a hint to be used when the server has no way ofdetermining the language via another way, like a specific URL, that iscontrolled by an explicit user decision.”[24]. As we want to beable to easily change the language, we should not use the contentnegotiation as a main language determination, so we need somethingelse.
Last solution is to use the URL path, which looks readable, allowsfor an easy switch from a language to another, and nicely acceptshyphens. Typically something like: “docs.python.org/de/” or, byusing a hyphen: “docs.python.org/pt-BR/”.
As for the version, sphinx-doc does not support compiling for multiplelanguages, so we’ll have full builds rooted under a path, exactly likewe’re already doing with versions.
So we can have “docs.python.org/de/3.6/” or“docs.python.org/3.6/de/”. A question that arises is:“Does the language contain multiple versions or does the version containmultiple languages?”. As versions exist in any case and translationsfor a given version may or may not exist, we may prefer“docs.python.org/3.6/de/”, but doing so scatters languages everywhere.Having “/de/3.6/” is clearer, meaning: “everything under /de/ is writtenin German”. Having the version at the end is also a habit taken byreaders of the documentation: they like to easily change the versionby changing the end of the path.
So we should use the following pattern:“docs.python.org/LANGUAGE_TAG/VERSION/”.
The current documentation is not moved to “/en/”, instead“docs.python.org/en/” will redirect to “docs.python.org”.
A common notation for language tags is theIETF Language Tag[4] based on ISO 639, although gettext uses ISO 639 tags withunderscores (ex:pt_BR) instead of dashes to join tags[5](ex:pt-BR). Examples of IETF Language Tags:fr (French),ja (Japanese),pt-BR (Orthographic formulation of 1943 -Official in Brazil).
It is more common to see dashes instead of underscores in URLs[6],so we should use IETF language tags, even if sphinx uses gettextinternally: URLs are not meant to leak the underlying implementation.
It’s uncommon to see capitalized letters in URLs, and docs.python.orgdoesn’t use any, so it may hurt readability by attracting the eye on it,like in: “https://docs.python.org/pt-BR/3.6/library/stdtypes.html”.RFC 5646#section-2.1.1(Tags for Identifying Languages (IETF)) section-2.1states that tags are not case sensitive. As the RFC allows lower case,and it enhances readability, we should use lowercased tags likept-br.
We may drop the region subtag when it does not add distinguishinginformation, for example: “de-DE” or “fr-FR”. (Although it mightmake sense, respectively meaning “German as spoken in Germany”and “French as spoken in France”). But when the region subtagactually adds information, for example “pt-BR” or “Portuguese asspoken in Brazil”, it should be kept.
So we should use IETF language tags, lowercased, like/fr/,/pt-br/,/de/ and so on.
Currently docsbuild-scripts are building the documentation[8].These scripts should be modified to fetch and build translations.
Building new translations is like building new versions so, while we’readding complexity it is not that much.
Two steps should be configurable distinctively: Building a new language,and adding it to the language switcher. This allows a transition stepbetween “we accepted the language” and “it is translated enough to bemade public”. During this step, translators can review theirmodifications on d.p.o without having to build the documentationlocally.
From the translation repositories, only the.po files should beopened by the docsbuild-script to keep the attack surface and probablebug sources at a minimum. This means no translation can patch sphinxto advertise their translation tool. (This specific feature should behandled by sphinx anyway[9]).
Thedoc-sig mailing list will be used to discuss cross-languagechanges on translated documentation.
There is also the i18n-sig list but it’s more oriented towards i18n APIs[1] than translating the Python documentation.
Due to the Python community being highly active on IRC, we shouldcreate a new IRC channel on freenode, typically #python-doc forconsistency with the mailing list name.
Each language coordinator can organize their own team, even by choosinganother chat system if the local usage asks for it. As local teamswill write in their native languages, we don’t want each team in asingle channel. It’s also natural for the local teams to reusetheir local channels like “#python-fr” for French translators.
Considering that each translation team may want to use differenttranslation tools, and that those tools should easily be synchronizedwith git, all translations should expose their.po files via a gitrepository.
Considering that each translation will be exposed via gitrepositories, and that Python has migrated to GitHub, translationswill be hosted on GitHub.
For consistency and discoverability, all translations should be in thesame GitHub organization and named according to a common pattern.
Given that we want translations to be official, and that Pythonalready has a GitHub organization, translations should be hosted asprojects of thePython GitHub organization.
For consistency, translation repositories should be calledpython-docs-LANGUAGE_TAG[22], using the language tag used inpaths: without region subtag if redundant, and lowercased.
The docsbuild-scripts may enforce this rule by refusing to fetchoutside of the Python organization or a wrongly named repository.
The CLA bot may be used on the translation repositories, but with alimited effect as local coordinators may synchronize themselves withtranslations from an external tool, like transifex, and lose trackof who translated what in the process.
Versions can be hosted on different repositories, different directoriesor different branches. Storing them on different repositories willprobably pollute the Python GitHub organization. As itis typical and natural to use branches to separate versions, branchesshould be used to do so.
Most of the translation work is actually done on Transifex[15].
Other tools may be used later likehttps://pontoon.mozilla.org/andhttp://zanata.org/.
Thepython-docs-translations GitHub organizationis home to several useful translation tools includingtranslations.python.org(python-docs-translations/dashboard).
Documentation does require a license from the translator, as itinvolves creativity in the expression of the ideas.
There’s multiple solutions, quoting Van Lindberg from the PSF askedabout the subject:
- Docs should either have the copyright assigned or be under CCO. Apermissive software license (like Apache or MIT) would also get thejob done, although it is not quite fit for task.
- The translators should either sign an agreement or submit adeclaration of the license with the translation.
- We should have in the project page an invitation for people tocontribute under a defined license, with acceptance defined by theiract of contribution. Such as:
“By posting this project on Transifex and inviting you toparticipate, we are proposing an agreement that you will provideyour translation for the PSF’s use under the CC0 license. In return,you may noted that you were the translator for the portion youtranslate. You signify acceptance of this agreement by submittingyour work to the PSF for inclusion in the documentation.”
It looks like having a “Documentation Contribution Agreement”is the most simple thing we can do as we can use multiple ways (GitHubbots, invitation page, …) in different context to ensure contributorsare agreeing with it.
Each language team should have one coordinator responsible for:
It would be possible to introduce a “simplified English” version likeWikipedia did[10], as discussed on python-dev[11], targetingEnglish learners and children.
Pros: It yields a single translation, theoretically readable byeveryone and reviewable by current maintainers.
Cons: Subtle details may be lost, and translators from English to Englishmay be hard to find as stated by Wikipedia:
> The main English Wikipedia has 5 million articles, written by nearly140K active users; the Swedish Wikipedia is almost as big, 3M articlesfrom only 3K active users; but the Simple English Wikipedia has just123K articles and 871 active users. That’s fewer articles thanEsperanto!
The Documentation Contribution Agreement have to be written by thePSF, then listed athttps://www.python.org/psf/contrib/ and have itsown page likehttps://www.python.org/psf/contrib/doc-contrib-form/.
We (authors of this PEP) already own French and Japanese Git repositories,so moving them to the Python documentation organization will not be aproblem. We’ll however be following theNew Translation Procedure.
To help ensuring contributors from GitHub have signed theDocumentation Contribution Agreement, We can setup the “The KnightsWho Say Ni” GitHub bot customized for this agreement on the migratedrepositories[28].
Docsbuild-script must be patched to:
github.com:python/python-docs-{language_tag}.git (SeeRepository for Po Files)Patched docsbuild-scripts must only open.po files fromtranslation repositories.
Add a page or a section with an empty list of coordinators to thedevguide, each new coordinator will be added to this list.
Highly similar to the version switcher, a language switcher must beimplemented. This language switcher must be configurable to hide orshow a given language.
The language switcher will only have to update or add the languagesegment to the path like the current version switcher does. Unlikethe version switcher, no preflight are required as destination pagealways exists (translations does not add or remove pages).Untranslated (but existing) pages still exists, they should however berendered as so, seeEnhance Rendering of Untranslated and FuzzyTranslations.
Thepatch_url function of the version switcher inversion_switch.js have to be updated to understand and allow thepresence of the language segment in the path.
It’s an opened sphinx issue[9], but we’ll need it so we’ll have towork on it. Translated, fuzzy, and untranslated paragraphs should bedifferentiated. (Fuzzy paragraphs have to warn the reader what he’sreading may be out of date.)
The first step is to designate a coordinator, seeLanguage Team,The coordinator must sign the CLA.
The coordinator should be added to the list of translation coordinatorson the devguide.
Create a repository named “python-docs-{LANGUAGE_TAG}” (IETF languagetag, without redundant region subtag, with a dash, and lowercased.) onthe Python GitHub organization (SeeRepository For Po Files.), andgrant the language coordinator push rights to this repository.
The README file should clearly show the following DocumentationContribution Agreement:
NOTE REGARDING THE LICENSE FOR TRANSLATIONS: Python's documentation ismaintained using a global network of volunteers. By posting thisproject on Transifex, GitHub, and other public places, and invitingyou to participate, we are proposing an agreement that you willprovide your improvements to Python's documentation or the translationof Python's documentation for the PSF's use under the CC0 license(available at`https://creativecommons.org/publicdomain/zero/1.0/legalcode`_). Inreturn, you may publicly claim credit for the portion of thetranslation you contributed and if your translation is accepted by thePSF, you may (but are not required to) submit a patch including anappropriate annotation in the Misc/ACKS or TRANSLATORS file. Althoughnothing in this Documentation Contribution Agreement obligates the PSFto incorporate your textual contribution, your participation in thePython community is welcomed and appreciated.You signify acceptance of this agreement by submitting your work tothe PSF for inclusion in the documentation.
As soon as the translation hits its first commits, update thedocsbuild-scripts configuration to build the translation (but notdisplaying it in the language switcher).
As soon as the translation hits:
the translation can be added to the language switcher.
[Python-ideas] Cross link documentation translations (January, 2016)
[Python-Dev] Translated Python documentation (February 2016)
[2] [Doc-SIG] Localization of Python docs (https://mail.python.org/pipermail/doc-sig/2013-September/003948.html)
This document has been placed in the public domain.
Source:https://github.com/python/peps/blob/main/peps/pep-0545.rst
Last modified:2025-11-13 20:48:23 GMT