Hi, 2016-03-19 17:30 GMT+01:00 Julien Palard <julien@palard.fr>:
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.
Nice.
TL;DR (with my personal choices): - URL may be "http://docs.python.org/fr/" - ... - existing script to build doc may be patched to build translations
If we choose to officially have translated documentation, I suggest to ensure that it has the same content thant the english. I don't want to read an outdated translated doc. I mean that all doc (en+fr) must be recompiled when a patch is merged.
- ... - untranslated strings may be visually marked as so
I don't think that it's needed. It's quite easy to notice untranslated parts...
### 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')).
IMHO we should see what PHP did, since PHP has a long history with documentation translation. http://php.net/manual/en/function.strlen.php http://php.net/manual/fr/function.strlen.php http://php.net/manual/pt_BR/function.strlen.php So /fr/ for french, but /pt_BR/ for Brazilian Portuguese. We can use something similar for Python. They chose to have /en/ in the URL of the original (english) documentation, *but* http://php.net/strlen is the translated doc. I would really prefer to not move on more time the Python doc (add /en/ to the URL), since *a lot* of articles have references to the Python doc. Or if you really want to do that, please add redirection (forever?). I'm lazy and I really like writing http://php.net/<function name> to get the documentation of a function. It's much more difficult to get the doc of len in the Python doc...
### 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].
PHP chose an underscore, it's more common in URLs. I prefer pt_BR. Anyway, users will use a dropdown list rather than explicitly writing the URL, no?
# 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.
Do you plan to use a web UI to allow anyone to translate easily the doc? It may have an impact on the authentication system. Should such contribution be pushed directly and become a draft which requires a review?
## 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].
Usually (on web sites, the language is chosen at the top right. Victor