Hi, I'm a member of the french #python-fr IRC channel on Freenode: it's common to meet people who don't speak english and so are unable to read the Python official documentation. Python wants to be widely available, for all users, in any language: that's also why Python 3 now allows any non-ASCII identifiers: https://www.python.org/dev/peps/pep-3131/#rationale There are a least 3 groups of people who are translating the Python documentation in their mother language (french, japanese, spanish). They tried to make it more official, but their attempt didn't go far yet. I'm writing this email to propose to officially support translated versions of the documentation. For me, the most impotant point would be to give access to the translated documentation from docs.python.org. For example, have a dropdown list with available languages. IMHO a reference in this domain is PHP: PHP documentation is translated to at least 10 languages. See for example the "Change language: [...]" list at: http://php.net/echo I'm not asking you to take any technical decision here, I'm just asking for an official general "support" of translated documentation. References to translated documentations: Transiflex project: https://www.transifex.com/python-doc/ Français (French, FR): doc: https://www.afpy.org/doc/python/ source: https://github.com/AFPy/python_doc_fr mailing list: http://lists.afpy.org/mailman/listinfo/traductions Japanese (JP): doc: http://docs.python.jp/3/ source: https://github.com/python-doc-ja/python-doc-ja Spanish: doc: http://docs.python.org.ar/tutorial/3/index.html Previous discussions: [Python-ideas] Cross link documentation translations (January, 2016): https://mail.python.org/pipermail/python-ideas/2016-January/038010.html [Python-ideas] https://docs.python.org/fr/ ? (March 2016) https://mail.python.org/pipermail/python-ideas/2016-March/038879.html Victor
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 02/22/2017 07:10 AM, Victor Stinner wrote:
Hi,
I'm a member of the french #python-fr IRC channel on Freenode: it's common to meet people who don't speak english and so are unable to read the Python official documentation. Python wants to be widely available, for all users, in any language: that's also why Python 3 now allows any non-ASCII identifiers: https://www.python.org/dev/peps/pep-3131/#rationale
There are a least 3 groups of people who are translating the Python documentation in their mother language (french, japanese, spanish). They tried to make it more official, but their attempt didn't go far yet. I'm writing this email to propose to officially support translated versions of the documentation.
For me, the most impotant point would be to give access to the translated documentation from docs.python.org. For example, have a dropdown list with available languages.
IMHO a reference in this domain is PHP: PHP documentation is translated to at least 10 languages. See for example the "Change language: [...]" list at:
I'm not asking you to take any technical decision here, I'm just asking for an official general "support" of translated documentation.
+1 for the idea. Tres. - -- =================================================================== Tres Seaver +1 540-429-0999 tseaver@palladion.com Palladion Software "Excellence by Design" http://palladion.com -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 iQIcBAEBAgAGBQJYrawEAAoJEPKpaDSJE9HYevwP/0KsRu1KNkBGFVffA8WNBDqT khZta8AogUnvIkubNxDWvtMgo+UDgXdpW0D0/uCI5ON8O6TVeAQp8JB5giZkKt6e VSoXjPaD4sJJRjWCFj+z33DCu/HlVE5+qt60cRQ6kwWWKWm6Aoh+yiu1g0CDQIN0 miOmc+6rZWTptYUDYX3j/gq1W/XxiaEDIJTf9D8GUQ7YZA6AyTkzUm1o9OY8PJdg lSsTxkjuriQPLJq6IVXMZxOUPKgU/O9HLL9r3XfRqA/sIle6pz6z6qKIQOHj246E lKiSXwm2Gik+XrIk0YfIG+ZezlWJuRyyA+7wksxQmX/Azl85iQ/Nb5/zwVMTfpF1 NIT0++bpefM5X/Y7CLusupNIQ90k5dSMjX9uPOBoK/ZIJ7I6QglBVxr97CHx1FCn lJ4brOkBnGCtz9mJ50FgM4YqYuUUWjw8mZxpjv5URl8ouPdZnhmuWmiRJLgezmbV n0uqjr9XvEdXEYidRzL39LAWcERJIj1CfyyCgDISYw8eaZsrn29lrk0F8x17XAIP Z0iIF4cYg0Z1oXqmWelzljDyo66GIMybof3R2pHKCiPlfZeE3b+AwgU2eyI+6lnj iVfQi5ok4XuYMydmJhjfWbmz8xb0jkqQ7un3TRb6w8MFOS1WxxYAsVJnesA6Jk3c g4leycwmSg9dTQ/TSRZj =6/rU -----END PGP SIGNATURE-----
Hi Victor, On Wed, 22 Feb 2017 13:10:17 +0100 Victor Stinner <victor.stinner@gmail.com> wrote:
IMHO a reference in this domain is PHP: PHP documentation is translated to at least 10 languages. See for example the "Change language: [...]" list at:
I'm not asking you to take any technical decision here, I'm just asking for an official general "support" of translated documentation.
As long as you are asking for "moral" support and not actually vouching for the accuracy of third-party translations, then +1 from me. à bientôt Antoine.
2017-02-22 16:40 GMT+01:00 Antoine Pitrou <solipsis@pitrou.net>:
As long as you are asking for "moral" support and not actually vouching for the accuracy of third-party translations, then +1 from me.
The main complain about these translations is the accuracy. My bet is that making these translations "official" and more visible (at docs.python.org) would make them more popular, and so indirectly help to recruit new contributors. Slowly, the number of translated pages should increase, but the overall translation quality should also increase. That's how free software are developed, no? :-) Victor
On 22.02.17 18:15, Victor Stinner wrote:
2017-02-22 16:40 GMT+01:00 Antoine Pitrou <solipsis@pitrou.net>:
As long as you are asking for "moral" support and not actually vouching for the accuracy of third-party translations, then +1 from me.
The main complain about these translations is the accuracy.
My bet is that making these translations "official" and more visible (at docs.python.org) would make them more popular, and so indirectly help to recruit new contributors. Slowly, the number of translated pages should increase, but the overall translation quality should also increase. That's how free software are developed, no? :-)
What percent of lines is changed between bugfix releases? Feature releases? My largest apprehension is that the documentation can be outdated and quickly become degraded if main contributors left it.
On Wed, Feb 22, 2017 at 3:04 PM, Serhiy Storchaka <storchaka@gmail.com> wrote:
My largest apprehension is that the documentation can be outdated and quickly become degraded if main contributors left it.
This is why we focus in the Tutorial only, but also: a) The tutorial is mostly the "entry point" to Python's doc, so being it in Spanish for Spanish speakers lowers the barrier a lot b) At some point you need to understand English docs, so translating the library reference should not be that important Regards, -- . Facundo Blog: http://www.taniquetil.com.ar/plog/ PyAr: http://www.python.org/ar/ Twitter: @facundobatista
2017-02-22 19:04 GMT+01:00 Serhiy Storchaka <storchaka@gmail.com>:
What percent of lines is changed between bugfix releases? Feature releases?
My largest apprehension is that the documentation can be outdated and quickly become degraded if main contributors left it.
If the original text (english) changes, untranslated text is displayed, not outdated text. The french translation uses gettext. I don't know how other translations are implemented. Victor
On Thu, Feb 23, 2017 at 12:01 AM, Victor Stinner <victor.stinner@gmail.com> wrote:
2017-02-22 19:04 GMT+01:00 Serhiy Storchaka <storchaka@gmail.com>:
What percent of lines is changed between bugfix releases? Feature releases?
My largest apprehension is that the documentation can be outdated and quickly become degraded if main contributors left it.
If the original text (english) changes, untranslated text is displayed, not outdated text.
I think that's much worse than showing the outdated text. I don't see any point on showing half English and half French text if the reader can't understand the other half of it. As someone who have spent a lot of time reviewing and committing documentation patches, I'm strongly against on marking documentation translations as official. The Python documentation updates frequently and it's simply not possible to keep them sync with the official documentation. See https://github.com/python/cpython/commits/master/Doc for the commit history of the official documentation. You can easily compare it with the translations by looking their GitHub repositories. Also, there are a lot of better educational materials (e.g. Django Girls Tutorial) for people who don't speak English and have no previous programming experience. Even the tutorial contains several references to different programming concepts and programming languages such as C++. --Berker
On Fri, Feb 24, 2017 at 9:20 PM, Berker Peksağ <berker.peksag@gmail.com> wrote:
On Thu, Feb 23, 2017 at 12:01 AM, Victor Stinner <victor.stinner@gmail.com> wrote:
2017-02-22 19:04 GMT+01:00 Serhiy Storchaka <storchaka@gmail.com>:
What percent of lines is changed between bugfix releases? Feature releases?
My largest apprehension is that the documentation can be outdated and quickly become degraded if main contributors left it.
If the original text (english) changes, untranslated text is displayed, not outdated text.
I think that's much worse than showing the outdated text. I don't see any point on showing half English and half French text if the reader can't understand the other half of it.
In Japan, everyone learn English at school, but most people is not good at English. So 80% translated text helps us very much. Especially, Sphinx split document by paragraph. It's best granularity for translation. For example, there are some English paragraph remains in pathlib document <https://docs.python.jp/3/library/pathlib.html>. But it's very useful for Japanese not good at English.
As someone who have spent a lot of time reviewing and committing documentation patches, I'm strongly against on marking documentation translations as official.
I totally agree with you. Our QA is not good as commit review of CPython. So what I want is (un|semi) official place for we share our efforts with other language translators. (e.g. automated build, hosting translated documentation, and downstream customizations like adding link to official English document).
The Python documentation updates frequently and it's simply not possible to keep them sync with the official documentation. See https://github.com/python/cpython/commits/master/Doc for the commit history of the official documentation. You can easily compare it with the translations by looking their GitHub repositories.
While we don't translate mastar branch, I admit we behind several weeks or months from upstream. But since we moved most work on Travis, we can make it weekly or even daily. And we can share the automation with other Languages if we have a team. I can do it without official agreement, but I don't want to do it until I get consensus about domain name or github organization name.
Also, there are a lot of better educational materials (e.g. Django Girls Tutorial) for people who don't speak English and have no previous programming experience. Even the tutorial contains several references to different programming concepts and programming languages such as C++.
Sadly, there are many medium level programmers who are not good at English in Japan. So translated library reference is very helpful too. Regards,
On 24 February 2017 at 23:05, INADA Naoki <songofacandy@gmail.com> wrote:
On Fri, Feb 24, 2017 at 9:20 PM, Berker Peksağ <berker.peksag@gmail.com> wrote:
As someone who have spent a lot of time reviewing and committing documentation patches, I'm strongly against on marking documentation translations as official.
I totally agree with you. Our QA is not good as commit review of CPython. So what I want is (un|semi) official place for we share our efforts with other language translators. (e.g. automated build, hosting translated documentation, and downstream customizations like adding link to official English document).
The Python documentation updates frequently and it's simply not possible to keep them sync with the official documentation. See https://github.com/python/cpython/commits/master/Doc for the commit history of the official documentation. You can easily compare it with the translations by looking their GitHub repositories.
While we don't translate mastar branch, I admit we behind several weeks or months from upstream. But since we moved most work on Travis, we can make it weekly or even daily. And we can share the automation with other Languages if we have a team.
Right, I think this is the key: helping the language translation communities set up common flows so they can collaborate on the backend automation, request process or tech changes in the main docs to simplify translation (such as resolving the issue with "implementation detail" notes disappearing when translated), and generally improving discoverability of the translated versions. In addition to the case of folks that struggle to read the English documentation at all, I'd assume that there are also folks that would appreciate the chance to check their own understanding against someone else's translation of various topics. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On 24/02/2017 12:20, Berker Peksağ wrote:
On Thu, Feb 23, 2017 at 12:01 AM, Victor Stinner <victor.stinner@gmail.com> wrote:
2017-02-22 19:04 GMT+01:00 Serhiy Storchaka <storchaka@gmail.com>:
What percent of lines is changed between bugfix releases? Feature releases?
My largest apprehension is that the documentation can be outdated and quickly become degraded if main contributors left it. If the original text (english) changes, untranslated text is displayed, not outdated text. I think that's much worse than showing the outdated text. I don't see any point on showing half English and half French text if the reader can't understand the other half of it.
Fair point (especially if you substitute a language totally unrelated to English (e.g. Turkish, Finnish, Urdu, Japanese) for "French"). But it can be turned around: Popular demand would encourage whoever is maintaining the translated versions to catch up within a reasonable time when changes are made. It would nudge non-English readers to look at the untranslated English text and begin/develop their knowledge of English. Best wishes, Rob Cliffe
Could we have side-by-side English and whatever translated language? Then also use some sort of typographic indicator like color to show when the translation is out of date? On Feb 26, 2017 6:39 PM, "Rob Cliffe" <rob.cliffe@btinternet.com> wrote:
On 24/02/2017 12:20, Berker Peksağ wrote:
On Thu, Feb 23, 2017 at 12:01 AM, Victor Stinner <victor.stinner@gmail.com> wrote:
2017-02-22 19:04 GMT+01:00 Serhiy Storchaka <storchaka@gmail.com>:
What percent of lines is changed between bugfix releases? Feature releases?
My largest apprehension is that the documentation can be outdated and quickly become degraded if main contributors left it.
If the original text (english) changes, untranslated text is displayed, not outdated text.
I think that's much worse than showing the outdated text. I don't see any point on showing half English and half French text if the reader can't understand the other half of it.
Fair point (especially if you substitute a language totally unrelated to English (e.g. Turkish, Finnish, Urdu, Japanese) for "French"). But it can be turned around: Popular demand would encourage whoever is maintaining the translated versions to catch up within a reasonable time when changes are made. It would nudge non-English readers to look at the untranslated English text and begin/develop their knowledge of English. Best wishes, Rob Cliffe
Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/mertz% 40gnosis.cx
On 27 February 2017 at 14:03, David Mertz <mertz@gnosis.cx> wrote:
Could we have side-by-side English and whatever translated language? Then also use some sort of typographic indicator like color to show when the translation is out of date?
This kind of interface is what services like Transifex and Zanata offer translators (they also have things like phrase dictionaries, showing how particular terms have been translated elsewhere in the project). For the actual documentation, showing partial translations is the standard practice, as the assumption is that many readers will have *some* ability to read English, they just prefer to read their native language. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On Sun, Feb 26, 2017 at 11:30 PM, Nick Coghlan <ncoghlan@gmail.com> wrote:
On 27 February 2017 at 14:03, David Mertz <mertz@gnosis.cx> wrote:
Could we have side-by-side English and whatever translated language? Then also use some sort of typographic indicator like color to show when the translation is out of date?
This kind of interface is what services like Transifex and Zanata offer translators (they also have things like phrase dictionaries, showing how particular terms have been translated elsewhere in the project).
For the actual documentation, showing partial translations is the standard practice, as the assumption is that many readers will have *some* ability to read English, they just prefer to read their native language.
I think it would be at least as useful for readers as for the translators. As you mention, many readers will have *some* English. If they can look from the left half to the right half of the screen in synchronized texts (or perhaps top/bottom; whatever), they can read the English as well as they are able while simultaneously reading as much of their preferred language as is available. If their preferred language is available but possibly not current, they could decide whether to try to understand the difference in the canonical English version. I really liked this in books I've read. There are a fair number of languages other than English where I can make a little bit of sense of the text (but sadly only the one in which I'm proficient). Nonetheless, I like looking at the original text next to the English that I actually understand fully. Admittedly this is especially nice for something like poetry where you can read for meter on one side then content on the other... that's not the same concern as technical documentation, I realize. But even if only as an option, I think it would be a valuable interface for many readers. -- Keeping medicines from the bloodstreams of the sick; food from the bellies of the hungry; books from the hands of the uneducated; technology from the underdeveloped; and putting advocates of freedom in prisons. Intellectual property is to the 21st century what the slave trade was to the 16th.
2017-02-24 13:20 GMT+01:00 Berker Peksağ <berker.peksag@gmail.com>:
If the original text (english) changes, untranslated text is displayed, not outdated text.
I think that's much worse than showing the outdated text. I don't see any point on showing half English and half French text if the reader can't understand the other half of it.
Sorry, it doesn't make sense to me. If I wouldn't be to read english at all, and I have the choice between a doc partially translated and a doc written fully in english (current docs.python.org), the obvious choice for me would be to pick the partially translated doc. It's better than nothing. No? Victor
On 23 February 2017 at 02:15, Victor Stinner <victor.stinner@gmail.com> wrote:
2017-02-22 16:40 GMT+01:00 Antoine Pitrou <solipsis@pitrou.net>:
As long as you are asking for "moral" support and not actually vouching for the accuracy of third-party translations, then +1 from me.
The main complain about these translations is the accuracy.
My bet is that making these translations "official" and more visible (at docs.python.org) would make them more popular, and so indirectly help to recruit new contributors. Slowly, the number of translated pages should increase, but the overall translation quality should also increase. That's how free software are developed, no? :-)
+1 from me for these reasons, and those Facundo gives: we want folks to be able to learn at least the basics of Python *before* they learn English (even if learning English remains a pre-requisite for tapping into the full capabilities of both the language and its ecosystem). Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
My gut splits the difference on this issue; I suggest an approach to meet in the middle – a version of the docs written in simplified English (Not quite Up Goer Five simplified, but simplified.) It has the practical benefit of having more eyes to look at the docs to check for accuracy, it targets both English learners and children, and is something the current contributors to the documentation can do. For any language you want to support other than English, you need a translator who is A: a python expert, B: fluent in English, and C: fluent in the target language. …And then you need another one to check what was written. These are practical problems. There are extant services to support this, they are expensive in either money or time, and the docs produced usually lag behind English quite a bit. From: Python-Dev [mailto:python-dev-bounces+tritium-list=sdamon.com@python.org] On Behalf Of Nick Coghlan Sent: Friday, February 24, 2017 5:02 AM To: Victor Stinner <victor.stinner@gmail.com> Cc: Antoine Pitrou <solipsis@pitrou.net>; Python Dev <python-dev@python.org> Subject: Re: [Python-Dev] Translated Python documentation On 23 February 2017 at 02:15, Victor Stinner <victor.stinner@gmail.com <mailto:victor.stinner@gmail.com> > wrote: 2017-02-22 16:40 GMT+01:00 Antoine Pitrou <solipsis@pitrou.net <mailto:solipsis@pitrou.net> >:
As long as you are asking for "moral" support and not actually vouching for the accuracy of third-party translations, then +1 from me.
The main complain about these translations is the accuracy. My bet is that making these translations "official" and more visible (at docs.python.org <http://docs.python.org> ) would make them more popular, and so indirectly help to recruit new contributors. Slowly, the number of translated pages should increase, but the overall translation quality should also increase. That's how free software are developed, no? :-) +1 from me for these reasons, and those Facundo gives: we want folks to be able to learn at least the basics of Python *before* they learn English (even if learning English remains a pre-requisite for tapping into the full capabilities of both the language and its ecosystem). Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com <mailto:ncoghlan@gmail.com> | Brisbane, Australia
I've recently been translating the Tutorial in Greek as a side thing that also helps me catch some doc bugs :-). So it's an obvious +1 from me. I really like this idea and would like to see it come to fruition. I think some issues need to be addressed first, though: Where should these translated docs live and how does one make it clear to users reading them that doc bugs shouldn't be submitted to the main bug tracker/github repo? these are just two that popped in my head. It would be great if this went forward, many people will find the path to learning Python much much easier to walk if, at least the tutorial, was written in a language they are comfortable in.
Where should these translated docs live and how does one make it clear to users reading them that doc bugs shouldn't be submitted to the main bug tracker/github repo?
We setup github page. See https://python-doc-ja.github.io/py36/ (note that version switcher won't work because this html is build for docs.python.jp.) I reserved "python-docs" organization. So we can use URL like https://python-doc.github.io/<lang>/3.6/ (Because the organization name looks "something official", I won't use it until we get consensus about it.) For issue tracker, bugs.html must mention about translated document, before mention to normal issue tracker.
On Fri, 24 Feb 2017 at 03:50 INADA Naoki <songofacandy@gmail.com> wrote:
Where should these translated docs live and how does one make it clear to users reading them that doc bugs shouldn't be submitted to the main bug tracker/github repo?
We setup github page. See https://python-doc-ja.github.io/py36/ (note that version switcher won't work because this html is build for docs.python.jp .)
I reserved "python-docs" organization. So we can use URL like https://python-doc.github.io/<lang>/3.6/ (Because the organization name looks "something official", I won't use it until we get consensus about it.)
For issue tracker, bugs.html must mention about translated document, before mention to normal issue tracker.
It's getting a little hard to tease out what exactly is being asked at this point. Perhaps it's time to move the discussion over to a translation SIG (which probably needs to be created unless the old https://mail.python.org/mailman/listinfo/i18n-sig makes sense)? That way active translators can figure out exactly what they want to ask of python-dev in terms of support and we can have a more focused discussion.
On Feb 25, 2017, at 13:19, Brett Cannon <brett@python.org> wrote:
It's getting a little hard to tease out what exactly is being asked at this point. Perhaps it's time to move the discussion over to a translation SIG (which probably needs to be created unless the old https://mail.python.org/mailman/listinfo/i18n-sig makes sense)? That way active translators can figure out exactly what they want to ask of python-dev in terms of support and we can have a more focused discussion.
I agree. We would need a more concrete and detailed proposal to really make any thoughtful decision. That may also include getting approval from the PSF Board as they are ultimately responsible for the contents of python.org. Without more detail, I don't have an opinion myself other than to note that, if we do something, it needs to be careful to not complicate or restrict the Python release process. -- Ned Deily nad@python.org -- []
Yes, right place to discussion is one of important things what I want. I haven't know about i18n-sig. Is it better than docs-sig? Another thing I want is agreement to use project name looks like (semi)official project. We used "python-doc-jp" name on Transifex at first. But since some people other than Japanese ask me to allow other languages, I renamed it to "python-doc". And I reserved "python-docs" organization at Github. While it's better name for working together with other Language translators, I don't like that unofficial project use such name. Hosting at docs.python.org is desirable too, but it can be discussed later. Regards, On Sun, Feb 26, 2017 at 4:08 AM, Ned Deily <nad@python.org> wrote:
On Feb 25, 2017, at 13:19, Brett Cannon <brett@python.org> wrote:
It's getting a little hard to tease out what exactly is being asked at this point. Perhaps it's time to move the discussion over to a translation SIG (which probably needs to be created unless the old https://mail.python.org/mailman/listinfo/i18n-sig makes sense)? That way active translators can figure out exactly what they want to ask of python-dev in terms of support and we can have a more focused discussion.
I agree. We would need a more concrete and detailed proposal to really make any thoughtful decision. That may also include getting approval from the PSF Board as they are ultimately responsible for the contents of python.org. Without more detail, I don't have an opinion myself other than to note that, if we do something, it needs to be careful to not complicate or restrict the Python release process.
-- Ned Deily nad@python.org -- []
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/songofacandy%40gmail.com
On 26 February 2017 at 05:57, INADA Naoki <songofacandy@gmail.com> wrote:
Yes, right place to discussion is one of important things what I want. I haven't know about i18n-sig. Is it better than docs-sig?
Another thing I want is agreement to use project name looks like (semi)official project.
We used "python-doc-jp" name on Transifex at first. But since some people other than Japanese ask me to allow other languages, I renamed it to "python-doc". And I reserved "python-docs" organization at Github.
+1 from me for continuing to use those names (although you may want to standardise on "python-docs", since the mailing list is docs-sig, and the site is docs.python.org). While it's not translation related, I'll also note an idea that came up at the language summit a couple of years ago: moving the tutorial and the howto guides *out* of the version-specific documentation and into a separate version independent docs repository. As the stats Serhiy posted suggest, these typically *don't* change a great deal between versions, and when they do, the version differences are often going to be better handled inline (e.g. "On versions older than 3.x, ....") rather than by maintaining multiple distinct versions of the document. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On Sat, 25 Feb 2017 at 11:59 INADA Naoki <songofacandy@gmail.com> wrote:
Yes, right place to discussion is one of important things what I want. I haven't know about i18n-sig. Is it better than docs-sig?
Probably not (I honestly forgot about docs-sig).
Another thing I want is agreement to use project name looks like (semi)official project.
We used "python-doc-jp" name on Transifex at first. But since some people other than Japanese ask me to allow other languages, I renamed it to "python-doc".
As Nick suggested, "python-docs" is probably a better name to be consistent. -Brett
And I reserved "python-docs" organization at Github.
While it's better name for working together with other Language translators, I don't like that unofficial project use such name.
Hosting at docs.python.org is desirable too, but it can be discussed later.
Regards,
On Feb 25, 2017, at 13:19, Brett Cannon <brett@python.org> wrote:
It's getting a little hard to tease out what exactly is being asked at
On Sun, Feb 26, 2017 at 4:08 AM, Ned Deily <nad@python.org> wrote: this point. Perhaps it's time to move the discussion over to a translation SIG (which probably needs to be created unless the old https://mail.python.org/mailman/listinfo/i18n-sig makes sense)? That way active translators can figure out exactly what they want to ask of python-dev in terms of support and we can have a more focused discussion.
I agree. We would need a more concrete and detailed proposal to really
make any thoughtful decision. That may also include getting approval from the PSF Board as they are ultimately responsible for the contents of python.org. Without more detail, I don't have an opinion myself other than to note that, if we do something, it needs to be careful to not complicate or restrict the Python release process.
-- Ned Deily nad@python.org -- []
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe:
https://mail.python.org/mailman/options/python-dev/songofacandy%40gmail.com _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/brett%40python.org
2017-02-25 19:19 GMT+01:00 Brett Cannon <brett@python.org>:
It's getting a little hard to tease out what exactly is being asked at this point. Perhaps it's time to move the discussion over to a translation SIG (which probably needs to be created unless the old https://mail.python.org/mailman/listinfo/i18n-sig makes sense)? That way active translators can figure out exactly what they want to ask of python-dev in terms of support and we can have a more focused discussion.
Things are already happening in the background on other lists and other Python projects, but the problem is that the translation project seems "blocked" for some reasons. That's why I started the thread. Example of a recent CPython PR, blocked: https://github.com/python/cpython/pull/195 "bpo-28331: fix "CPython implementation detail:" label is removed when content is translated." opened 7 days ago by INADA Naoki (JP translation) Example of a docsbuild PR: https://github.com/python/docsbuild-scripts/pull/8 "[WIP] Add french, japanese, and chinese", opened at 12 Dec 2016 by Julien Palard (FR translation) See also Julien Palard's threads on python-ideas: no decision was taken, so the project is blocked. According to this thread, there is an official GO for official translations, so these PR should be merged, right? Victor
[catching up on an older thread] On Feb 27, 2017, at 05:31, Victor Stinner <victor.stinner@gmail.com> wrote:
2017-02-25 19:19 GMT+01:00 Brett Cannon <brett@python.org>:
It's getting a little hard to tease out what exactly is being asked at this point. Perhaps it's time to move the discussion over to a translation SIG (which probably needs to be created unless the old https://mail.python.org/mailman/listinfo/i18n-sig makes sense)? That way active translators can figure out exactly what they want to ask of python-dev in terms of support and we can have a more focused discussion.
Things are already happening in the background on other lists and other Python projects, but the problem is that the translation project seems "blocked" for some reasons. That's why I started the thread.
Example of a recent CPython PR, blocked: https://github.com/python/cpython/pull/195 "bpo-28331: fix "CPython implementation detail:" label is removed when content is translated." opened 7 days ago by INADA Naoki (JP translation)
Example of a docsbuild PR: https://github.com/python/docsbuild-scripts/pull/8 "[WIP] Add french, japanese, and chinese", opened at 12 Dec 2016 by Julien Palard (FR translation)
See also Julien Palard's threads on python-ideas: no decision was taken, so the project is blocked.
According to this thread, there is an official GO for official translations, so these PR should be merged, right?
I don't know exactly what you mean by an "official GO" but I don't think there has been any agreement yet since there hasn't been a specific proposal yet to review. I think what *was* agreed is that, in principle, translation *sounds* like a good idea to follow up on elsewhere, i.e. on one of the existing sigs, and then come back with a specific proposal for review. Thinking about that a little more, I think the appropriate output of those discussions should be a process PEP. Then we can review the proposal properly and also have the process clearly documented for the future. -- Ned Deily nad@python.org -- []
2017-03-10 0:35 GMT+01:00 Ned Deily <nad@python.org>:
I don't know exactly what you mean by an "official GO" but I don't think there has been any agreement yet since there hasn't been a specific proposal yet to review. I think what *was* agreed is that, in principle, translation *sounds* like a good idea to follow up on elsewhere, i.e. on one of the existing sigs, and then come back with a specific proposal for review. Thinking about that a little more, I think the appropriate output of those discussions should be a process PEP. Then we can review the proposal properly and also have the process clearly documented for the future.
FYI we are already working on a PEP with Julien Palard (FR) and INADA Naoki (JP). We will post it when it will be ready ;-) Victor
2017-03-10 1:03 GMT+01:00 Victor Stinner <victor.stinner@gmail.com>:
FYI we are already working on a PEP with Julien Palard (FR) and INADA Naoki (JP). We will post it when it will be ready ;-)
Ok, Julien wrote the PEP with the help of Naoki and myself. He posted it on python-ideas for a first review: https://mail.python.org/pipermail/python-ideas/2017-March/045226.html The PEP is now very complete and lists all requested changes on the Python side. Let's discuss that on the python-ideas list ;-) Victor
On Fri, Feb 24, 2017 at 06:01:59AM -0500, tritium-list@sdamon.com wrote:
My gut splits the difference on this issue; I suggest an approach to meet in the middle – a version of the docs written in simplified English (Not quite Up Goer Five simplified, but simplified.)
As an English speaker, my gut tells me that it would be much harder to write *accurate* simplified English technical documentation than to translate it into another language. You have all the difficulties of translation, plus you're working under a handicap of only using some (ill-defined?) subset of English. Wikipedia offers some evidence supporting my view: - the main English Wikipedia has 5 million articles, written by nearly 140K active users; - the Swedish Wikipedia is almost as big, 3M articles from only 3K active users; - but the Simple English Wikipedia has just 123K articles and 871 active users. That's fewer articles than Esperanto! https://meta.wikimedia.org/wiki/List_of_Wikipedias Nevertheless, I certainly wouldn't object if people wanted to try writing Simple English translations of the docs. But I don't think they would be as useful as translations into non-English. [...]
For any language you want to support other than English, you need a translator who is A: a python expert, B: fluent in English, and C: fluent in the target language.
I disagree. You need a translator who is A: skilled at technical documentation, with B and C as above. They don't need to be a Python expert. We have plenty of Python experts that they can consult with and ask questions. But they need to know the right questions to ask: "Python attributes, they're kind of like C members, right? I would translate 'member' into Klingon as 'gham', which means 'arm or leg', so I can use the same word for attribute."
…And then you need another one to check what was written. These are practical problems. There are extant services to support this, they are expensive in either money or time, and the docs produced usually lag behind English quite a bit.
Is this a good use for some PSF funding? Would companies be willing to invest money in translating Python documentation? Just because we're Open Source, doesn't mean that everything we do has to be purely volunteer. -- Steve
On 2017-02-24 15:10, Steven D'Aprano wrote:
On Fri, Feb 24, 2017 at 06:01:59AM -0500, tritium-list@sdamon.com wrote:
My gut splits the difference on this issue; I suggest an approach to meet in the middle – a version of the docs written in simplified English (Not quite Up Goer Five simplified, but simplified.)
As an English speaker, my gut tells me that it would be much harder to write *accurate* simplified English technical documentation than to translate it into another language.
You have all the difficulties of translation, plus you're working under a handicap of only using some (ill-defined?) subset of English.
Wikipedia offers some evidence supporting my view:
- the main English Wikipedia has 5 million articles, written by nearly 140K active users;
- the Swedish Wikipedia is almost as big, 3M articles from only 3K active users;
- but the Simple English Wikipedia has just 123K articles and 871 active users. That's fewer articles than Esperanto!
https://meta.wikimedia.org/wiki/List_of_Wikipedias
Nevertheless, I certainly wouldn't object if people wanted to try writing Simple English translations of the docs. But I don't think they would be as useful as translations into non-English.
[snip] Would it be easier to make a translation into Esperanto, which is meant to be easier to learn than English?
On 25 February 2017 at 04:54, MRAB <python@mrabarnett.plus.com> wrote:
On 2017-02-24 15:10, Steven D'Aprano wrote:
Nevertheless, I certainly wouldn't object if people wanted to try writing Simple English translations of the docs. But I don't think they would be as useful as translations into non-English.
[snip]
Would it be easier to make a translation into Esperanto, which is meant to be easier to learn than English?
Not really, as there are two main criteria for building a successful translation community: - potential audience for the translation (i.e. native speakers of the target language) - an interested pool of bilingual speakers to do the translation Those numbers are far more favourable for native language translations to widely spoken languages like Japanese, Mandarin Chinese, Spanish, and French than they are for Esperanto. When it comes to the idea of creating a Simple English translation of the standard tutorial, my experience is that what folks are more inclined to do on that front is to just write a new tutorial of their own specifically targeting the audience they care about, rather than translating the standard one. That provides a lot more freedom to not only adjust the specific words used, but also decide when and how to introduce different concepts based on their particular target audience (e.g. teaching Python to a group of mid-career scientific researchers or a group of professional engineers is very different from teaching it to a classroom full of 6 year olds, or students pursuing a computing degree at university, which in turn are very different from teaching groups of interested people that have designed to sacrifice their own time to attend a community run introduction to programming workshop). Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On 25 February 2017 at 01:10, Steven D'Aprano <steve@pearwood.info> wrote:
On Fri, Feb 24, 2017 at 06:01:59AM -0500, tritium-list@sdamon.com wrote:
…And then you need another one to check what was written. These are practical problems. There are extant services to support this, they are expensive in either money or time, and the docs produced usually lag behind English quite a bit.
Is this a good use for some PSF funding? Would companies be willing to invest money in translating Python documentation?
Translated documentation is certainly one of the things commercial open source users appreciate, and hence redistributors are willing to fund in the general case (see https://access.redhat.com/documentation/ja/red-hat-enterprise-linux/ or https://docs.openstack.org/ja/ for example) For the specific case of the PSF, credible development grant ideas are always worth considering (as those are an excellent way for the PSF to help enable community activities).
Just because we're Open Source, doesn't mean that everything we do has to be purely volunteer.
Right, but this kind of problem is also one of the major reasons I tend to harp on about the fact that the commercial redistributors active in the Python community aren't contributing as effectively as they could be, and their existing customers aren't holding them accountable for the failure. Python's origins as a "scripting language for Linux" means it is often still perceived that way in the commercial sector and treated accordingly, even though it has subsequently matured into a full-fledged cross-platform application development and data analysis platform. Even those of us already working for redistributors can't readily provide that missing accountability, as any reasonable business is going to weigh the costs of additional investment in any given area against the potential for increased future revenue. That means the most effective pressure comes from industry partners, governments, existing customers, and credible potential customers (i.e. folks that have the ability to affect redistributor revenue directly) rather than from redistributor staff or community volunteers (as we're pretty much limited to using risk management and hiring pipeline based lines of argument, rather than being able to push the "future revenue potential" line directly). Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
2017-02-24 16:10 GMT+01:00 Steven D'Aprano <steve@pearwood.info>:
…And then you need another one to check what was written. These are practical problems. There are extant services to support this, they are expensive in either money or time, and the docs produced usually lag behind English quite a bit.
Is this a good use for some PSF funding? Would companies be willing to invest money in translating Python documentation?
Just because we're Open Source, doesn't mean that everything we do has to be purely volunteer.
IHMO translating the *whole* Python documentation at once by a professional translator can be very expensive, no somthing that the PSF would affort. Which language would you pick? Depending on what? We already have motivated translators for free who only ask us for the permission to make tiny changes to make their life simpler and make the doc more visible. I'm in favor of allowing them to translate and make the translated doc official ;-) IMHO a better usage of the PSF funding would be to organize some local sprints to translate the Python documentation. Such sprints are fun, cheap, and can be a nice opportunity to recruit free and motivated translators. We are looking for people involved to translate the doc the doc is updated, not only translate the doc once and go away. Right? Victor
I support having an official translated doc. I have seen several groups trying to translate part of our official doc. But their efforts are disperse and quickly become lost because they are not organized to work towards a single common result and their results are hold anywhere on the Web and hard to find. An official one could help ease the pain. But I agree we may need more details on the workflow. At 2017-02-27 19:04:21, "Victor Stinner" <victor.stinner@gmail.com> wrote:
2017-02-24 16:10 GMT+01:00 Steven D'Aprano <steve@pearwood.info>:
…And then you need another one to check what was written. These are practical problems. There are extant services to support this, they are expensive in either money or time, and the docs produced usually lag behind English quite a bit.
Is this a good use for some PSF funding? Would companies be willing to invest money in translating Python documentation?
Just because we're Open Source, doesn't mean that everything we do has to be purely volunteer.
IHMO translating the *whole* Python documentation at once by a professional translator can be very expensive, no somthing that the PSF would affort. Which language would you pick? Depending on what?
We already have motivated translators for free who only ask us for the permission to make tiny changes to make their life simpler and make the doc more visible. I'm in favor of allowing them to translate and make the translated doc official ;-)
IMHO a better usage of the PSF funding would be to organize some local sprints to translate the Python documentation. Such sprints are fun, cheap, and can be a nice opportunity to recruit free and motivated translators. We are looking for people involved to translate the doc the doc is updated, not only translate the doc once and go away. Right?
Victor
I've recently been translating the Tutorial in Greek as a side thing that also helps me catch some doc bugs :-). So it's an obvious +1 from me. I really like this idea and would like to see it come to fruition. I think some issues need to be addressed first, though: Where should these translated docs live and how does one make it clear to users reading them that doc bugs shouldn't be submitted to the main bug tracker/github repo? these are just two that popped in my head. It would be great if this went forward, many people will find the path to learning Python much much easier to walk if the documentation was written in a language they are comfortable in. Best Regards, Jim Fasarakis Hilliard *d.f.hilliard@gmail.com <d.f.hilliard@gmail.com> | dimitrisjim.github.io <http://dimitrisjim.github.io>* <https://gr.linkedin.com/pub/jim-fasarakis-hilliard/87/794/b18> <http://stackoverflow.com/users/4952130/dimitris-jim?tab=profile> <https://github.com/DimitrisJim> <https://twitter.com/Dimitris__Jim> <https://plus.google.com/112215906824777598051/> <https://www.facebook.com/dimitristzim> <https://hub.docker.com/u/dimitrisjim/> On Fri, Feb 24, 2017 at 12:02 PM, Nick Coghlan <ncoghlan@gmail.com> wrote:
On 23 February 2017 at 02:15, Victor Stinner <victor.stinner@gmail.com> wrote:
2017-02-22 16:40 GMT+01:00 Antoine Pitrou <solipsis@pitrou.net>:
As long as you are asking for "moral" support and not actually vouching for the accuracy of third-party translations, then +1 from me.
The main complain about these translations is the accuracy.
My bet is that making these translations "official" and more visible (at docs.python.org) would make them more popular, and so indirectly help to recruit new contributors. Slowly, the number of translated pages should increase, but the overall translation quality should also increase. That's how free software are developed, no? :-)
+1 from me for these reasons, and those Facundo gives: we want folks to be able to learn at least the basics of Python *before* they learn English (even if learning English remains a pre-requisite for tapping into the full capabilities of both the language and its ecosystem).
Cheers, Nick.
-- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/d. f.hilliard%40gmail.com
On Wed, Feb 22, 2017 at 9:10 AM, Victor Stinner <victor.stinner@gmail.com> wrote:
There are a least 3 groups of people who are translating the Python documentation in their mother language (french, japanese, spanish).
We translated (and even printed/published) the Tutorial (we're currently maintaining the Py2 and Py3 branches). But only the tutorial, that is a smaller and steadier doc.
For me, the most impotant point would be to give access to the translated documentation from docs.python.org. For example, have a dropdown list with available languages.
To clarify: you're proposing to *serve* the translated files from d.p.o? Or just a link to where those are served now? Thanks! -- . Facundo Blog: http://www.taniquetil.com.ar/plog/ PyAr: http://www.python.org/ar/ Twitter: @facundobatista
participants (17)
-
Antoine Pitrou -
Berker Peksağ -
Brett Cannon -
David Mertz -
Facundo Batista -
INADA Naoki -
Jim F.Hilliard -
MRAB -
Ned Deily -
Nick Coghlan -
Rob Cliffe -
Serhiy Storchaka -
Steven D'Aprano -
Tres Seaver -
tritium-list＠sdamon.com -
Victor Stinner -
Xiang Zhang