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

[Victor Stinner]

Hi,

2016-03-19 17:30 GMT+01:00 Julien Palard <julien at 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