On 03/21/2016 11:38 AM, Victor Stinner wrote:
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  and IETF goes by using a dash .
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-co...),
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