Cross link documentation translations
o/ While translating the Python Documentation in French [1][2], I discovered that we're not the only country doing it, there is also Japan [3][4], and Spain [5]. It's possible there's other but I didn't find them (and it's the problem). But there's only a few way for users to find the translations (hearing about them, or explicitly searching for them on a search engine, which they won't do, obviously expecting a link from the english version if they exists). So here is my idea: Why not linking translations from the main documentation? I know that's not directly supported by Sphinx doc [6], but separate sphinx build, blindly (with hardcoded links) linking themselves, may work (like readthedoc is probably doing). The downside of those links is that we'll sometime link to untranslated parts, but those parts may be marked as untranslated [7] to encourage new translators to help. Thoughts? [1] http://www.afpy.org/doc/python/3.5/ [2] https://github.com/afpy/python_doc_fr [3] http://docs.python.jp/3/ [4] https://github.com/python-doc-ja/python-doc-ja [5] http://docs.python.org.ar/tutorial/3/index.html [6] https://github.com/sphinx-doc/sphinx/issues/2252 [7] https://github.com/sphinx-doc/sphinx/issues/1246 -- Julien Palard
I am -1 for linking the official documentation to anything not on docs.python.org (or to things like the source listings link on the library docs, which is controlled by the same party as controls the documentation). It irks me every time I see a link to activestate recipes in the official docs. Activestate has already taken down documentation they have previously hosted, and the recipes will only exist as long as it is advantageous to them to continue hosting them*. The same can be said of translation projects that don't exist as special interest groups under the PSF. But I do like the idea of linking to translations. Would it not be a better solution to try and unify the translation efforts into one system as SIGs of the Doc-SIG? Besides, linking only to documentation you generate (as hosting the docs as a sig under the doc-sig would allow) would make the technical implementation much easier. Baring that, its a better-than-nothing idea. * not to mention the questionable quality of the recipes. On 1/24/2016 05:35, Julien Palard wrote:
On 01/24/2016 03:51 PM, Alexander Walters wrote:
Being hosted on doc.python.org is probably the neatest way to do it: So I can only agree.
Actually we generate the whole documentation, even untranslated parts, (actually Sphinx does it). Also, ignoring the internal working of special interest groups, I completely miss the "hosting the docs as a sig under the doc-sig" part: does SIG has hostings ? -- Julien Palard
Julien Palard writes:
As you're probably aware, Debian[1] has #(languages) + 2 teams translating the Debian-specific parts of packages. One of the special teams works on internationalizing the packaging software (mostly but not entirely done, even after more than a decade), and another provides infrastructure for accepting and distributing translations. As with Debian, I don't think there will be unification of organizations, and it certainly isn't needed. On the other hand, *somebody* will need to construct the web page and repository structure and linkage, and there will be an on-going need for integrating new versions. The debian-i18n mailing list is also useful for propagating best practices. Quality of translation is an issue that Debian doesn't much have to deal with (because the Debian teams are working on the same task -- installation and configuration -- they quickly develop idioms for repetitive queries), but for manuals the issue is important. IMHO, it would be ideal if the integrators included a team of editor/reviewers independent of the various language teams. At least for Japanese, translations (both of generic English and specifically English software manuals) are often mechanical and not very educational, and occasionally actively misleading. Of course this is pie-in-the-sky; surely people with such skills and the interest are likely to be participating in the teams. But I think it's a good idea to keep quality of translation in mind, and possibly impose some sort of formal review process or two-approvals requirement. Footnotes: [1] The example I'm familiar with, I suppose many other projects have similar setups.
ReadTheDocs supports hosting projects with multiple translations: | Docs: http://docs.readthedocs.org/en/latest/localization.html - [ ] There could be a dedicated Python Infrastructure ReadtheDocs Docker instance. https://github.com/rtfd/readthedocs-docker-images ReadTheDocs CPython Docs /en/latest/ * | Docs: http://cpython.readthedocs.org/en/latest/ * | Project: http://readthedocs.org/projects/cpython/ * [ ] All past revisions * [ ] All translations On Jan 24, 2016 4:41 AM, "Julien Palard" <julien@palard.fr> wrote:
o/
While translating the Python Documentation in French [1][2], I discovered
that we're not the only country doing it, there is also Japan [3][4], and Spain [5]. It's possible there's other but I didn't find them (and it's the problem).
But there's only a few way for users to find the translations (hearing
about them, or explicitly searching for them on a search engine, which they won't do, obviously expecting a link from the english version if they exists).
So here is my idea: Why not linking translations from the main
documentation?
I know that's not directly supported by Sphinx doc [6], but separate
sphinx build, blindly (with hardcoded links) linking themselves, may work (like readthedoc is probably doing). The downside of those links is that we'll sometime link to untranslated parts, but those parts may be marked as untranslated [7] to encourage new translators to help.
I am -1 for linking the official documentation to anything not on docs.python.org (or to things like the source listings link on the library docs, which is controlled by the same party as controls the documentation). It irks me every time I see a link to activestate recipes in the official docs. Activestate has already taken down documentation they have previously hosted, and the recipes will only exist as long as it is advantageous to them to continue hosting them*. The same can be said of translation projects that don't exist as special interest groups under the PSF. But I do like the idea of linking to translations. Would it not be a better solution to try and unify the translation efforts into one system as SIGs of the Doc-SIG? Besides, linking only to documentation you generate (as hosting the docs as a sig under the doc-sig would allow) would make the technical implementation much easier. Baring that, its a better-than-nothing idea. * not to mention the questionable quality of the recipes. On 1/24/2016 05:35, Julien Palard wrote:
On 01/24/2016 03:51 PM, Alexander Walters wrote:
Being hosted on doc.python.org is probably the neatest way to do it: So I can only agree.
Actually we generate the whole documentation, even untranslated parts, (actually Sphinx does it). Also, ignoring the internal working of special interest groups, I completely miss the "hosting the docs as a sig under the doc-sig" part: does SIG has hostings ? -- Julien Palard
Julien Palard writes:
As you're probably aware, Debian[1] has #(languages) + 2 teams translating the Debian-specific parts of packages. One of the special teams works on internationalizing the packaging software (mostly but not entirely done, even after more than a decade), and another provides infrastructure for accepting and distributing translations. As with Debian, I don't think there will be unification of organizations, and it certainly isn't needed. On the other hand, *somebody* will need to construct the web page and repository structure and linkage, and there will be an on-going need for integrating new versions. The debian-i18n mailing list is also useful for propagating best practices. Quality of translation is an issue that Debian doesn't much have to deal with (because the Debian teams are working on the same task -- installation and configuration -- they quickly develop idioms for repetitive queries), but for manuals the issue is important. IMHO, it would be ideal if the integrators included a team of editor/reviewers independent of the various language teams. At least for Japanese, translations (both of generic English and specifically English software manuals) are often mechanical and not very educational, and occasionally actively misleading. Of course this is pie-in-the-sky; surely people with such skills and the interest are likely to be participating in the teams. But I think it's a good idea to keep quality of translation in mind, and possibly impose some sort of formal review process or two-approvals requirement. Footnotes: [1] The example I'm familiar with, I suppose many other projects have similar setups.
ReadTheDocs supports hosting projects with multiple translations: | Docs: http://docs.readthedocs.org/en/latest/localization.html - [ ] There could be a dedicated Python Infrastructure ReadtheDocs Docker instance. https://github.com/rtfd/readthedocs-docker-images ReadTheDocs CPython Docs /en/latest/ * | Docs: http://cpython.readthedocs.org/en/latest/ * | Project: http://readthedocs.org/projects/cpython/ * [ ] All past revisions * [ ] All translations On Jan 24, 2016 4:41 AM, "Julien Palard" <julien@palard.fr> wrote:
o/
While translating the Python Documentation in French [1][2], I discovered
that we're not the only country doing it, there is also Japan [3][4], and Spain [5]. It's possible there's other but I didn't find them (and it's the problem).
But there's only a few way for users to find the translations (hearing
about them, or explicitly searching for them on a search engine, which they won't do, obviously expecting a link from the english version if they exists).
So here is my idea: Why not linking translations from the main
documentation?
I know that's not directly supported by Sphinx doc [6], but separate
sphinx build, blindly (with hardcoded links) linking themselves, may work (like readthedoc is probably doing). The downside of those links is that we'll sometime link to untranslated parts, but those parts may be marked as untranslated [7] to encourage new translators to help.
participants (4)
-
Alexander Walters -
Julien Palard -
Stephen J. Turnbull -
Wes Turner