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

[INADA Naoki]

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.
https://www.transifex.com/python-doc/python-35/dashboard/

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

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
github.com/python-docs/
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?


Regards,

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/