Text of peps.python.org › pep-0545 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 545 – Python Documentation Translations | peps.python.org

PEP 545 – Python Documentation Translations PEP 545 – Python Documentation Translations Author : Julien Palard <julien at palard.fr>, Inada Naoki <songofacandy at gmail.com>, Victor Stinner <vstinner at python.org> Status : Active Type : Process Topic : Governance Created : 04-Mar-2017 Resolution : Python-Dev message Table of Contents Abstract Motivation Rationale Translation Issue tracker Branches Hosting Domain Name, Content negotiation and URL Language Tag Fetching And Building Translations Community Mailing List Chat Repository for PO Files Translation tools python-docs-translations Documentation Contribution Agreement Language Team Alternatives Simplified English Changes Get a Documentation Contribution Agreement Migrate GitHub Repositories Setup a GitHub bot for Documentation Contribution Agreement Patch docsbuild-scripts to Compile Translations List coordinators in the devguide Create sphinx-doc Language Switcher Update sphinx-doc Version Switcher Enhance Rendering of Untranslated and Fuzzy Translations New Translation Procedure Designate a Coordinator Create GitHub Repository Setup the Documentation Contribution Agreement Add support for translations in docsbuild-scripts Add Translation to the Language Switcher Previous Discussions References Copyright Abstract The intent of this PEP is to make existing translations of the Python Documentation more accessible and discoverable.

By doing so, we hope to attract and motivate new translators and new translations. Translated documentation will be hosted on python.org. Examples of two active translation teams: https://docs.python.org/fr/ : French https://docs.python.org/ja/ : Japanese https://docs.python.org/en/ will redirect to https://docs.python.org/ . Sources of translated documentation will be hosted in the Python organization on GitHub: https://github.com/python/ .

Contributors will have to accept a Documentation Contribution Agreement. Motivation On the French #python-fr IRC channel on freenode, it’s not rare to meet people who don’t speak English and so are unable to read the Python official documentation. Python wants to be widely available to all users in any language: this is also why Python 3 supports any non-ASCII identifiers: PEP 3131 There are at least 4 groups of people who are translating the Python documentation to their native language (French [16] [17] [18] , Japanese [19] [20] , Spanish [21] , Hungarian [26] [27] ) even though their translations are not visible on d.p.o.

Other, less visible and less organized groups, are also translating the documentation, we’ve heard of Russian [25] , Chinese and Korean. Others we haven’t found yet might also exist. This PEP defines rules describing how to move translations on docs.python.org so they can easily be found by developers, newcomers and potential translators. The Japanese team has (as of March 2017) translated ~80% of the documentation, the French team ~20%.

French translation went from 6% to 23% in 2016 [13] with 7 contributors [14] , proving a translation team 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 official doc. But their efforts are disperse and quickly become lost because they are not organized to work towards a single common result and their results are hold anywhere on the Web and hard to find.

An official one could help ease the pain. Rationale Translation Issue tracker Considering that issues opened about translations may be written in the translation language, which can be considered noise but at least is inconsistent, issues should not be placed in the CPython issue tracker . As all translation must have their own GitHub project (see Repository for Po Files ), they must use the associated GitHub issue tracker.

Considering the noise induced by translation issues redacted in any languages which may beyond every warnings land in the issue tracker, triage will have to be done. Considering that translations already exist and are not actually a source of noise in issue tracker, an unmanageable amount of work is not to be expected. Considering that Xiang Zhang and Victor Stinner are already triaging, and Julien Palard is willing to help on this task, noise on issue tracker is not to be expected.

Also, language team coordinators (see Language Team ) should help with triaging the issue tracker by properly indicating, in the language of the issue author if required, the right issue tracker. Branches Translation teams should focus on last stable versions, and use tools (scripts, translation memory, …) to automatically translate what is done in one branch to other branches. Note Translation memories are a kind of database of previously translated paragraphs, even removed ones.

See also Sphinx Internationalization . The newest currently stable branch will be translated and translations can be propagated to other branches. The scripts to build the documentation of older branches needs to be modified to support translation [12] , whereas these branches now only accept security-only fixes. The development branch (main) should have a lower translation priority than stable branches. But docsbuild-scripts should build it anyway so it is possible for a team to work on it to be ready for the next release.

Hosting Domain Name, Content negotiation and URL Different translations can be identified by changing one of the following: Country Code Top Level Domain (CCTLD), path segment, subdomain or content negotiation. Buying a CCTLD for each translations is expensive, time-consuming, and sometimes almost impossible when already registered, this solution should be avoided. Using subdomains like “es.docs.python.org” or “docs.es.python.org” is possible but confusing (“is it es.docs.python.org or docs.es.python.org ?”).

Hyphens in subdomains like pt-br.doc.python.org is uncommon and SEOMoz [23] correlated the presence of hyphens as a negative factor. Usage of underscores in subdomain is prohibited by the RFC 1123 , section 2.1. Finally, using subdomains means creating TLS certificates for each language. This not only requires more maintenance but will also cause issues in language switcher if, as for version switcher, we want a preflight to check if the translation exists in the given version: preflight will probably be blocked by same-origin-policy.

Wildcard TLS certificates are very expensive. Using content negotiation (HTTP headers Accept-Language in the request and Vary: Accept-Language ) leads to a bad user experience where they can’t easily change the language. According to Mozilla: “This header is a hint to be used when the server has no way of determining the language via another way, like a specific URL, that is controlled by an explicit user decision.” [24] .

As we want to be able to easily change the language, we should not use the content negotiation as a main language determination, so we need something else. Last solution is to use the URL path, which looks readable, allows for an easy switch from a language to another, and nicely accepts hyphens. Typically something like: “docs.python.org/de/” or, by using a hyphen: “docs.python.org/pt-BR/”. As for the version, sphinx-doc does not support compiling for multiple languages, so we’ll have full builds rooted under a path, exactly like we’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 contain multiple languages?”. As versions exist in any case and translations for 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 written in German”.

Having the version at the end is also a habit taken by readers of the documentation: they li

The rest of this page is on the live site.