PEP 545: Python Documentation Translations
Hi.
Here's PEP 545, ready to be reviewed!
This is the follow-up to the "PEP: Python Documentation Translations" thread on python-ideas [1]_,
itself a follow-up of the "Translated Python documentation" thread on python-dev [2]_.
This PEP describes the steps to make existing and future translations of the Python documentation official and accessible on docs.python.org.
You can read it rendered here https://www.python.org/dev/peps/pep-0545/ or inline here, I'll happily get your feedback.
========================================
PEP: 545
Title: Python Documentation Translations
Version: $Revision$
Last-Modified: $Date$
Author: Victor Stinner
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!
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 be following the `New Translation Procedure`_. 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 switcher. - Find translation repositories by formatting ``github.com:python/python-docs-{language_tag}.git`` (See `Repository for Po Files`_) - Build translations for each branch and each language. Patched docsbuild-scripts must only open ``.po`` files from translation repositories. List coordinators in the devguide --------------------------------- 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 Switcher ----------------------------------- 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`_. 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 differentiated. (Fuzzy paragraphs have to warn the reader what he's reading may be out of date.) New Translation Procedure ========================= 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 the list of translation coordinators on the devguide. Create Github 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 ------------------------------------------------- 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). Add Translation to the Language Switcher ---------------------------------------- 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). the translation can be added to the language switcher. Previous Discussions ==================== - `[Python-ideas] Cross link documentation translations (January, 2016)`_ - `[Python-ideas] Cross link documentation translations (January, 2016)`_ - `[Python-ideas] https://docs.python.org/fr/ ? (March 2016)`_ .. _[Python-ideas] Cross link documentation translations (January, 2016): https://mail.python.org/pipermail/python-ideas/2016-January/038010.html .. _[Python-Dev] Translated Python documentation (Febrary 2016): https://mail.python.org/pipermail/python-dev/2017-February/147416.html .. _[Python-ideas] https://docs.python.org/fr/ ? (March 2016): https://mail.python.org/pipermail/python-ideas/2016-March/038879.html References ========== .. [1] [I18n-sig] Hello Python members, Do you have any idea about Python documents? (https://mail.python.org/pipermail/i18n-sig/2013-September/002130.html) .. [2] [Doc-SIG] Localization of Python docs (https://mail.python.org/pipermail/doc-sig/2013-September/003948.html) .. [3] Tags for Identifying Languages (http://tools.ietf.org/html/rfc5646) .. [4] IETF language tag (https://en.wikipedia.org/wiki/IETF_language_tag) .. [5] GNU Gettext manual, section 2.3.1: Locale Names (https://www.gnu.org/software/gettext/manual/html_node/Locale-Names.html) .. [6] Semantic URL: Slug (https://en.wikipedia.org/wiki/Semantic_URL#Slug) .. [7] Tags for Identifying Languages: Formatting of Language Tags (https://tools.ietf.org/html/rfc5646#section-2.1.1) .. [8] Docsbuild-scripts github repository (https://github.com/python/docsbuild-scripts/) .. [9] i18n: Highlight untranslated paragraphs (https://github.com/sphinx-doc/sphinx/issues/1246) .. [10] Wikipedia: Simple English (https://simple.wikipedia.org/wiki/Main_Page) .. [11] Python-dev discussion about simplified english (https://mail.python.org/pipermail/python-dev/2017-February/147446.html) .. [12] Passing options to sphinx from Doc/Makefile (https://github.com/python/cpython/commit/57acb82d275ace9d9d854b156611e641f68...) .. [13] French translation progression (https://mdk.fr/pycon2016/#/11) .. [14] French translation contributors (https://github.com/AFPy/python_doc_fr/graphs/contributors?from=2016-01-01&to=2016-12-31&type=c) .. [15] Python-doc on Transifex (https://www.transifex.com/python-doc/) .. [16] French translation (https://www.afpy.org/doc/python/) .. [17] French translation github (https://github.com/AFPy/python_doc_fr) .. [18] French mailing list (http://lists.afpy.org/mailman/listinfo/traductions) .. [19] Japanese translation (http://docs.python.jp/3/) .. [20] Japanese github (https://github.com/python-doc-ja/python-doc-ja) .. [21] Spanish translation (http://docs.python.org.ar/tutorial/3/index.html) .. [22] [Python-Dev] Translated Python documentation: doc vs docs (https://mail.python.org/pipermail/python-dev/2017-February/147472.html) .. [23] Domains - SEO Best Practices | Moz (https://moz.com/learn/seo/domain) .. [24] Requirements for Internet Hosts -- Application and Support (https://www.ietf.org/rfc/rfc1123.txt) .. [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 ========= This document has been placed in the public domain. .. Local Variables: mode: indented-text indent-tabs-mode: nil sentence-end-double-space: t fill-column: 70 coding: utf-8 End: ======================================== .. [1] [Python-ideas] PEP: Python Documentation Translations (https://mail.python.org/pipermail/python-ideas/2017-March/045226.html) .. [2] [Python-Dev] Translated Python documentation (https://mail.python.org/pipermail/python-dev/2017-February/147416.html) Bests, -- Julien Palard https://mdk.fr
Sounds good overall! I only have one thing to suggest in regards to the license, two grammar tweaks, and a question. On Wed, 29 Mar 2017 at 08:10 Julien Palard via Python-Dev < python-dev@python.org> wrote:
[SNIP] Sources of translated documentation will be hosted in the Python 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.
Please check with the PSF that this is what we really want. In the past the suggestion has been to **not** use the PSF license with all of its historical baggage but instead use something like Apache. But since IANAL we really should ask the PSF what the best license for new code is.
[SNIP] 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 loose track of who translated what in the process.
"loose" -> "lose"
[SNIP] Other tools may be used later https://pontoon.mozilla.org/ and http://zanata.org/
"be used later like".
[SNIP]
Create sphinx-doc Language Switcher -----------------------------------
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`_.
What kind of support does Read the Docs have for translations? I have no active plans to push for this but it has been idea in the back of my head for a while so it would be good to know if such a move would make this easier or harder. -Brett
Hi Brett, thanks for the feedback! Please check with the PSF that this is what we really want. Gladly, but … how? I'm very new to all those process and have now idea on how I can get in touch with PSF lawyers. What kind of support does Read the Docs have for translations? I have no active plans to push for this but it has been idea in the back of my head for a while so it would be good to know if such a move would make this easier or harder. Read the Docs support translations [1]_, quoting them:
To support this, you will have one parent project and a number of projects marked as translations of that parent. Let’s use phpmyadmin as an example.
The main phpmyadmin project is the parent for all translations. Then you must create a project for each translation, for example phpmyadmin-spanish. You will set the Language for phpmyadmin-spanish to Spanish. In the parent projects Translations page, you will say that phpmyadmin-spanish is a translation for your project.
This has the results of serving: - phpmyadmin at http://phpmyadmin.readthedocs.io/en/latest/ - phpmyadmin-spanish at http://phpmyadmin.readthedocs.io/es/latest/
Which is nice as it's almost the same syntax the PEP proposes for paths: /{language_tag}/{version_tag}. Their language tags are simplified too (redundency removed (fr-FR → fr)) but not lowercased, and they use underscore "instead of" dashes as a separator, see for example: - https://docs.phpmyadmin.net/fr/latest/ - https://docs.phpmyadmin.net/pt_BR/latest/ while the PEP proposes /pt-br/ instead. .. [1] Project with multiple translations (https://docs.readthedocs.io/en/latest/localization.html#project-with-multipl...) -- Julien Palard [https://mdk.fr](https://mdk.fr/)
On Wed, 29 Mar 2017 at 13:13 Julien Palard
Hi Brett, thanks for the feedback!
Please check with the PSF that this is what we really want.
Gladly, but … how? I'm very new to all those process and have now idea on how I can get in touch with PSF lawyers.
What kind of support does Read the Docs have for translations? I have no active plans to push for this but it has been idea in the back of my head for a while so it would be good to know if such a move would make this easier or harder.
Read the Docs support translations [1]_, quoting them:
To support this, you will have one parent project and a number of projects marked as translations of that parent. Let’s use phpmyadmin as an example.
The main phpmyadmin project is the parent for all translations. Then you must create a project for each translation, for example phpmyadmin-spanish. You will set the Language for phpmyadmin-spanish to Spanish. In the parent projects Translations page, you will say that phpmyadmin-spanish is a translation for your project.
This has the results of serving: - phpmyadmin at http://phpmyadmin.readthedocs.io/en/latest/ - phpmyadmin-spanish at http://phpmyadmin.readthedocs.io/es/latest/
Which is nice as it's almost the same syntax the PEP proposes for paths: /{language_tag}/{version_tag}. Their language tags are simplified too (redundency removed (fr-FR → fr)) but not lowercased, and they use underscore "instead of" dashes as a separator, see for example:
- https://docs.phpmyadmin.net/fr/latest/ - https://docs.phpmyadmin.net/pt_BR/latest/
while the PEP proposes /pt-br/ instead.
.. [1] Project with multiple translations ( https://docs.readthedocs.io/en/latest/localization.html#project-with-multipl... )
Should we just match what Read the Docs does then?
Hi Brett,
On Wed, 29 Mar 2017 at 13:13 Julien Palard
Congratulations! After a brief review period, and noticing there has not been more discussion on this PEP, I have *approved* the latest version of PEP 545. Hopefully one of the authors can update the PEP text in the peps repo with this status change, linking to this message. (Note that my approval does not preclude minor textual tweaks and clarifications, or even updates to specific processes recommended by the PEP. This PEP seems to be a work in progress in terms of some details, but I approve of the overall plan, and it is now up to the PEP authors to implement that plan.) -- --Guido van Rossum (python.org/~guido)
Champagne! Congrats *Julien*! Julien Palards is the one who really
drives the effort to get a translated doc at python.org. Thanks also
Naoki INADA for the help on that PEP. I didn't do much, except of
pushing to get a PEP and get everything written down to make things
going smoothly and making the discussion more productive.
Victor
2017-05-20 22:54 GMT-07:00 Guido van Rossum
Congratulations!
After a brief review period, and noticing there has not been more discussion on this PEP, I have *approved* the latest version of PEP 545.
Hopefully one of the authors can update the PEP text in the peps repo with this status change, linking to this message.
(Note that my approval does not preclude minor textual tweaks and clarifications, or even updates to specific processes recommended by the PEP. This PEP seems to be a work in progress in terms of some details, but I approve of the overall plan, and it is now up to the PEP authors to implement that plan.)
-- --Guido van Rossum (python.org/~guido)
On 3/29/2017 4:13 PM, Julien Palard via Python-Dev wrote:
Gladly, but … how? I'm very new to all those process and have now idea on how I can get in touch with PSF lawyers.
https://www.python.org/about/legal/ "If you have any questions, please send them to the legal mailing list at: legal@python.org." -- Terry Jan Reedy
Hi, little follow-up about this PEP. Please check with the PSF that this is what we really want. In the past the suggestion has been to **not** use the PSF license with all of its historical baggage but instead use something like Apache. But since IANAL we really should ask the PSF what the best license for new code is. I checked with the PSF and after a few emails with VanL (thanks), we concluded that we need a "Documentation Contribution Agreement" (they're working on writing it), then we'll *just* have to ensure contributors are understanding and agreeing with it. I think we should setup a bot like "The Knights Who Say Ni" from PEP 512 [1]_ or The Knight Who Say Ni itself, configured for the "DCLA" what do you think? The bot will *only* cover contributions from actual github pull requests, other means of contributions like transifex can be enforced by other means, namely: - We can write a welcome text like "By contributing to this transifex project I accept the Documentation Contribution Licence Agreement…". - We can ask contributors to specifically write they accept the licence agreement along witht the translation independently of the way they send us translations. (It even work for paper…). .. [1] PEP 512 -- Migrating from hg.python.org to GitHub (https://www.python.org/dev/peps/pep-0512/#a-bot-to-enforce-cla-signing) -- Julien Palard https://mdk.fr
On Tue, 4 Apr 2017 at 04:58 Julien Palard
Hi, little follow-up about this PEP.
Please check with the PSF that this is what we really want. In the past the suggestion has been to **not** use the PSF license with all of its historical baggage but instead use something like Apache. But since IANAL we really should ask the PSF what the best license for new code is.
I checked with the PSF and after a few emails with VanL (thanks), we concluded that we need a "Documentation Contribution Agreement" (they're working on writing it), then we'll *just* have to ensure contributors are understanding and agreeing with it.
I think we should setup a bot like "The Knights Who Say Ni" from PEP 512 [1]_ or The Knight Who Say Ni itself, configured for the "DCLA" what do you think?
It's definitely possible. The bot is designed to be easily customizable from a server hosting, PR hosting, and CLA hosting perspective. Question is whether the DCLA will be managed the same as the CLA, i.e. a flag set on bugs.python.org? -Brett
The bot will *only* cover contributions from actual github pull requests, other means of contributions like transifex can be enforced by other means, namely:
- We can write a welcome text like "By contributing to this transifex project I accept the Documentation Contribution Licence Agreement…". - We can ask contributors to specifically write they accept the licence agreement along witht the translation independently of the way they send us translations. (It even work for paper…).
.. [1] PEP 512 -- Migrating from hg.python.org to GitHub (https://www.python.org/dev/peps/pep-0512/#a-bot-to-enforce-cla-signing )
-- Julien Palard https://mdk.fr
Typos:
english -> English
Febrary -> February
insted -> instead
redundent -> redundant
* Julien Palard
It's redundant to display both language and country code if they're the same, for example: "de-DE" or "fr-FR".
This wording is unfortunate. It seems to imply that you can meaningfully compare a language code and a territory code for equality. This is not the case. For example, Belarusian (language code "be") is mainly spoken in Belarus (country code "by"), not in Belgium (country code "be"). -- Jakub Wilk
Hi Jakub,
Typos
Fixed, thanks.
* Julien Palard
It's redundant to display both language and country code if they're the same, for example: "de-DE" or "fr-FR".
This wording is unfortunate. It seems to imply that you can meaningfully compare a language code and a territory code for equality. This is not the case. For example, Belarusian (language code "be") is mainly spoken in Belarus (country code "by"), not in Belgium (country code "be"). Thanks for noticing, would the intented meaning is "when they add no distinguishing information", is it better like: ====== We may drop the region subtag when it does 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" for "Portuguese as spoken in Brazil", it should be kept. ====== ? Bests, -- Julien Palard https://mdk.fr
participants (6)
-
Brett Cannon
-
Guido van Rossum
-
Jakub Wilk
-
Julien Palard
-
Terry Reedy
-
Victor Stinner