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

[Julien Palard]

Hi,

On 03/21/2016 11:38 AM, Victor Stinner wrote:
> Hi,
> 
> 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.

I like the idea of running "msgmerge" at each patch so outdated
translations are rapidly removed (marked as "fuzzy"), it's probably
possible and easy. Our makefile provide a "msgmerge_all" to do that on
all versions. I'll keep it in mind.

>>  - ...
>>  - untranslated strings may be visually marked as so
> 
> I don't think that it's needed. It's quite easy to notice untranslated parts...

It's strongly linked to your "Do you plan to use a web UI to allow
anyone to translate easily": I think we should provide a simple way to
propose little corrections or even whole paragraph translations, but:

 - Not soon, the project does not depend on it and it's more a
Sphinx-doc feature than a Python documentations feature, it should be
treated separately.
 - From my point of view, proposed translations goes to a moderation
queue, they can't be accepted directly.
 - Some services like crowdin (on which we have an unlimited free plan,
thanks Crowdin !) provide those kind of features (and crowdin is already
interfaced with poedit). However I have not used crowdin that much and
still prefer poedit+git for that. We may also write a git bot
auto-generating pull requests... Many ideas here, that we should
probably discuss in a sphinx-related issue or mailing list.

>> ### Dropping the default locale of a language
> 
> IMHO we should see what PHP did, since PHP has a long history with
> documentation translation.
> 
> So /fr/ for french, but /pt_BR/ for Brazilian Portuguese. We can use
> something similar for Python.

Dropping a redundant local (fr_FR -> fr) seems logic, but I still prefer
"pt-br" over "pt_BR", counterbalancing the PHP doc using "pt_BR" we have
some big player using pt-br like:
 - wordpress: https://codex.wordpress.org/pt-br:Codex_Multilingua
 - facebook: https://pt-br.facebook.com/login/
 - msn: www.msn.com/pt-br/
 - skype: www.skype.com/pt-br

> I would really prefer to not move on more time the Python doc (add /en/
> to the URL),

I agree, we don't have to move the actual doc under `/en/`. If setting
redirections we can set them from `/en/` to `/` just in case someone
modify /fr/ to /en/ manually.

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

That's a whole other subject, but as we're on it, instead of giving a
404 for https://docs.python.org/3.5/len or even
https://docs.python.org/len why not displaying a search result page with
hopefully len as a first result ? I was sur I read some RFC telling that
a 404 should return "relevant links" but can't find it in the 2616 :(

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

I can only disagree, dashes seems more common than underscores in URLs
from my point of view, see typically slugs
(https://en.wikipedia.org/wiki/Semantic_URL#Slug) but my link
contradicts itself with a "Semantic_URL" instead of a "Semantic-URL" ...
slugs (with dashes) are commonly used like at stackoverflow, yahoo,
amazon, the Python doc itself
(https://docs.python.org/3.5/library/stdtypes.html#numeric-types-int-float-complex),

Also the Google recommendation "We recommend that you use hyphens (-)
instead of underscores (_) in your URLs."
https://support.google.com/webmasters/answer/76329?hl=en

-- 
Julien Palard
+08 99 49 05 40
http://mdk.fr