[Python-ideas] PEP: Python Documentation Translations

[Julien Palard]

Hi Nick,

My one request for clarification would be whether or not there would be redirects back to the /en/ versions in place when there is no translation for a particular version (e.g. the older security-fix only branches). I'm not sure it matters all that much either way, but the PEP should be explicit.

About switching language in the same version:

A 404 can't occur (both builds are from the *same* rst files), although the destination page may not be translated. In this case the page should still be displayed (as it exists) the page should warn about its untranslated state. It's a more a sphinx-doc issue than a python doc issue, but it still should be adressed, see "Enhance rendering of untranslated fuzzy translations".

About switching version in the same language:
A 404 can occur, but is already handled by the current version switcher, which preflights the request and give you the home page in case the destination does not exists. This behavior will be kept in the version switcher.

However the current version switcher should be updated to understand the language segment in the path, I reviewed its code and it's not ready, so I updated the PEP, I changed the Language Switcher paragraph to:

Create sphinx-doc Language Switcher
-----------------------------------

Highly similar to the version switcher, a language switcher must be
implemented. This language switcher must be configurable to hide or
show a given language.

The language switcher will only have to update or add the language
segment to the path like the current version switcher does. Unlike
the version switcher, no preflight are required as destination page
always exists (translations does not add or remove pages).
Untranslated (but existing) pages still exists, they should however be
rendered as so, see `Enhance Rendering of Untranslated and Fuzzy
Translations`_.

And added:

Update sphinx-doc Version Switcher
----------------------------------

The ``patch_url`` function of the version switcher in
``version_switch.js`` have to be updated to understand and allow the
presence of the language segment in the path.

I also replaced occurrences of "picker" with "switcher" at it's the vocabulary used in the current version pi^Wswitcher.

--
Julien Palard
https://mdk.fr
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20170322/6e0b17f6/attachment.html>