iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Polish wording in PEP-0545 (#228)

This commit is contained in:
Jim Fasarakis-Hilliard 2017-03-22 18:38:56 +02:00 committed by Brett Cannon
parent e638e87982
commit fdc8599b90
1 changed files with 104 additions and 102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

206
pep-0545.txt
View File

@ -15,8 +15,8 @@ Abstract
========
The intent of this PEP is to make existing translations of the Python
Documentation more accessible and discoverable. By doing so,
attracting and motivating new translators and new translations.
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:
@ -35,26 +35,27 @@ and the license will be the PSF License.
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: that's also why Python 3 now allows
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:
https://www.python.org/dev/peps/pep-3131/#rationale
There are a least 3 groups of people who are translating the Python
documentation in their mother language (french [16]_ [17]_ [18]_,
japanese [19]_ [20]_, spanish [21]_), even though their translation
are not visible on d.p.o. Other less visible and less organized
groups are also translating in their mother language, we heard of
Russian, Chinese, Korean, maybe some others we didn't found yet. This
PEP defines rules to move translations on docs.python.org so they can
easily be found by developers, newcomers and potential translators.
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
and potential translators.
The Japanese team currently (March 2017) translated ~80% of the
documentation, 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 documentation mutates.
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:
@ -92,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
triaging b.p.o by properly indicating, in the issue author language if
needed, 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
@ -108,10 +109,10 @@ done in one branch to other branches.
paragraphs, even removed ones. See also `Sphinx Internationalization
<http://www.sphinx-doc.org/en/stable/intl.html>`_.
The three stable branches will be translated [12]_: 2.7, 3.5, and 3.6.
The scripts to build the documentation of older branches have to be
modified to support translation [12]_, whereas these branches now only
accept security-only fixes.
The three currently stable branches that will be translated are [12]_:
2.7, 3.5, and 3.6. 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 (master) should have a lower translation priority
than stable branches. But docsbuild-scripts should build it anyway so
@ -122,12 +123,12 @@ release.
Hosting
-------
Domain Name, Content negociation and URL
Domain Name, Content negotiation and URL
''''''''''''''''''''''''''''''''''''''''
Different translation can be told appart by changing one of:
Country Code Top Level Domain (CCTLD),
path segment, subdomain, or by content negociation.
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
@ -136,57 +137,58 @@ 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` in uncommon and SEOMoz [23]_ correlated the presence of
`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 languages, which is more
maintenance, and will probably causes us troubles in language pickers
if, like for version picker, we want a preflight to check if the
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.
Using content negociation (HTTP headers ``Accept-Language`` in the
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." [25]_. As we want to be
able to easily change the language, we should not use the content
negociation as a main language determination, so we need somthing
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/". Example
with a hyphen: "docs.python.org/pt-BR/"
hyphens. Typically something like: "docs.python.org/de/" or, by
using a hyphen: "docs.python.org/pt-BR/".
As for version, sphinx-doc does not support compiling for multiple
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/". Question is "Does the language contains
multiple version or does version contains multiple languages?" As
versions exists in any cases, and translations for a given version may
or may not exists, we may prefer "docs.python.org/3.6/de/", but doing
so scatter languages everywhere. Having "/de/3.6/" is clearer about
"everything under /de/ is written in deutch". Having the version at
the end is also an habit taken by readers of the documentation: they
like to easily change the version by changing the end of the path.
"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.
So we should use the following pattern:
"docs.python.org/LANGUAGE_TAG/VERSION/".
Current documentation is not moved to "/en/", but "docs.python.org/en/"
will redirect to "docs.python.org/en/".
The current documentation is not moved to "/en/", insted
"docs.python.org/en/" will redirect to "docs.python.org".
Language Tag
''''''''''''
A common notation for language tags is the IETF Language Tag [3]_
[4]_ based on ISO 639, alghough gettext uses ISO 639 tags with
[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 -
@ -197,19 +199,19 @@ so we should use IETF language tags, even if sphinx uses gettext
internally: URLs are not meant to leak the underlying implementation.
It's uncommon to see capitalized letters in URLs, and docs.python.org
don't use any, so it may hurt readability by attracting the eye on it,
doesn'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 (Tags for Identifying Languages (IETF)) section-2.1 [7]_
tells the tags are not case sensitive. As the RFC allows lower case,
states that tags are not case sensitive. As the RFC allows lower case,
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, typically "de-DE", "fr-FR", although it make sense,
respectively "Deutch as spoken in Germany" and "French as spoken in
France", it's not a usefull information for the reader. So we may drop
those redundencies. We should obviously keep the country part when it
make sense like "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.
@ -221,19 +223,19 @@ Fetching And Building 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 we're
adding complexity, but not that much.
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: Build a new language,
and add it to the language picker. This allows a transition step
Two steps should be configurable distinctively: Building a new language,
and adding it to the language picker. 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
made public". During this step, translators can review their
modifications on d.p.o without having to build the documentation
locally.
From the translations repositories, only the ``.po`` files should be
From the translation repositories, only the ``.po`` files should be
opened by the docsbuild-script to keep the attack surface and probable
bugs sources at a minimum. This mean no translation can patch sphinx
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 [9]_).
@ -245,10 +247,10 @@ Mailing List
''''''''''''
The `doc-sig`_ mailing list will be used to discuss cross-language
changes on translated documentations.
changes on translated documentation.
There is also the i18n-sig list but it's more oriented towards i18n APIs
[1]_, than translation the Python documentation.
[1]_ than translating the Python documentation.
.. _i18n-sig: https://mail.python.org/mailman/listinfo/i18n-sig
.. _doc-sig: https://mail.python.org/mailman/listinfo/doc-sig
@ -257,21 +259,21 @@ There is also the i18n-sig list but it's more oriented towards i18n APIs
Chat
''''
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.
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.
Each language coordinator can organize its own team, even by choosing
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, and it's also natural for the local teams to reuse
their local channels like "#python-fr" for french translators.
single channel. It's also natural for the local teams to reuse
their local channels like "#python-fr" for French translators.
Repository for PO Files
'''''''''''''''''''''''
Considering that each translation teams may want to use different
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 ``.po`` files via a git
repository.
@ -283,22 +285,22 @@ will be hosted on github.
For consistency and discoverability, all translations should be in the
same github organization and named according to a common pattern.
Considering that we want translations to be official, and that Python
already have a github organization, translations should be hosted as
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`_.
For consistency, translations repositories should be called
For consistency, translation repositories should be called
``python-docs-LANGUAGE_TAG`` [22]_.
The docsbuild-scripts may enforce this rule by refusing to fetch
outside of the Python organization or a wrongly named repository.
The CLA bot may be used on the translation repositories, but with a
limited effect as local coordinators may synchronize themselves
translations from an external tool like transifex, loosing in the
process who translated what.
limited effect as local coordinators may synchronize themselves with
translations from an external tool, like transifex, and loose track
of who translated what in the process.
Version can be hosted on different repositories, different directories
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
is typical and natural to use branches to separate versions, branches
@ -328,14 +330,14 @@ https://www.python.org/psf/contrib/contrib-form/
Language Team
'''''''''''''
Each language team should have one coordinator responsible to:
Each language team should have one coordinator responsible for:
- Manage the team
- Choose and manage the tools its team will use (chat, mailing list, …)
- Ensure contributors understand and agree with the CLA
- Ensure quality (grammar, vocabulary, consistency, filtering spam, ads, …)
- Do redirect to GitHub issue tracker issues related to its
language on bugs.python.org
- Managing the team.
- Choosing and managing the tools the team will use (chat, mailing list, …).
- Ensure contributors understand and agree with the CLA.
- Ensure quality (grammar, vocabulary, consistency, filtering spam, ads, …).
- 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.
@ -347,14 +349,14 @@ Alternatives
Simplified English
''''''''''''''''''
It would be possible to introduce a "simplified english" version like
wikipedia did [10]_, as discussed on python-dev [11]_, targetting
english learners and childrens.
It would be possible to introduce a "simplified English" version like
wikipedia did [10]_, as discussed on python-dev [11]_, targeting
English learners and children.
Pros: It yields a single other translation, theorically readable by
everyone, and reviewable by current maintainers.
Pros: It yields a single translation, theoretically readable by
everyone and reviewable by current maintainers.
Cons: Subtle details may be lost, and translators from english to english
Cons: Subtle details may be lost, and translators from English to English
may be hard to find as stated by Wikipedia:
> The main English Wikipedia has 5 million articles, written by nearly
@ -370,9 +372,9 @@ Changes
Migrate GitHub Repositories
---------------------------
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 follow the `New Translation Procedure`_.
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 `New Translation Procedure`_.
Patch docsbuild-scripts to Compile Translations
@ -380,12 +382,12 @@ Patch docsbuild-scripts to Compile Translations
Docsbuild-script must be patched to:
- List the languages tags to build along with the branches to build.
- List the languages tags to display in the language picker.
- List the language tags to build along with the branches to build.
- List the language tags to display in the language picker.
- Find translation repositories by formatting
``github.com:python-docs/python-docs-{language_tag}.git`` (See
`Repository for Po Files`_)
- Build translations for each branches and each languages
- Build translations for each branch and each language.
Patched docsbuild-scripts must only open ``.po`` files from
translation repositories.
@ -395,7 +397,7 @@ List coordinators in the devguide
---------------------------------
Add a page or a section with an empty list of coordinators to the
devguide, each new coordinators will be added to this list.
devguide, each new coordinator will be added to this list.
Create sphinx-doc Language Picker
@ -424,7 +426,7 @@ Designate a Coordinator
The first step is to designate a coordinator, see `Language Team`_,
The coordinator must sign the CLA.
The coordinator should be added to a list of translation coordinator
The coordinator should be added to the list of translation coordinators
on the devguide.
@ -439,7 +441,7 @@ language coordinator push rights to this repository.
Add support for translations in docsbuild-scripts
-------------------------------------------------
As soon as the translation hits its firsts commits, update the
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).
@ -451,8 +453,8 @@ As soon as the translation hits:
- 100% of bugs.html with proper links to the language repository
issue tracker.
- 100% of tutorial
- 100% of library/functions (builtins)
- 100% of tutorial.
- 100% of library/functions (builtins).
the translation can be added to the language picker.