Update PEP 545
This commit is contained in:
Victor Stinner
parent
a3062a8744
commit
03172174c4
133
pep-0545.txt
133
pep-0545.txt
|
|
@ -22,14 +22,14 @@ Translated documentation will be hosted on python.org. Examples of
|
|||
two active translation teams:
|
||||
|
||||
* http://docs.python.org/fr/: French
|
||||
* http://docs.python.org/jp/: Japanese
|
||||
* http://docs.python.org/ja/: Japanese
|
||||
|
||||
http://docs.python.org/en/ will redirect to http://docs.python.org/.
|
||||
|
||||
Sources of translated documentation will be hosted in the Python
|
||||
Documentation organization on GitHub: https://github.com/python-docs/.
|
||||
Contributors will have to sign the Python Contributor Agreement (CLA)
|
||||
and the license will be the PSF License.
|
||||
organization on GitHub: https://github.com/python/. Contributors will
|
||||
have to sign the Python Contributor Agreement (CLA) and the license
|
||||
will be the PSF License.
|
||||
|
||||
|
||||
Motivation
|
||||
|
|
@ -46,10 +46,10 @@ There are a least 3 groups of people who are translating the Python
|
|||
documentation to their native language (French [16]_ [17]_ [18]_,
|
||||
Japanese [19]_ [20]_, Spanish [21]_) 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,
|
||||
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
|
||||
groups, are also translating the documentation, we've heard of Russian
|
||||
[26]_, 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
|
||||
|
|
@ -93,8 +93,8 @@ Stinner are already triaging, and Julien Palard is willing to help on
|
|||
this task, noise on b.p.o is not to be expected.
|
||||
|
||||
Also, language team coordinators (see `Language Team`_) should help
|
||||
with triaging b.p.o by properly indicating, in the language of the issue
|
||||
author if required, the right issue tracker.
|
||||
with triaging b.p.o by properly indicating, in the language of the
|
||||
issue author if required, the right issue tracker.
|
||||
|
||||
|
||||
Branches
|
||||
|
|
@ -135,17 +135,17 @@ 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 RFC1123 [24]_, 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 pickers
|
||||
if, as for version pickers, 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.
|
||||
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 RFC1123 [24]_, 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
|
||||
|
|
@ -191,7 +191,7 @@ A common notation for language tags is the IETF Language Tag [3]_
|
|||
[4]_ based on ISO 639, although gettext uses ISO 639 tags with
|
||||
underscores (ex: ``pt_BR``) instead of dashes to join tags [5]_
|
||||
(ex: ``pt-BR``). Examples of IETF Language Tags: ``fr`` (French),
|
||||
``jp`` (Japanese), ``pt-BR`` (Orthographic formulation of 1943 -
|
||||
``ja`` (Japanese), ``pt-BR`` (Orthographic formulation of 1943 -
|
||||
Official in Brazil).
|
||||
|
||||
It is more common to see dashes instead of underscores in URLs [6]_,
|
||||
|
|
@ -207,11 +207,12 @@ and it enhances readability, we should use lowercased tags like
|
|||
``pt-br``.
|
||||
|
||||
It's redundant to display both language and country code if they're
|
||||
the same, 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", it's not useful information for the reader. So we may drop
|
||||
these redundancies and only keep the country code for cases where
|
||||
it makes sense, for example, "pt-BR" for "Portuguese as spoken in Brazil".
|
||||
the same, 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", it's not useful information for the reader. So
|
||||
we may drop these redundancies and only keep the country code for
|
||||
cases where it makes sense, for example, "pt-BR" for "Portuguese as
|
||||
spoken in Brazil".
|
||||
|
||||
So we should use IETF language tags, lowercased, like ``/fr/``,
|
||||
``/pt-br/``, ``/de/`` and so on.
|
||||
|
|
@ -220,14 +221,14 @@ So we should use IETF language tags, lowercased, like ``/fr/``,
|
|||
Fetching And Building Translations
|
||||
''''''''''''''''''''''''''''''''''
|
||||
|
||||
Currently docsbuild-scripts are building the documentation [8]_. These scripts
|
||||
should be modified to fetch and build translations.
|
||||
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're
|
||||
adding complexity it is not that much.
|
||||
|
||||
Two steps should be configurable distinctively: Building a new language,
|
||||
and adding it to the language picker. This allows a transition step
|
||||
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
|
||||
|
|
@ -287,10 +288,11 @@ same github organization and named according to a common pattern.
|
|||
|
||||
Given that we want translations to be official, and that Python
|
||||
already has a github organization, translations should be hosted as
|
||||
projects of the `Python documentation GitHub organization`_.
|
||||
projects of the `Python GitHub organization`_.
|
||||
|
||||
For consistency, translation repositories should be called
|
||||
``python-docs-LANGUAGE_TAG`` [22]_.
|
||||
``python-docs-LANGUAGE_TAG`` [22]_, using the language tag used in
|
||||
paths: without region subtag if redundent, and lowercased.
|
||||
|
||||
The docsbuild-scripts may enforce this rule by refusing to fetch
|
||||
outside of the Python organization or a wrongly named repository.
|
||||
|
|
@ -302,11 +304,11 @@ of who translated what in the process.
|
|||
|
||||
Versions can be hosted on different repositories, different directories
|
||||
or different branches. Storing them on different repositories will
|
||||
probably pollute the Python documentation github organization. As it
|
||||
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.
|
||||
|
||||
.. _Python documentation GitHub organization: https://github.com/python-docs/
|
||||
.. _Python GitHub organization: https://github.com/python/
|
||||
|
||||
|
||||
Translation tools
|
||||
|
|
@ -321,8 +323,8 @@ and http://zanata.org/
|
|||
Contributor Agreement
|
||||
'''''''''''''''''''''
|
||||
|
||||
Contributions to translated documentation will be requested to sign the
|
||||
Python Contributor Agreement (CLA):
|
||||
Contributions to translated documentation will be requested to sign
|
||||
the Python Contributor Agreement (CLA):
|
||||
|
||||
https://www.python.org/psf/contrib/contrib-form/
|
||||
|
||||
|
|
@ -339,8 +341,9 @@ Each language team should have one coordinator responsible for:
|
|||
- Redirect issues posted on b.p.o to the correct GitHub issue tracker
|
||||
for the language.
|
||||
|
||||
The license will be the `PSF License <https://docs.python.org/3/license.html>`_,
|
||||
and copyright should be transferable to PSF later.
|
||||
The license will be the `PSF License
|
||||
<https://docs.python.org/3/license.html>`_, and copyright should be
|
||||
transferable to PSF later.
|
||||
|
||||
|
||||
Alternatives
|
||||
|
|
@ -383,9 +386,9 @@ Patch docsbuild-scripts to Compile Translations
|
|||
Docsbuild-script must be patched to:
|
||||
|
||||
- List the language tags to build along with the branches to build.
|
||||
- List the language tags to display in the language picker.
|
||||
- List the language tags to display in the language switcher.
|
||||
- Find translation repositories by formatting
|
||||
``github.com:python-docs/python-docs-{language_tag}.git`` (See
|
||||
``github.com:python/python-docs-{language_tag}.git`` (See
|
||||
`Repository for Po Files`_)
|
||||
- Build translations for each branch and each language.
|
||||
|
||||
|
|
@ -400,16 +403,32 @@ Add a page or a section with an empty list of coordinators to the
|
|||
devguide, each new coordinator will be added to this list.
|
||||
|
||||
|
||||
Create sphinx-doc Language Picker
|
||||
---------------------------------
|
||||
Create sphinx-doc Language Switcher
|
||||
-----------------------------------
|
||||
|
||||
Highly similar to the version picker, a language picker must be
|
||||
implemented. This language picker must be configurable to hide or
|
||||
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.
|
||||
|
||||
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 `Enhance Rendering of Untranslated and Fuzzy
|
||||
Translations`_.
|
||||
|
||||
Enhance rendering of untranslated fuzzy translations
|
||||
----------------------------------------------------
|
||||
|
||||
Update sphinx-doc Version Switcher
|
||||
----------------------------------
|
||||
|
||||
The ``patch_url`` function of the version switcher in
|
||||
``version_switch.js`` have to be updated to understand and allow the
|
||||
presence of the language segment in the path.
|
||||
|
||||
|
||||
Enhance Rendering of Untranslated and Fuzzy Translations
|
||||
--------------------------------------------------------
|
||||
|
||||
It's an opened sphinx issue [9]_, but we'll need it so we'll have to
|
||||
work on it. Translated, fuzzy, and untranslated paragraphs should be
|
||||
|
|
@ -430,12 +449,13 @@ The coordinator should be added to the list of translation coordinators
|
|||
on the devguide.
|
||||
|
||||
|
||||
Create github repository
|
||||
Create Github Repository
|
||||
------------------------
|
||||
|
||||
Create a repository named "python-docs-{LANGUAGE_TAG}" on the Python
|
||||
documentation github organization (See `Repository For Po Files`_.), and grant the
|
||||
language coordinator push rights to this repository.
|
||||
Create a repository named "python-docs-{LANGUAGE_TAG}" (IETF language
|
||||
tag, without redundent region subtag, with a dash, and lowercased.) on
|
||||
the Python github organization (See `Repository For Po Files`_.), and
|
||||
grant the language coordinator push rights to this repository.
|
||||
|
||||
|
||||
Add support for translations in docsbuild-scripts
|
||||
|
|
@ -443,11 +463,11 @@ Add support for translations in docsbuild-scripts
|
|||
|
||||
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 picker).
|
||||
displaying it in the language switcher).
|
||||
|
||||
|
||||
Add translation to the language picker
|
||||
--------------------------------------
|
||||
Add Translation to the Language Switcher
|
||||
----------------------------------------
|
||||
|
||||
As soon as the translation hits:
|
||||
|
||||
|
|
@ -456,10 +476,10 @@ As soon as the translation hits:
|
|||
- 100% of tutorial.
|
||||
- 100% of library/functions (builtins).
|
||||
|
||||
the translation can be added to the language picker.
|
||||
the translation can be added to the language switcher.
|
||||
|
||||
|
||||
Previous discussions
|
||||
Previous Discussions
|
||||
====================
|
||||
|
||||
- `[Python-ideas] Cross link documentation translations (January, 2016)`_
|
||||
|
|
@ -556,6 +576,9 @@ References
|
|||
.. [25] Accept-Language
|
||||
(https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language)
|
||||
|
||||
.. [26] Документация Python 2.7!
|
||||
(http://python-lab.ru/documentation/index.html)
|
||||
|
||||
Copyright
|
||||
=========
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue