mirror of https://github.com/python/peps
775 lines
53 KiB
HTML
775 lines
53 KiB
HTML
|
||
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="color-scheme" content="light dark">
|
||
<title>PEP 545 – Python Documentation Translations | peps.python.org</title>
|
||
<link rel="shortcut icon" href="../_static/py.png">
|
||
<link rel="canonical" href="https://peps.python.org/pep-0545/">
|
||
<link rel="stylesheet" href="../_static/style.css" type="text/css">
|
||
<link rel="stylesheet" href="../_static/mq.css" type="text/css">
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light">
|
||
<link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark">
|
||
<link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss">
|
||
<meta property="og:title" content='PEP 545 – Python Documentation Translations | peps.python.org'>
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:url" content="https://peps.python.org/pep-0545/">
|
||
<meta property="og:site_name" content="Python Enhancement Proposals (PEPs)">
|
||
<meta property="og:image" content="https://peps.python.org/_static/og-image.png">
|
||
<meta property="og:image:alt" content="Python PEPs">
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
<meta name="description" content="Python Enhancement Proposals (PEPs)">
|
||
<meta name="theme-color" content="#3776ab">
|
||
</head>
|
||
<body>
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
|
||
<symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Following system colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<circle cx="12" cy="12" r="9"></circle>
|
||
<path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Selected dark colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
|
||
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Selected light colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<circle cx="12" cy="12" r="5"></circle>
|
||
<line x1="12" y1="1" x2="12" y2="3"></line>
|
||
<line x1="12" y1="21" x2="12" y2="23"></line>
|
||
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
|
||
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
|
||
<line x1="1" y1="12" x2="3" y2="12"></line>
|
||
<line x1="21" y1="12" x2="23" y2="12"></line>
|
||
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
|
||
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
|
||
</svg>
|
||
</symbol>
|
||
</svg>
|
||
<script>
|
||
|
||
document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto"
|
||
</script>
|
||
<section id="pep-page-section">
|
||
<header>
|
||
<h1>Python Enhancement Proposals</h1>
|
||
<ul class="breadcrumbs">
|
||
<li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li>
|
||
<li><a href="../pep-0000/">PEP Index</a> » </li>
|
||
<li>PEP 545</li>
|
||
</ul>
|
||
<button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())">
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg>
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg>
|
||
<span class="visually-hidden">Toggle light / dark / auto colour theme</span>
|
||
</button>
|
||
</header>
|
||
<article>
|
||
<section id="pep-content">
|
||
<h1 class="page-title">PEP 545 – Python Documentation Translations</h1>
|
||
<dl class="rfc2822 field-list simple">
|
||
<dt class="field-odd">Author<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Julien Palard <julien at palard.fr>,
|
||
Inada Naoki <songofacandy at gmail.com>,
|
||
Victor Stinner <vstinner at python.org></dd>
|
||
<dt class="field-even">Status<span class="colon">:</span></dt>
|
||
<dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd>
|
||
<dt class="field-odd">Type<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><abbr title="Normative PEP describing or proposing a change to a Python community process, workflow or governance">Process</abbr></dd>
|
||
<dt class="field-even">Created<span class="colon">:</span></dt>
|
||
<dd class="field-even">04-Mar-2017</dd>
|
||
<dt class="field-odd">Resolution<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><a class="reference external" href="https://mail.python.org/pipermail/python-dev/2017-May/147957.html">Python-Dev message</a></dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<section id="contents">
|
||
<details><summary>Table of Contents</summary><ul class="simple">
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#motivation">Motivation</a></li>
|
||
<li><a class="reference internal" href="#rationale">Rationale</a><ul>
|
||
<li><a class="reference internal" href="#translation">Translation</a><ul>
|
||
<li><a class="reference internal" href="#issue-tracker">Issue tracker</a></li>
|
||
<li><a class="reference internal" href="#branches">Branches</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#hosting">Hosting</a><ul>
|
||
<li><a class="reference internal" href="#domain-name-content-negotiation-and-url">Domain Name, Content negotiation and URL</a></li>
|
||
<li><a class="reference internal" href="#language-tag">Language Tag</a></li>
|
||
<li><a class="reference internal" href="#fetching-and-building-translations">Fetching And Building Translations</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#community">Community</a><ul>
|
||
<li><a class="reference internal" href="#mailing-list">Mailing List</a></li>
|
||
<li><a class="reference internal" href="#chat">Chat</a></li>
|
||
<li><a class="reference internal" href="#repository-for-po-files">Repository for PO Files</a></li>
|
||
<li><a class="reference internal" href="#translation-tools">Translation tools</a></li>
|
||
<li><a class="reference internal" href="#documentation-contribution-agreement">Documentation Contribution Agreement</a></li>
|
||
<li><a class="reference internal" href="#language-team">Language Team</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#alternatives">Alternatives</a><ul>
|
||
<li><a class="reference internal" href="#simplified-english">Simplified English</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#changes">Changes</a><ul>
|
||
<li><a class="reference internal" href="#get-a-documentation-contribution-agreement">Get a Documentation Contribution Agreement</a></li>
|
||
<li><a class="reference internal" href="#migrate-github-repositories">Migrate GitHub Repositories</a></li>
|
||
<li><a class="reference internal" href="#setup-a-github-bot-for-documentation-contribution-agreement">Setup a GitHub bot for Documentation Contribution Agreement</a></li>
|
||
<li><a class="reference internal" href="#patch-docsbuild-scripts-to-compile-translations">Patch docsbuild-scripts to Compile Translations</a></li>
|
||
<li><a class="reference internal" href="#list-coordinators-in-the-devguide">List coordinators in the devguide</a></li>
|
||
<li><a class="reference internal" href="#create-sphinx-doc-language-switcher">Create sphinx-doc Language Switcher</a></li>
|
||
<li><a class="reference internal" href="#update-sphinx-doc-version-switcher">Update sphinx-doc Version Switcher</a></li>
|
||
<li><a class="reference internal" href="#enhance-rendering-of-untranslated-and-fuzzy-translations">Enhance Rendering of Untranslated and Fuzzy Translations</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#new-translation-procedure">New Translation Procedure</a><ul>
|
||
<li><a class="reference internal" href="#designate-a-coordinator">Designate a Coordinator</a></li>
|
||
<li><a class="reference internal" href="#create-github-repository">Create GitHub Repository</a></li>
|
||
<li><a class="reference internal" href="#setup-the-documentation-contribution-agreement">Setup the Documentation Contribution Agreement</a></li>
|
||
<li><a class="reference internal" href="#add-support-for-translations-in-docsbuild-scripts">Add support for translations in docsbuild-scripts</a></li>
|
||
<li><a class="reference internal" href="#add-translation-to-the-language-switcher">Add Translation to the Language Switcher</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#previous-discussions">Previous Discussions</a></li>
|
||
<li><a class="reference internal" href="#references">References</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
</details></section>
|
||
<section id="abstract">
|
||
<h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2>
|
||
<p>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.</p>
|
||
<p>Translated documentation will be hosted on python.org. Examples of
|
||
two active translation teams:</p>
|
||
<ul class="simple">
|
||
<li><a class="reference external" href="http://docs.python.org/fr/">http://docs.python.org/fr/</a>: French</li>
|
||
<li><a class="reference external" href="http://docs.python.org/ja/">http://docs.python.org/ja/</a>: Japanese</li>
|
||
</ul>
|
||
<p><a class="reference external" href="http://docs.python.org/en/">http://docs.python.org/en/</a> will redirect to <a class="reference external" href="http://docs.python.org/">http://docs.python.org/</a>.</p>
|
||
<p>Sources of translated documentation will be hosted in the Python
|
||
organization on GitHub: <a class="reference external" href="https://github.com/python/">https://github.com/python/</a>. Contributors will
|
||
have to accept a Documentation Contribution Agreement.</p>
|
||
</section>
|
||
<section id="motivation">
|
||
<h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2>
|
||
<p>On the French <code class="docutils literal notranslate"><span class="pre">#python-fr</span></code> 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:
|
||
<a class="pep reference internal" href="../pep-3131/#rationale" title="PEP 3131 – Supporting Non-ASCII Identifiers § Rationale">PEP 3131</a></p>
|
||
<p>There are at least 4 groups of people who are translating the Python
|
||
documentation to their native language (French <a class="footnote-reference brackets" href="#id40" id="id1">[16]</a> <a class="footnote-reference brackets" href="#id41" id="id2">[17]</a> <a class="footnote-reference brackets" href="#id42" id="id3">[18]</a>,
|
||
Japanese <a class="footnote-reference brackets" href="#id43" id="id4">[19]</a> <a class="footnote-reference brackets" href="#id44" id="id5">[20]</a>, Spanish <a class="footnote-reference brackets" href="#id45" id="id6">[21]</a>, Hungarian <a class="footnote-reference brackets" href="#id50" id="id7">[26]</a> <a class="footnote-reference brackets" href="#id51" id="id8">[27]</a>) 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 <a class="footnote-reference brackets" href="#id49" id="id9">[25]</a>, 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.</p>
|
||
<p>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 <a class="footnote-reference brackets" href="#id37" id="id10">[13]</a> with 7 contributors <a class="footnote-reference brackets" href="#id38" id="id11">[14]</a>, proving a translation
|
||
team can be faster than the rate the documentation mutates.</p>
|
||
<p>Quoting Xiang Zhang about Chinese translations:</p>
|
||
<blockquote>
|
||
<div>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.</div></blockquote>
|
||
</section>
|
||
<section id="rationale">
|
||
<h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2>
|
||
<section id="translation">
|
||
<h3><a class="toc-backref" href="#translation" role="doc-backlink">Translation</a></h3>
|
||
<section id="issue-tracker">
|
||
<h4><a class="toc-backref" href="#issue-tracker" role="doc-backlink">Issue tracker</a></h4>
|
||
<p>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 be placed outside <a class="reference external" href="https://bugs.python.org/">bugs.python.org</a> (b.p.o).</p>
|
||
<p>As all translation must have their own GitHub project (see <a class="reference internal" href="#repository-for-po-files">Repository
|
||
for Po Files</a>), they must use the associated GitHub issue tracker.</p>
|
||
<p>Considering the noise induced by translation issues redacted in any
|
||
languages which may beyond every warnings land in b.p.o, triage will
|
||
have to be done. Considering that translations already exist and are
|
||
not actually a source of noise in b.p.o, 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 b.p.o is not to be expected.</p>
|
||
<p>Also, language team coordinators (see <a class="reference internal" href="#language-team">Language Team</a>) should help
|
||
with triaging b.p.o by properly indicating, in the language of the
|
||
issue author if required, the right issue tracker.</p>
|
||
</section>
|
||
<section id="branches">
|
||
<h4><a class="toc-backref" href="#branches" role="doc-backlink">Branches</a></h4>
|
||
<p>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.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Translation memories are a kind of database of previously translated
|
||
paragraphs, even removed ones. See also <a class="reference external" href="http://www.sphinx-doc.org/en/stable/intl.html">Sphinx Internationalization</a>.</p>
|
||
</div>
|
||
<p>The three currently stable branches that will be translated are <a class="footnote-reference brackets" href="#id36" id="id12">[12]</a>:
|
||
2.7, 3.5, and 3.6. The scripts to build the documentation of older
|
||
branches needs to be modified to support translation <a class="footnote-reference brackets" href="#id36" id="id13">[12]</a>, whereas
|
||
these branches now only accept security-only fixes.</p>
|
||
<p>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.</p>
|
||
</section>
|
||
</section>
|
||
<section id="hosting">
|
||
<h3><a class="toc-backref" href="#hosting" role="doc-backlink">Hosting</a></h3>
|
||
<section id="domain-name-content-negotiation-and-url">
|
||
<h4><a class="toc-backref" href="#domain-name-content-negotiation-and-url" role="doc-backlink">Domain Name, Content negotiation and URL</a></h4>
|
||
<p>Different translations can be identified by changing one of the
|
||
following: Country Code Top Level Domain (CCTLD),
|
||
path segment, subdomain or content negotiation.</p>
|
||
<p>Buying a CCTLD for each translations is expensive, time-consuming, and
|
||
sometimes almost impossible when already registered, this solution
|
||
should be avoided.</p>
|
||
<p>Using subdomains like “es.docs.python.org” or “docs.es.python.org” is
|
||
possible but confusing (“is it <code class="docutils literal notranslate"><span class="pre">es.docs.python.org</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">docs.es.python.org</span></code>?”). Hyphens in subdomains like
|
||
<code class="docutils literal notranslate"><span class="pre">pt-br.doc.python.org</span></code> is uncommon and SEOMoz <a class="footnote-reference brackets" href="#id47" id="id14">[23]</a> correlated the
|
||
presence of hyphens as a negative factor. Usage of underscores in
|
||
subdomain is prohibited by the <span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc1123.html"><strong>RFC 1123</strong></a>, 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.</p>
|
||
<p>Using content negotiation (HTTP headers <code class="docutils literal notranslate"><span class="pre">Accept-Language</span></code> in the
|
||
request and <code class="docutils literal notranslate"><span class="pre">Vary:</span> <span class="pre">Accept-Language</span></code>) 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.” <a class="footnote-reference brackets" href="#id48" id="id15">[24]</a>. 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.</p>
|
||
<p>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/”.</p>
|
||
<p>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.</p>
|
||
<p>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 like to easily change the version
|
||
by changing the end of the path.</p>
|
||
<p>So we should use the following pattern:
|
||
“docs.python.org/LANGUAGE_TAG/VERSION/”.</p>
|
||
<p>The current documentation is not moved to “/en/”, instead
|
||
“docs.python.org/en/” will redirect to “docs.python.org”.</p>
|
||
</section>
|
||
<section id="language-tag">
|
||
<h4><a class="toc-backref" href="#language-tag" role="doc-backlink">Language Tag</a></h4>
|
||
<p>A common notation for language tags is the <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5646.html"><strong>IETF Language Tag</strong></a>
|
||
<a class="footnote-reference brackets" href="#id29" id="id16">[4]</a> based on ISO 639, although gettext uses ISO 639 tags with
|
||
underscores (ex: <code class="docutils literal notranslate"><span class="pre">pt_BR</span></code>) instead of dashes to join tags <a class="footnote-reference brackets" href="#id30" id="id17">[5]</a>
|
||
(ex: <code class="docutils literal notranslate"><span class="pre">pt-BR</span></code>). Examples of IETF Language Tags: <code class="docutils literal notranslate"><span class="pre">fr</span></code> (French),
|
||
<code class="docutils literal notranslate"><span class="pre">ja</span></code> (Japanese), <code class="docutils literal notranslate"><span class="pre">pt-BR</span></code> (Orthographic formulation of 1943 -
|
||
Official in Brazil).</p>
|
||
<p>It is more common to see dashes instead of underscores in URLs <a class="footnote-reference brackets" href="#id31" id="id18">[6]</a>,
|
||
so we should use IETF language tags, even if sphinx uses gettext
|
||
internally: URLs are not meant to leak the underlying implementation.</p>
|
||
<p>It’s uncommon to see capitalized letters in URLs, and docs.python.org
|
||
doesn’t use any, so it may hurt readability by attracting the eye on it,
|
||
like in: “<a class="reference external" href="https://docs.python.org/pt-BR/3.6/library/stdtypes.html">https://docs.python.org/pt-BR/3.6/library/stdtypes.html</a>”.
|
||
<span class="target" id="index-2"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5646.html#section-2.1.1"><strong>RFC 5646#section-2.1.1</strong></a>
|
||
(Tags for Identifying Languages (IETF)) section-2.1
|
||
states that tags are not case sensitive. As the RFC allows lower case,
|
||
and it enhances readability, we should use lowercased tags like
|
||
<code class="docutils literal notranslate"><span class="pre">pt-br</span></code>.</p>
|
||
<p>We may drop the region subtag when it does not add distinguishing
|
||
information, for example: “de-DE” or “fr-FR”. (Although it might
|
||
make sense, respectively meaning “German as spoken in Germany”
|
||
and “French as spoken in France”). But when the region subtag
|
||
actually adds information, for example “pt-BR” or “Portuguese as
|
||
spoken in Brazil”, it should be kept.</p>
|
||
<p>So we should use IETF language tags, lowercased, like <code class="docutils literal notranslate"><span class="pre">/fr/</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">/pt-br/</span></code>, <code class="docutils literal notranslate"><span class="pre">/de/</span></code> and so on.</p>
|
||
</section>
|
||
<section id="fetching-and-building-translations">
|
||
<h4><a class="toc-backref" href="#fetching-and-building-translations" role="doc-backlink">Fetching And Building Translations</a></h4>
|
||
<p>Currently docsbuild-scripts are building the documentation <a class="footnote-reference brackets" href="#id32" id="id19">[8]</a>.
|
||
These scripts should be modified to fetch and build translations.</p>
|
||
<p>Building new translations is like building new versions so, while we’re
|
||
adding complexity it is not that much.</p>
|
||
<p>Two steps should be configurable distinctively: Building a new language,
|
||
and adding it to the language switcher. This allows a transition step
|
||
between “we accepted the language” and “it is translated enough to be
|
||
made public”. During this step, translators can review their
|
||
modifications on d.p.o without having to build the documentation
|
||
locally.</p>
|
||
<p>From the translation repositories, only the <code class="docutils literal notranslate"><span class="pre">.po</span></code> files should be
|
||
opened by the docsbuild-script to keep the attack surface and probable
|
||
bug sources at a minimum. This means no translation can patch sphinx
|
||
to advertise their translation tool. (This specific feature should be
|
||
handled by sphinx anyway <a class="footnote-reference brackets" href="#id33" id="id20">[9]</a>).</p>
|
||
</section>
|
||
</section>
|
||
<section id="community">
|
||
<h3><a class="toc-backref" href="#community" role="doc-backlink">Community</a></h3>
|
||
<section id="mailing-list">
|
||
<h4><a class="toc-backref" href="#mailing-list" role="doc-backlink">Mailing List</a></h4>
|
||
<p>The <a class="reference external" href="https://mail.python.org/mailman/listinfo/doc-sig">doc-sig</a> mailing list will be used to discuss cross-language
|
||
changes on translated documentation.</p>
|
||
<p>There is also the i18n-sig list but it’s more oriented towards i18n APIs
|
||
<a class="footnote-reference brackets" href="#id28" id="id21">[1]</a> than translating the Python documentation.</p>
|
||
</section>
|
||
<section id="chat">
|
||
<h4><a class="toc-backref" href="#chat" role="doc-backlink">Chat</a></h4>
|
||
<p>Due to the Python community being highly active on IRC, we should
|
||
create a new IRC channel on freenode, typically #python-doc for
|
||
consistency with the mailing list name.</p>
|
||
<p>Each language coordinator can organize their own team, even by choosing
|
||
another chat system if the local usage asks for it. As local teams
|
||
will write in their native languages, we don’t want each team in a
|
||
single channel. It’s also natural for the local teams to reuse
|
||
their local channels like “#python-fr” for French translators.</p>
|
||
</section>
|
||
<section id="repository-for-po-files">
|
||
<h4><a class="toc-backref" href="#repository-for-po-files" role="doc-backlink">Repository for PO Files</a></h4>
|
||
<p>Considering that each translation team may want to use different
|
||
translation tools, and that those tools should easily be synchronized
|
||
with git, all translations should expose their <code class="docutils literal notranslate"><span class="pre">.po</span></code> files via a git
|
||
repository.</p>
|
||
<p>Considering that each translation will be exposed via git
|
||
repositories, and that Python has migrated to GitHub, translations
|
||
will be hosted on GitHub.</p>
|
||
<p>For consistency and discoverability, all translations should be in the
|
||
same GitHub organization and named according to a common pattern.</p>
|
||
<p>Given that we want translations to be official, and that Python
|
||
already has a GitHub organization, translations should be hosted as
|
||
projects of the <a class="reference external" href="https://github.com/python/">Python GitHub organization</a>.</p>
|
||
<p>For consistency, translation repositories should be called
|
||
<code class="docutils literal notranslate"><span class="pre">python-docs-LANGUAGE_TAG</span></code> <a class="footnote-reference brackets" href="#id46" id="id22">[22]</a>, using the language tag used in
|
||
paths: without region subtag if redundant, and lowercased.</p>
|
||
<p>The docsbuild-scripts may enforce this rule by refusing to fetch
|
||
outside of the Python organization or a wrongly named repository.</p>
|
||
<p>The CLA bot may be used on the translation repositories, but with a
|
||
limited effect as local coordinators may synchronize themselves with
|
||
translations from an external tool, like transifex, and lose track
|
||
of who translated what in the process.</p>
|
||
<p>Versions can be hosted on different repositories, different directories
|
||
or different branches. Storing them on different repositories will
|
||
probably pollute the Python GitHub organization. As it
|
||
is typical and natural to use branches to separate versions, branches
|
||
should be used to do so.</p>
|
||
</section>
|
||
<section id="translation-tools">
|
||
<h4><a class="toc-backref" href="#translation-tools" role="doc-backlink">Translation tools</a></h4>
|
||
<p>Most of the translation work is actually done on Transifex <a class="footnote-reference brackets" href="#id39" id="id23">[15]</a>.</p>
|
||
<p>Other tools may be used later like <a class="reference external" href="https://pontoon.mozilla.org/">https://pontoon.mozilla.org/</a>
|
||
and <a class="reference external" href="http://zanata.org/">http://zanata.org/</a>.</p>
|
||
</section>
|
||
<section id="documentation-contribution-agreement">
|
||
<h4><a class="toc-backref" href="#documentation-contribution-agreement" role="doc-backlink">Documentation Contribution Agreement</a></h4>
|
||
<p>Documentation does require a license from the translator, as it
|
||
involves creativity in the expression of the ideas.</p>
|
||
<p>There’s multiple solutions, quoting Van Lindberg from the PSF asked
|
||
about the subject:</p>
|
||
<blockquote>
|
||
<div><ol class="arabic simple">
|
||
<li>Docs should either have the copyright assigned or be under CCO. A
|
||
permissive software license (like Apache or MIT) would also get the
|
||
job done, although it is not quite fit for task.</li>
|
||
<li>The translators should either sign an agreement or submit a
|
||
declaration of the license with the translation.</li>
|
||
<li>We should have in the project page an invitation for people to
|
||
contribute under a defined license, with acceptance defined by their
|
||
act of contribution. Such as:</li>
|
||
</ol>
|
||
<p>“By posting this project on Transifex and inviting you to
|
||
participate, we are proposing an agreement that you will provide
|
||
your translation for the PSF’s use under the CC0 license. In return,
|
||
you may noted that you were the translator for the portion you
|
||
translate. You signify acceptance of this agreement by submitting
|
||
your work to the PSF for inclusion in the documentation.”</p>
|
||
</div></blockquote>
|
||
<p>It looks like having a “Documentation Contribution Agreement”
|
||
is the most simple thing we can do as we can use multiple ways (GitHub
|
||
bots, invitation page, …) in different context to ensure contributors
|
||
are agreeing with it.</p>
|
||
</section>
|
||
<section id="language-team">
|
||
<h4><a class="toc-backref" href="#language-team" role="doc-backlink">Language Team</a></h4>
|
||
<p>Each language team should have one coordinator responsible for:</p>
|
||
<ul class="simple">
|
||
<li>Managing the team.</li>
|
||
<li>Choosing and managing the tools the team will use (chat, mailing list, …).</li>
|
||
<li>Ensure contributors understand and agree with the documentation
|
||
contribution agreement.</li>
|
||
<li>Ensure quality (grammar, vocabulary, consistency, filtering spam, ads, …).</li>
|
||
<li>Redirect issues posted on b.p.o to the correct GitHub issue tracker
|
||
for the language.</li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
<section id="alternatives">
|
||
<h3><a class="toc-backref" href="#alternatives" role="doc-backlink">Alternatives</a></h3>
|
||
<section id="simplified-english">
|
||
<h4><a class="toc-backref" href="#simplified-english" role="doc-backlink">Simplified English</a></h4>
|
||
<p>It would be possible to introduce a “simplified English” version like
|
||
Wikipedia did <a class="footnote-reference brackets" href="#id34" id="id24">[10]</a>, as discussed on python-dev <a class="footnote-reference brackets" href="#id35" id="id25">[11]</a>, targeting
|
||
English learners and children.</p>
|
||
<p>Pros: It yields a single translation, theoretically readable by
|
||
everyone and reviewable by current maintainers.</p>
|
||
<p>Cons: Subtle details may be lost, and translators from English to English
|
||
may be hard to find as stated by Wikipedia:</p>
|
||
<p>> The main English Wikipedia has 5 million articles, written by nearly
|
||
140K active users; the Swedish Wikipedia is almost as big, 3M articles
|
||
from only 3K active users; but the Simple English Wikipedia has just
|
||
123K articles and 871 active users. That’s fewer articles than
|
||
Esperanto!</p>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
<section id="changes">
|
||
<h2><a class="toc-backref" href="#changes" role="doc-backlink">Changes</a></h2>
|
||
<section id="get-a-documentation-contribution-agreement">
|
||
<h3><a class="toc-backref" href="#get-a-documentation-contribution-agreement" role="doc-backlink">Get a Documentation Contribution Agreement</a></h3>
|
||
<p>The Documentation Contribution Agreement have to be written by the
|
||
PSF, then listed at <a class="reference external" href="https://www.python.org/psf/contrib/">https://www.python.org/psf/contrib/</a> and have its
|
||
own page like <a class="reference external" href="https://www.python.org/psf/contrib/doc-contrib-form/">https://www.python.org/psf/contrib/doc-contrib-form/</a>.</p>
|
||
</section>
|
||
<section id="migrate-github-repositories">
|
||
<h3><a class="toc-backref" href="#migrate-github-repositories" role="doc-backlink">Migrate GitHub Repositories</a></h3>
|
||
<p>We (authors of this PEP) already own French and Japanese Git repositories,
|
||
so moving them to the Python documentation organization will not be a
|
||
problem. We’ll however be following the <a class="reference internal" href="#new-translation-procedure">New Translation Procedure</a>.</p>
|
||
</section>
|
||
<section id="setup-a-github-bot-for-documentation-contribution-agreement">
|
||
<h3><a class="toc-backref" href="#setup-a-github-bot-for-documentation-contribution-agreement" role="doc-backlink">Setup a GitHub bot for Documentation Contribution Agreement</a></h3>
|
||
<p>To help ensuring contributors from GitHub have signed the
|
||
Documentation Contribution Agreement, We can setup the “The Knights
|
||
Who Say Ni” GitHub bot customized for this agreement on the migrated
|
||
repositories <a class="footnote-reference brackets" href="#id52" id="id26">[28]</a>.</p>
|
||
</section>
|
||
<section id="patch-docsbuild-scripts-to-compile-translations">
|
||
<h3><a class="toc-backref" href="#patch-docsbuild-scripts-to-compile-translations" role="doc-backlink">Patch docsbuild-scripts to Compile Translations</a></h3>
|
||
<p>Docsbuild-script must be patched to:</p>
|
||
<ul class="simple">
|
||
<li>List the language tags to build along with the branches to build.</li>
|
||
<li>List the language tags to display in the language switcher.</li>
|
||
<li>Find translation repositories by formatting
|
||
<code class="docutils literal notranslate"><span class="pre">github.com:python/python-docs-{language_tag}.git</span></code> (See
|
||
<a class="reference internal" href="#repository-for-po-files">Repository for Po Files</a>)</li>
|
||
<li>Build translations for each branch and each language.</li>
|
||
</ul>
|
||
<p>Patched docsbuild-scripts must only open <code class="docutils literal notranslate"><span class="pre">.po</span></code> files from
|
||
translation repositories.</p>
|
||
</section>
|
||
<section id="list-coordinators-in-the-devguide">
|
||
<h3><a class="toc-backref" href="#list-coordinators-in-the-devguide" role="doc-backlink">List coordinators in the devguide</a></h3>
|
||
<p>Add a page or a section with an empty list of coordinators to the
|
||
devguide, each new coordinator will be added to this list.</p>
|
||
</section>
|
||
<section id="create-sphinx-doc-language-switcher">
|
||
<h3><a class="toc-backref" href="#create-sphinx-doc-language-switcher" role="doc-backlink">Create sphinx-doc Language Switcher</a></h3>
|
||
<p>Highly similar to the version switcher, a language switcher must be
|
||
implemented. This language switcher must be configurable to hide or
|
||
show a given language.</p>
|
||
<p>The language switcher will only have to update or add the language
|
||
segment to the path like the current version switcher does. Unlike
|
||
the version switcher, no preflight are required as destination page
|
||
always exists (translations does not add or remove pages).
|
||
Untranslated (but existing) pages still exists, they should however be
|
||
rendered as so, see <a class="reference internal" href="#enhance-rendering-of-untranslated-and-fuzzy-translations">Enhance Rendering of Untranslated and Fuzzy
|
||
Translations</a>.</p>
|
||
</section>
|
||
<section id="update-sphinx-doc-version-switcher">
|
||
<h3><a class="toc-backref" href="#update-sphinx-doc-version-switcher" role="doc-backlink">Update sphinx-doc Version Switcher</a></h3>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">patch_url</span></code> function of the version switcher in
|
||
<code class="docutils literal notranslate"><span class="pre">version_switch.js</span></code> have to be updated to understand and allow the
|
||
presence of the language segment in the path.</p>
|
||
</section>
|
||
<section id="enhance-rendering-of-untranslated-and-fuzzy-translations">
|
||
<h3><a class="toc-backref" href="#enhance-rendering-of-untranslated-and-fuzzy-translations" role="doc-backlink">Enhance Rendering of Untranslated and Fuzzy Translations</a></h3>
|
||
<p>It’s an opened sphinx issue <a class="footnote-reference brackets" href="#id33" id="id27">[9]</a>, but we’ll need it so we’ll have to
|
||
work on it. Translated, fuzzy, and untranslated paragraphs should be
|
||
differentiated. (Fuzzy paragraphs have to warn the reader what he’s
|
||
reading may be out of date.)</p>
|
||
</section>
|
||
</section>
|
||
<section id="new-translation-procedure">
|
||
<h2><a class="toc-backref" href="#new-translation-procedure" role="doc-backlink">New Translation Procedure</a></h2>
|
||
<section id="designate-a-coordinator">
|
||
<h3><a class="toc-backref" href="#designate-a-coordinator" role="doc-backlink">Designate a Coordinator</a></h3>
|
||
<p>The first step is to designate a coordinator, see <a class="reference internal" href="#language-team">Language Team</a>,
|
||
The coordinator must sign the CLA.</p>
|
||
<p>The coordinator should be added to the list of translation coordinators
|
||
on the devguide.</p>
|
||
</section>
|
||
<section id="create-github-repository">
|
||
<h3><a class="toc-backref" href="#create-github-repository" role="doc-backlink">Create GitHub Repository</a></h3>
|
||
<p>Create a repository named “python-docs-{LANGUAGE_TAG}” (IETF language
|
||
tag, without redundant region subtag, with a dash, and lowercased.) on
|
||
the Python GitHub organization (See <a class="reference internal" href="#repository-for-po-files">Repository For Po Files</a>.), and
|
||
grant the language coordinator push rights to this repository.</p>
|
||
</section>
|
||
<section id="setup-the-documentation-contribution-agreement">
|
||
<h3><a class="toc-backref" href="#setup-the-documentation-contribution-agreement" role="doc-backlink">Setup the Documentation Contribution Agreement</a></h3>
|
||
<p>The README file should clearly show the following Documentation
|
||
Contribution Agreement:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>NOTE REGARDING THE LICENSE FOR TRANSLATIONS: Python's documentation is
|
||
maintained using a global network of volunteers. By posting this
|
||
project on Transifex, GitHub, and other public places, and inviting
|
||
you to participate, we are proposing an agreement that you will
|
||
provide your improvements to Python's documentation or the translation
|
||
of Python's documentation for the PSF's use under the CC0 license
|
||
(available at
|
||
`https://creativecommons.org/publicdomain/zero/1.0/legalcode`_). In
|
||
return, you may publicly claim credit for the portion of the
|
||
translation you contributed and if your translation is accepted by the
|
||
PSF, you may (but are not required to) submit a patch including an
|
||
appropriate annotation in the Misc/ACKS or TRANSLATORS file. Although
|
||
nothing in this Documentation Contribution Agreement obligates the PSF
|
||
to incorporate your textual contribution, your participation in the
|
||
Python community is welcomed and appreciated.
|
||
|
||
You signify acceptance of this agreement by submitting your work to
|
||
the PSF for inclusion in the documentation.
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="add-support-for-translations-in-docsbuild-scripts">
|
||
<h3><a class="toc-backref" href="#add-support-for-translations-in-docsbuild-scripts" role="doc-backlink">Add support for translations in docsbuild-scripts</a></h3>
|
||
<p>As soon as the translation hits its first commits, update the
|
||
docsbuild-scripts configuration to build the translation (but not
|
||
displaying it in the language switcher).</p>
|
||
</section>
|
||
<section id="add-translation-to-the-language-switcher">
|
||
<h3><a class="toc-backref" href="#add-translation-to-the-language-switcher" role="doc-backlink">Add Translation to the Language Switcher</a></h3>
|
||
<p>As soon as the translation hits:</p>
|
||
<ul class="simple">
|
||
<li>100% of bugs.html with proper links to the language repository
|
||
issue tracker.</li>
|
||
<li>100% of tutorial.</li>
|
||
<li>100% of library/functions (builtins).</li>
|
||
</ul>
|
||
<p>the translation can be added to the language switcher.</p>
|
||
</section>
|
||
</section>
|
||
<section id="previous-discussions">
|
||
<h2><a class="toc-backref" href="#previous-discussions" role="doc-backlink">Previous Discussions</a></h2>
|
||
<p><a class="reference external" href="https://mail.python.org/pipermail/python-ideas/2016-January/038010.html">[Python-ideas] Cross link documentation translations (January, 2016)</a></p>
|
||
<p><a class="reference external" href="https://mail.python.org/pipermail/python-dev/2017-February/147416.html">[Python-Dev] Translated Python documentation (February 2016)</a></p>
|
||
<p><a class="reference external" href="https://mail.python.org/pipermail/python-ideas/2016-March/038879.html">[Python-ideas] https://docs.python.org/fr/ ? (March 2016)</a></p>
|
||
</section>
|
||
<section id="references">
|
||
<h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2>
|
||
<aside class="footnote-list brackets">
|
||
<aside class="footnote brackets" id="id28" role="doc-footnote">
|
||
<dt class="label" id="id28">[<a href="#id21">1</a>]</dt>
|
||
<dd>[I18n-sig] Hello Python members, Do you have any idea about
|
||
Python documents?
|
||
(<a class="reference external" href="https://mail.python.org/pipermail/i18n-sig/2013-September/002130.html">https://mail.python.org/pipermail/i18n-sig/2013-September/002130.html</a>)</aside>
|
||
</aside>
|
||
<p>[2] [Doc-SIG] Localization of Python docs
|
||
(<a class="reference external" href="https://mail.python.org/pipermail/doc-sig/2013-September/003948.html">https://mail.python.org/pipermail/doc-sig/2013-September/003948.html</a>)</p>
|
||
<aside class="footnote-list brackets">
|
||
<aside class="footnote brackets" id="id29" role="doc-footnote">
|
||
<dt class="label" id="id29">[<a href="#id16">4</a>]</dt>
|
||
<dd>IETF language tag
|
||
(<a class="reference external" href="https://en.wikipedia.org/wiki/IETF_language_tag">https://en.wikipedia.org/wiki/IETF_language_tag</a>)</aside>
|
||
<aside class="footnote brackets" id="id30" role="doc-footnote">
|
||
<dt class="label" id="id30">[<a href="#id17">5</a>]</dt>
|
||
<dd>GNU Gettext manual, section 2.3.1: Locale Names
|
||
(<a class="reference external" href="https://www.gnu.org/software/gettext/manual/html_node/Locale-Names.html">https://www.gnu.org/software/gettext/manual/html_node/Locale-Names.html</a>)</aside>
|
||
<aside class="footnote brackets" id="id31" role="doc-footnote">
|
||
<dt class="label" id="id31">[<a href="#id18">6</a>]</dt>
|
||
<dd>Semantic URL: Slug
|
||
(<a class="reference external" href="https://en.wikipedia.org/wiki/Clean_URL#Slug">https://en.wikipedia.org/wiki/Clean_URL#Slug</a>)</aside>
|
||
<aside class="footnote brackets" id="id32" role="doc-footnote">
|
||
<dt class="label" id="id32">[<a href="#id19">8</a>]</dt>
|
||
<dd>Docsbuild-scripts GitHub repository
|
||
(<a class="reference external" href="https://github.com/python/docsbuild-scripts/">https://github.com/python/docsbuild-scripts/</a>)</aside>
|
||
<aside class="footnote brackets" id="id33" role="doc-footnote">
|
||
<dt class="label" id="id33">[9]<em> (<a href='#id20'>1</a>, <a href='#id27'>2</a>) </em></dt>
|
||
<dd>i18n: Highlight untranslated paragraphs
|
||
(<a class="reference external" href="https://github.com/sphinx-doc/sphinx/issues/1246">https://github.com/sphinx-doc/sphinx/issues/1246</a>)</aside>
|
||
<aside class="footnote brackets" id="id34" role="doc-footnote">
|
||
<dt class="label" id="id34">[<a href="#id24">10</a>]</dt>
|
||
<dd>Wikipedia: Simple English
|
||
(<a class="reference external" href="https://simple.wikipedia.org/wiki/Main_Page">https://simple.wikipedia.org/wiki/Main_Page</a>)</aside>
|
||
<aside class="footnote brackets" id="id35" role="doc-footnote">
|
||
<dt class="label" id="id35">[<a href="#id25">11</a>]</dt>
|
||
<dd>Python-dev discussion about simplified English
|
||
(<a class="reference external" href="https://mail.python.org/pipermail/python-dev/2017-February/147446.html">https://mail.python.org/pipermail/python-dev/2017-February/147446.html</a>)</aside>
|
||
<aside class="footnote brackets" id="id36" role="doc-footnote">
|
||
<dt class="label" id="id36">[12]<em> (<a href='#id12'>1</a>, <a href='#id13'>2</a>) </em></dt>
|
||
<dd>Passing options to sphinx from Doc/Makefile
|
||
(<a class="reference external" href="https://github.com/python/cpython/commit/57acb82d275ace9d9d854b156611e641f68e9e7c">https://github.com/python/cpython/commit/57acb82d275ace9d9d854b156611e641f68e9e7c</a>)</aside>
|
||
<aside class="footnote brackets" id="id37" role="doc-footnote">
|
||
<dt class="label" id="id37">[<a href="#id10">13</a>]</dt>
|
||
<dd>French translation progression
|
||
(<a class="reference external" href="https://mdk.fr/pycon2016/#/11">https://mdk.fr/pycon2016/#/11</a>)</aside>
|
||
<aside class="footnote brackets" id="id38" role="doc-footnote">
|
||
<dt class="label" id="id38">[<a href="#id11">14</a>]</dt>
|
||
<dd>French translation contributors
|
||
(<a class="reference external" href="https://github.com/AFPy/python_doc_fr/graphs/contributors?from=2016-01-01&to=2016-12-31&type=c">https://github.com/AFPy/python_doc_fr/graphs/contributors?from=2016-01-01&to=2016-12-31&type=c</a>)</aside>
|
||
<aside class="footnote brackets" id="id39" role="doc-footnote">
|
||
<dt class="label" id="id39">[<a href="#id23">15</a>]</dt>
|
||
<dd>Python-doc on Transifex
|
||
(<a class="reference external" href="https://www.transifex.com/python-doc/public/">https://www.transifex.com/python-doc/public/</a>)</aside>
|
||
<aside class="footnote brackets" id="id40" role="doc-footnote">
|
||
<dt class="label" id="id40">[<a href="#id1">16</a>]</dt>
|
||
<dd>French translation
|
||
(<a class="reference external" href="https://www.afpy.org/doc/python/">https://www.afpy.org/doc/python/</a>)</aside>
|
||
<aside class="footnote brackets" id="id41" role="doc-footnote">
|
||
<dt class="label" id="id41">[<a href="#id2">17</a>]</dt>
|
||
<dd>French translation on Gitea
|
||
(<a class="reference external" href="https://git.afpy.org/AFPy/python-docs-fr">https://git.afpy.org/AFPy/python-docs-fr</a>)</aside>
|
||
<aside class="footnote brackets" id="id42" role="doc-footnote">
|
||
<dt class="label" id="id42">[<a href="#id3">18</a>]</dt>
|
||
<dd>French mailing list
|
||
(<a class="reference external" href="http://lists.afpy.org/mailman/listinfo/traductions">http://lists.afpy.org/mailman/listinfo/traductions</a>)</aside>
|
||
<aside class="footnote brackets" id="id43" role="doc-footnote">
|
||
<dt class="label" id="id43">[<a href="#id4">19</a>]</dt>
|
||
<dd>Japanese translation
|
||
(<a class="reference external" href="http://docs.python.jp/3/">http://docs.python.jp/3/</a>)</aside>
|
||
<aside class="footnote brackets" id="id44" role="doc-footnote">
|
||
<dt class="label" id="id44">[<a href="#id5">20</a>]</dt>
|
||
<dd>Japanese translation on GitHub
|
||
(<a class="reference external" href="https://github.com/python-doc-ja/python-doc-ja">https://github.com/python-doc-ja/python-doc-ja</a>)</aside>
|
||
<aside class="footnote brackets" id="id45" role="doc-footnote">
|
||
<dt class="label" id="id45">[<a href="#id6">21</a>]</dt>
|
||
<dd>Spanish translation
|
||
(<a class="reference external" href="https://docs.python.org/es/3/tutorial/index.html">https://docs.python.org/es/3/tutorial/index.html</a>)</aside>
|
||
<aside class="footnote brackets" id="id46" role="doc-footnote">
|
||
<dt class="label" id="id46">[<a href="#id22">22</a>]</dt>
|
||
<dd>[Python-Dev] Translated Python documentation: doc vs docs
|
||
(<a class="reference external" href="https://mail.python.org/pipermail/python-dev/2017-February/147472.html">https://mail.python.org/pipermail/python-dev/2017-February/147472.html</a>)</aside>
|
||
<aside class="footnote brackets" id="id47" role="doc-footnote">
|
||
<dt class="label" id="id47">[<a href="#id14">23</a>]</dt>
|
||
<dd>Domains - SEO Best Practices | Moz
|
||
(<a class="reference external" href="https://moz.com/learn/seo/domain">https://moz.com/learn/seo/domain</a>)</aside>
|
||
<aside class="footnote brackets" id="id48" role="doc-footnote">
|
||
<dt class="label" id="id48">[<a href="#id15">24</a>]</dt>
|
||
<dd>Accept-Language
|
||
(<a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language">https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language</a>)</aside>
|
||
<aside class="footnote brackets" id="id49" role="doc-footnote">
|
||
<dt class="label" id="id49">[<a href="#id9">25</a>]</dt>
|
||
<dd>Документация Python 2.7!
|
||
(<a class="reference external" href="http://python-lab.ru/documentation/index.html">http://python-lab.ru/documentation/index.html</a>)</aside>
|
||
<aside class="footnote brackets" id="id50" role="doc-footnote">
|
||
<dt class="label" id="id50">[<a href="#id7">26</a>]</dt>
|
||
<dd>Python-oktató
|
||
(<a class="reference external" href="http://web.archive.org/web/20170526080729/http://harp.pythonanywhere.com/python_doc/tutorial/index.html">http://web.archive.org/web/20170526080729/http://harp.pythonanywhere.com/python_doc/tutorial/index.html</a>)</aside>
|
||
<aside class="footnote brackets" id="id51" role="doc-footnote">
|
||
<dt class="label" id="id51">[<a href="#id8">27</a>]</dt>
|
||
<dd>The Python-hu Archives
|
||
(<a class="reference external" href="https://mail.python.org/pipermail/python-hu/">https://mail.python.org/pipermail/python-hu/</a>)</aside>
|
||
<aside class="footnote brackets" id="id52" role="doc-footnote">
|
||
<dt class="label" id="id52">[<a href="#id26">28</a>]</dt>
|
||
<dd>[Python-Dev] PEP 545: Python Documentation Translations
|
||
(<a class="reference external" href="https://mail.python.org/pipermail/python-dev/2017-April/147752.html">https://mail.python.org/pipermail/python-dev/2017-April/147752.html</a>)</aside>
|
||
</aside>
|
||
</section>
|
||
<section id="copyright">
|
||
<h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2>
|
||
<p>This document has been placed in the public domain.</p>
|
||
</section>
|
||
</section>
|
||
<hr class="docutils" />
|
||
<p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0545.rst">https://github.com/python/peps/blob/main/peps/pep-0545.rst</a></p>
|
||
<p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0545.rst">2023-09-09 17:39:29 GMT</a></p>
|
||
|
||
</article>
|
||
<nav id="pep-sidebar">
|
||
<h2>Contents</h2>
|
||
<ul>
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#motivation">Motivation</a></li>
|
||
<li><a class="reference internal" href="#rationale">Rationale</a><ul>
|
||
<li><a class="reference internal" href="#translation">Translation</a><ul>
|
||
<li><a class="reference internal" href="#issue-tracker">Issue tracker</a></li>
|
||
<li><a class="reference internal" href="#branches">Branches</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#hosting">Hosting</a><ul>
|
||
<li><a class="reference internal" href="#domain-name-content-negotiation-and-url">Domain Name, Content negotiation and URL</a></li>
|
||
<li><a class="reference internal" href="#language-tag">Language Tag</a></li>
|
||
<li><a class="reference internal" href="#fetching-and-building-translations">Fetching And Building Translations</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#community">Community</a><ul>
|
||
<li><a class="reference internal" href="#mailing-list">Mailing List</a></li>
|
||
<li><a class="reference internal" href="#chat">Chat</a></li>
|
||
<li><a class="reference internal" href="#repository-for-po-files">Repository for PO Files</a></li>
|
||
<li><a class="reference internal" href="#translation-tools">Translation tools</a></li>
|
||
<li><a class="reference internal" href="#documentation-contribution-agreement">Documentation Contribution Agreement</a></li>
|
||
<li><a class="reference internal" href="#language-team">Language Team</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#alternatives">Alternatives</a><ul>
|
||
<li><a class="reference internal" href="#simplified-english">Simplified English</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#changes">Changes</a><ul>
|
||
<li><a class="reference internal" href="#get-a-documentation-contribution-agreement">Get a Documentation Contribution Agreement</a></li>
|
||
<li><a class="reference internal" href="#migrate-github-repositories">Migrate GitHub Repositories</a></li>
|
||
<li><a class="reference internal" href="#setup-a-github-bot-for-documentation-contribution-agreement">Setup a GitHub bot for Documentation Contribution Agreement</a></li>
|
||
<li><a class="reference internal" href="#patch-docsbuild-scripts-to-compile-translations">Patch docsbuild-scripts to Compile Translations</a></li>
|
||
<li><a class="reference internal" href="#list-coordinators-in-the-devguide">List coordinators in the devguide</a></li>
|
||
<li><a class="reference internal" href="#create-sphinx-doc-language-switcher">Create sphinx-doc Language Switcher</a></li>
|
||
<li><a class="reference internal" href="#update-sphinx-doc-version-switcher">Update sphinx-doc Version Switcher</a></li>
|
||
<li><a class="reference internal" href="#enhance-rendering-of-untranslated-and-fuzzy-translations">Enhance Rendering of Untranslated and Fuzzy Translations</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#new-translation-procedure">New Translation Procedure</a><ul>
|
||
<li><a class="reference internal" href="#designate-a-coordinator">Designate a Coordinator</a></li>
|
||
<li><a class="reference internal" href="#create-github-repository">Create GitHub Repository</a></li>
|
||
<li><a class="reference internal" href="#setup-the-documentation-contribution-agreement">Setup the Documentation Contribution Agreement</a></li>
|
||
<li><a class="reference internal" href="#add-support-for-translations-in-docsbuild-scripts">Add support for translations in docsbuild-scripts</a></li>
|
||
<li><a class="reference internal" href="#add-translation-to-the-language-switcher">Add Translation to the Language Switcher</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#previous-discussions">Previous Discussions</a></li>
|
||
<li><a class="reference internal" href="#references">References</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
|
||
<br>
|
||
<a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0545.rst">Page Source (GitHub)</a>
|
||
</nav>
|
||
</section>
|
||
<script src="../_static/colour_scheme.js"></script>
|
||
<script src="../_static/wrap_tables.js"></script>
|
||
<script src="../_static/sticky_banner.js"></script>
|
||
</body>
|
||
</html> |