OSDir

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[no subject]


Community
---------

Mailing List
''''''''''''

The `doc-sig`_ mailing list will be used to discuss cross-language
changes on translated documentation.

There is also the i18n-sig list but it's more oriented towards i18n APIs
[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

Chat
''''

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 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.

Repository for PO Files
'''''''''''''''''''''''

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.

Considering that each translation will be exposed via git
repositories, and that Python has migrated to GitHub, translations
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.

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 GitHub organization`_.

For consistency, translation repositories should be called
``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.

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.

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.

.. _Python GitHub organization: https://github.com/python/

Translation tools
'''''''''''''''''

Most of the translation work is actually done on Transifex [15]_.

Other tools may be used later https://pontoon.mozilla.org/
and http://zanata.org/

Contributor Agreement
'''''''''''''''''''''

Contributions to translated documentation will be requested to sign
the Python Contributor Agreement (CLA):

https://www.python.org/psf/contrib/contrib-form/

Language Team
'''''''''''''

Each language team should have one coordinator responsible for:

- 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.

Alternatives
------------

Simplified English
''''''''''''''''''

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 translation, theoretically readable by
everyone and reviewable by current maintainers.

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
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/57acb82d275ace9d9d854b156611e641f68e9e7c)

.. [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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20170329/d78f4c76/attachment-0001.html>