[Python-ideas] https://docs.python.org/fr/ ?

[Julien Palard]

o/

The french translation of the Python Documentation [1][2] has translated 
20% of the pageviews of docs.python.org. I think it's the right moment 
to push it do docs.python.org. So there's some questions ! And I'd like 
feedback.

TL;DR (with my personal choices):
  - URL may be "http://docs.python.org/fr/"
  - For localized variations of languages we should use dash and 
lowercase like "docs.python.org/pt-br/"
  - po files may be hosted on the python's github
  - existing script to build doc may be patched to build translations
  - each translations may crosslink to others
  - untranslated strings may be visually marked as so

I also opened: http://bugs.python.org/issue26546.

# Chronology, dependencies

The only blocking decision here is the URL, (also reviewing my patch 
...), with those two, translated docs can be pushed to production, and 
the other steps can be discussed and applied one by one.

# The URL

## CCTLD vs path vs subdomain

I think we should use a variation of "docs.python.org/fr/" for 
simplicity and clarity.

I think we should avoid using CCTLDs as they're sometime hard or near 
impossible to obtain (may cost a lot of time), also some are expensive, 
so it's time and money we clearly don't need to loose.

Last possibility I see is to use a subdomain, like fr.docs.python.org or 
docs.fr.python.org but I don't think it's the role / responsibility of 
the sub-domain to do it.

So I'm for docs.python.org/LANGUAGE_TAG/ (without moving current 
documentation inside a /en/).

## Language tag in path

### Dropping the default locale of a language

I personally think we should not show the region in case it's redundant: 
so to use "fr" instead of "fr-FR", "de" instead of "de-DE", but keeping 
the possibility to use a locale code when it's not redundant like for 
"pt-br" or "de-AT" (German ('de') as used in Austria ('AT')).

I think so because I don't think we'll have a lot of locale variations 
(like de-AT, fr-CH, fr-CA, ...) so it will be most of the time redundant 
(visually heavy, longer to type, longer to read) but we'll still need 
some locale (pt-BR typically).

### gettext VS IETF language tag format

gettext goes by using an underscore between language and locale [3] and 
IETF goes by using a dash [4][5].

As sphinx is using gettext, and gettext uses underscore we may choose 
underscore too. But URLs are not here to leak the underlying 
implementation, and the IETF looks like to be the standard way to 
represent language tags. Also I visually prefer the dash over the 
underscore, so I'm for the dash here.

### Lower case vs upper case local tag

RFC 5646 section-2.1 tells us language tags are not case sensitive, yet 
ISO3166-1 recommends that country codes (part of the language tag) be 
capitalized. I personally prefer the all-lowercase one as paths in URLs 
typically are lowercase. I searched for `inurl:"pt-br"` to see if I'm 
not too far away from the usage here and usage seems to agree with me, 
although there's some "pt-BR" in urls.

# Where to host the translated files

Currently we're hosting the *po* files in the afpy's (Francophone 
association for python) [6] github [1] but it may make sense to use (in 
the generation scripts) a more controlled / restricted clone in the 
python github, at least to have a better view of who can push on the 
documentation.

We may want to choose between aggregating all translations under the 
same git repository but I don't feel it's useful.

# How to

Currently, a python script [7] is used to generate `docs.python.org`, I 
proposed a patch in [8] to make this script clone and build the french 
translation too, it's a simple and effective way, I don't think we need 
more ? Any idea welcome.

In our side, we have a Makefile [12] to build the translated doc which 
is only a thin layer on top of the Sphinx Makefile. So my proposed patch 
to build scripts "just" delegate the build to our Makefile which itself 
delegate the hard work to the Sphinx Makefile.

# Next ?

## Document how to translate Python

I think I can (should) write a documentation on "how to start a Python 
doc translation project" and "how to migrate existing [9][10][11] python 
doc translation projects to docs.python.org" if french does goes 
docs.python.org because it may hopefully motivate people to do the same, 
and I think our structure is a nice way to do it (A Makefile to generate 
the doc, all versions translated, people mainly working on latest 
version, scripts to propagating translations to older version, etc...).

## Crosslinking between existing translations

Once the translations are on `docs.python.org`, crosslinks may be 
established so people on a version can be aware of other version, and 
easily switch to them. I'm not a UI/UX man but I think we may have a 
select box right before the existing select box about version, on the 
top-left corner. Right before because it'll reflect the path: /fr/3.5/ 
-> [select box fr][select box 3.5].

## Marking as "untranslated, you can help" the untranslated paragraphs

The translations will always need work to follow upstream modifications: 
marking untranslated paragraphs as so may transform the "Oh they suck, 
this paragraph is not even translated :-(" to "Hey, nice I can help 
translating that !". There's an opened sphinx-doc ticket to do so [13] 
but I have not worked on it yet. As previously said I'm real bad at 
designing user interfaces, so I don't even visualize how I'd like it to be.


[1] http://www.afpy.org/doc/python/3.5/
[2] https://github.com/afpy/python_doc_fr
[3] https://www.gnu.org/software/gettext/manual/html_node/Locale-Names.html
[4] http://tools.ietf.org/html/rfc5646
[5] https://en.wikipedia.org/wiki/IETF_language_tag
[6] http://www.afpy.org/
[7] https://github.com/python/docsbuild-scripts/
[8] http://bugs.python.org/issue26546
[9] http://docs.python.jp/3/
[10] https://github.com/python-doc-ja/python-doc-ja
[11] http://docs.python.org.ar/tutorial/3/index.html
[12] https://github.com/AFPy/python_doc_fr/blob/master/Makefile
[13] https://github.com/sphinx-doc/sphinx/issues/1246

-- 
Julien Palard