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

INADA Naoki songofacandy at gmail.com
Mon Jan 30 04:21:57 EST 2017

There are some updates about this topic.
 And I have something to discuss to get things forward.

We (Japanese translation team) and Julien start sharing one Transifex project.
Please see this dashboard.  We have nice progress.

Julien want hosting french documentation at https://docs.python.org/fr/
I don't have strong opinion about where to hosting, but I want to share
more efforts (automated build + hosting) with Julien and other language

Since Berker Peksag against about hosting translated document on
docs.python.org [1], I'm considering about using github pages.

I got "python-docs" organization already for it [2].  So translated documents
can be hosted on URL like https://python-docs.github.io/py35-ja/ or
https://python-docs.github.io/py35/fr/ .  (first part of the path
should be same to
repository name).

I already uses github pages for testing Japanese translation [3].
It's nice place to host webpage.  We can get https and CDN for free.

[1]: https://github.com/python/docsbuild-scripts/pull/8
[2]: https://github.com/python-docs
[3]: https://python-doc-ja.github.io/py35/

So I want to discuss (and get consensus) about where should we host
translated document.

a) translated docs on docs.python.org / issue tracker on github.com/python-docs/
b) translated docs on python-docs.github.io / issue tracker on
c) We shouldn't use neither "python-docs" nor "docs.python.org".
Translation should be in other community.
d) Other idea?

What do you think?


On Sun, Mar 20, 2016 at 1:30 AM, Julien Palard <julien at palard.fr> wrote:
> 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
> _______________________________________________
> Python-ideas mailing list
> Python-ideas at python.org
> https://mail.python.org/mailman/listinfo/python-ideas
> Code of Conduct: http://python.org/psf/codeofconduct/

More information about the docs mailing list