Update PEP 545

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/.
+organization on GitHub: https://github.com/python/.  Contributors will
-Contributors will have to sign the Python Contributor Agreement (CLA)
+have to sign the Python Contributor Agreement (CLA) and the license
-and the license will be the PSF 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,
+groups, are also translating the documentation, we've heard of Russian
-Chinese and Korean. Others we haven't found yet might also exist.
+[26]_, Chinese and Korean. Others we haven't found yet might also
-This PEP defines rules describing how to move translations
+exist.  This PEP defines rules describing how to move translations on
-on docs.python.org so they can easily be found by developers, newcomers
+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
+with triaging b.p.o by properly indicating, in the language of the
-author if required, the right issue tracker.
+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`?").
+possible but confusing ("is it `es.docs.python.org` or
-Hyphens in subdomains like
+`docs.es.python.org`?").  Hyphens in subdomains like
-`pt-br.doc.python.org` is uncommon and SEOMoz [23]_ correlated the presence of
+`pt-br.doc.python.org` is uncommon and SEOMoz [23]_ correlated the
-hyphens as a negative factor.  Usage of underscores in subdomain is
+presence of hyphens as a negative factor.  Usage of underscores in
-prohibited by the RFC1123 [24]_, section 2.1.  Finally, using subdomains
+subdomain is prohibited by the RFC1123 [24]_, section 2.1.  Finally,
-means creating TLS certificates for each language. This not only
+using subdomains means creating TLS certificates for each
-requires more maintenance but will also cause issues in language pickers
+language. This not only requires more maintenance but will also cause
-if, as for version pickers, we want a preflight to check if the
+issues in language switcher if, as for version switcher, we want a
-translation exists in the given version: preflight will probably be
+preflight to check if the translation exists in the given version:
-blocked by same-origin-policy.  Wildcard TLS certificates are very
+preflight will probably be blocked by same-origin-policy.  Wildcard
-expensive.
+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,
+the same, for example: "de-DE" or "fr-FR".  Although it might make
-respectively meaning "German as spoken in Germany" and "French as spoken in
+sense, respectively meaning "German as spoken in Germany" and "French
-France", it's not useful information for the reader.  So we may drop
+as spoken in France", it's not useful information for the reader.  So
-these redundancies and only keep the country code for cases where
+we may drop these redundancies and only keep the country code for
-it makes sense, for example, "pt-BR" for "Portuguese as spoken in Brazil".
+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
+Currently docsbuild-scripts are building the documentation [8]_.
-should be modified to fetch and build translations.
+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
+Contributions to translated documentation will be requested to sign
-Python Contributor Agreement (CLA):
+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>`_,
+The license will be the `PSF License
-and copyright should be transferable to PSF later.
+<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
+Highly similar to the version switcher, a language switcher must be
-implemented.  This language picker must be configurable to hide or
+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
+Create a repository named "python-docs-{LANGUAGE_TAG}" (IETF language
-documentation github organization (See `Repository For Po Files`_.), and grant the
+tag, without redundent region subtag, with a dash, and lowercased.) on
-language coordinator push rights to this repository.
+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
 =========