From fromwheretowhere.service at gmail.com Sun Apr 15 14:45:08 2018 From: fromwheretowhere.service at gmail.com (Xuan Wu) Date: Sun, 15 Apr 2018 11:45:08 -0700 Subject: [Doc-SIG] Translating sample programs in documentation Message-ID: I posted this to python-dev list but I suppose here is better place. Excuse me if this was discussed before, but in French and Japanese translations, all the sample programs seem to have identifiers in English still. According to "PEP 545 -- Python Documentation Translations", as I understand .po files are used for translations. May I ask if there are technical restrictions causing translations being only applied to the text parts? For example, here's the first sample program in 4.2: >>># Measure some strings: ... words = ['cat', 'window', 'defenestrate'] >>>for w in words: ... print(w, len(w)) ... cat 3 window 6 defenestrate 12 Here's a possible translation in Chinese: >>> # ??????? ... ?? = ['?', '??', '????'] >>> for ? in ??: ... print(?, len(?)) ... ? 1 ?? 2 ???? 4 As you may notice the strings differ in size if they are translated directly. Obviously that does add extra burden to review the new sample programs to assure effectiveness and readability. Any suggestion or comments are welcome. Thanks, Xuan. -------------- next part -------------- An HTML attachment was scrubbed... URL: From julien at palard.fr Sun Apr 15 15:58:15 2018 From: julien at palard.fr (Julien Palard) Date: Sun, 15 Apr 2018 15:58:15 -0400 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: References: Message-ID: Hi Xuan, > Excuse me if this was discussed before, but in French and Japanese translations, all the sample programs seem to have identifiers in English still. According to "PEP 545 -- Python Documentation Translations", as I understand .po files are used for translations. May I ask if there are technical restrictions causing translations being only applied to the text parts? Our current sphinx-docs configuration (default about this matter) is not to provide those blocs in the po files. (It's the `gettext_additional_targets entry).` My point of view is we should not translate them, as we dont want to see ` ``for ? in ??:` pushed by anyone (I mean : we're writing code in english, even if the doc is translated we *still* have to write the code in english). Also, we have enough work translating the text, we don't need more. In the other hand I personally use translated variable names when I teach Python to newcomers, because it helps them to distinguish between "what they can change" and "what they can't", seeing "for ? in ??:" make it clear that "for", "in". and ":" are from Python and "?" and "??" are from the teacher, but when I do, I mention it, I make it clear I won't accept it in their code, so if we do translate the variables names, I think we should do it only in the tutoriel (Meaning we should be clear to all translators which code should be translated, which should not, this is already hard), and we should explain why it's translated here and not elsewhere to the readers. Also, we could imagine a legitimate translation, (keep comments and variable names in english, but manipulate translated data): ??? >>> # Measure some strings: ??? ... words = ['?', '??', '????'] ??? >>> for word in words: ??? ...???? print(word, len(word)) ??? ... ??? ? 1 ??? ?? 2 ??? ???? 4 But does it really worth it? I don't think so. ?--? Julien Palard https://mdk.fr? From fromwheretowhere.service at gmail.com Sun Apr 15 17:56:04 2018 From: fromwheretowhere.service at gmail.com (Xuan Wu) Date: Sun, 15 Apr 2018 14:56:04 -0700 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: References: Message-ID: Hi Julien, thanks for the information. > Our current sphinx-docs configuration (default about this matter) is not to provide those blocs in the po files. (It's the `gettext_additional_targets entry).` If I understand correctly, that makes it technically impossible to achieve what I described, unless we change the sphinx-docs configuration? > My point of view is we should not translate them, as we dont want to see ` ``for ? in ??:` pushed by anyone (I mean : we're writing code in english, even if the doc is translated we *still* have to write the code in english). Also, we have enough work translating the text, we don't need more. I've heard of similar comments from many other Chinese developers as well. Actually I wasn't 100% sure about the benefit of this practice until I read the rationale part of "PEP 3131 -- Supporting Non-ASCII Identifiers ": " By using identifiers in their native language, code clarity and maintainability of the code among speakers of that language improves." > In the other hand I personally use translated variable names when I teach Python to newcomers, because it helps them to distinguish between "what they can change" and "what they can't", seeing "for ? in ??:" make it clear that "for", "in". and ":" are from Python and "?" and "??" are from the teacher, I agree that makes it more understandable to beginners. > so if we do translate the variables names, I think we should do it only in the tutoriel (Meaning we should be clear to all translators which code should be translated, which should not, this is already hard), and we should explain why it's translated here and not elsewhere to the readers. I agree the boundary will be hard to define, and I've no issue starting the practice in the tutorial. I see some complexity in the additional code style that's specific to a language. In the given example, because there's no plural form as English in Chinese, I need to use '??', which is similar in meaning to 'word list'. Also, as there's no upper/lower case in Chinese, that might also make some difference. > Also, we could imagine a legitimate translation, (keep comments and variable names in english, but manipulate translated data): IMO comments are good targets for translation, as I heard many developers write comments in native languages. Above said, I totally agree this practice means much more work when translating, not to mention the potential controversies even among Chinese developers. Still, I'd look forward to trying the idea out somewhere proper. Thanks again, Xuan. -------------- next part -------------- An HTML attachment was scrubbed... URL: From julien at palard.fr Mon Apr 16 01:56:28 2018 From: julien at palard.fr (Julien Palard) Date: Mon, 16 Apr 2018 01:56:28 -0400 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: References: Message-ID: Hi Xuan, > > Our current sphinx-docs configuration (default about this matter) is not to provide those blocs in the po files. (It's the `gettext_additional_targets entry).` > > If I understand correctly, that makes it technically impossible to achieve what I described, unless we change the sphinx-docs configuration? Yes, until we change the cpython sphinx-docs configuration in `Doc/conf.py`. > Above said, I totally agree this practice means much more work when translating, not to mention the potential controversies even among Chinese developers. Still, I'd look forward to trying the idea out somewhere proper. I think we can resume this thread when ~6 translations have reach ~99% translated (is there a currently living translation of the doc in chinese? Heard of https://github.com/python-doc-tw/python-doc-tw for zh-tw and heard of some work on transifex for zh-cn (1.4% translated as of fall 2017). ?--? Julien Palard https://mdk.fr? From fromwheretowhere.service at gmail.com Mon Apr 16 05:06:12 2018 From: fromwheretowhere.service at gmail.com (Xuan Wu) Date: Mon, 16 Apr 2018 02:06:12 -0700 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: References: Message-ID: <0bf5e3c8-e7ea-8e81-caac-81133dbaece2@gmail.com> Hi Julien, >>> Our current sphinx-docs configuration (default about this matter) is not to provide those blocs in the po files. (It's the `gettext_additional_targets entry).` >> If I understand correctly, that makes it technically impossible to achieve what I described, unless we change the sphinx-docs configuration? > Yes, until we change the cpython sphinx-docs configuration in `Doc/conf.py`. Thanks I'll see how to change that. > >> Above said, I totally agree this practice means much more work when translating, not to mention the potential controversies even among Chinese developers. Still, I'd look forward to trying the idea out somewhere proper. > I think we can resume this thread when ~6 translations have reach ~99% translated (is there a currently living translation of the doc in chinese? Heard of https://github.com/python-doc-tw/python-doc-tw for zh-tw and heard of some work on transifex for zh-cn (1.4% translated as of fall 2017). Frankly, I don't see the relevance between the progress of translation and whether this discussion can be continued. The ability to translate elements in sample programs would certainly give me more motivation to contribute. Best wishes, Xuan. From songofacandy at gmail.com Mon Apr 16 06:28:09 2018 From: songofacandy at gmail.com (INADA Naoki) Date: Mon, 16 Apr 2018 19:28:09 +0900 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: <0bf5e3c8-e7ea-8e81-caac-81133dbaece2@gmail.com> References: <0bf5e3c8-e7ea-8e81-caac-81133dbaece2@gmail.com> Message-ID: > > Frankly, I don't see the relevance between the progress of translation and > whether this discussion can be continued. The ability to translate elements > in sample programs would certainly give me more motivation to contribute. > Personally speaking, I'm strong -1 on translating code, especially for identifiers. (weak -1 on comments and docstring, strong -1 on identifiers). In Japan, many Pythonista doesn't use Japanese identifiers regulally. There are many "looks similar, but different" characters in Japanese. So ASCII is more readable than Japanese Hanji. I don't know about Chinese practice, but how popular Chinese identifiers are? If you're participating large Chinese community, could you try survey about it there? At least, I think Chinese translation team's agreement is needed before trying it. Regards, -- INADA Naoki From fromwheretowhere.service at gmail.com Mon Apr 16 13:27:23 2018 From: fromwheretowhere.service at gmail.com (Xuan Wu) Date: Mon, 16 Apr 2018 10:27:23 -0700 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: References: <0bf5e3c8-e7ea-8e81-caac-81133dbaece2@gmail.com> Message-ID: Thanks for the feedback. A couple of months ago, I heard from one experienced Japanese developer that he thought Japanese naming for variables and functions are easy to read and write in his practice. He also mentioned that many others don't like the practice. Similarly in Chinese developer community, more developers dislike Chinese naming, even though IMO this opposition is not well-grounded in most cases. Additionally and pitifully, quite some developers, especially beginners, don't even know they can use unicode naming in Python (or any programming languages) and it may result in better readability. From my own experience with some projects in Java/JavaScript, Chinese naming is more readable even for myself, who have programmed in English-speaking environment for many years. Also, I know there are beginners in China who would love to have tutorials that contain sample programs with Chinese naming, based on the discussions in the github organization I created for programming in Chinese language. IMO it's almost impossible to verify if this practice is generally better for beginners or not, without actually trying it out in limited scope, like the official tutorial. To clarify, I'm not pushing other languages to do the same. Best wishes, Xuan. On 4/16/18 3:28 AM, INADA Naoki wrote: >> Frankly, I don't see the relevance between the progress of translation and >> whether this discussion can be continued. The ability to translate elements >> in sample programs would certainly give me more motivation to contribute. >> > Personally speaking, I'm strong -1 on translating code, especially for > identifiers. > (weak -1 on comments and docstring, strong -1 on identifiers). > > In Japan, many Pythonista doesn't use Japanese identifiers regulally. > There are many "looks similar, but different" characters in Japanese. > So ASCII is more readable than Japanese Hanji. > > I don't know about Chinese practice, but how popular Chinese identifiers are? > If you're participating large Chinese community, could you try survey > about it there? > > At least, I think Chinese translation team's agreement is needed > before trying it. > > Regards, From ncoghlan at gmail.com Tue Apr 17 05:56:42 2018 From: ncoghlan at gmail.com (Nick Coghlan) Date: Tue, 17 Apr 2018 19:56:42 +1000 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: References: <0bf5e3c8-e7ea-8e81-caac-81133dbaece2@gmail.com> Message-ID: On 17 April 2018 at 03:27, Xuan Wu wrote: > IMO it's almost impossible to verify if this practice is generally better > for beginners or not, without actually trying it out in limited scope, like > the official tutorial. > > To clarify, I'm not pushing other languages to do the same. While I'm hesitant to suggest this (since I'm not sure how much extra work it would be, or if it's even practical at all), would it be feasible to provide two different variants of the Chinese tutorial translation, one that keeps the original "online open source collaboration defaults to English for historical reasons" examples, and another that also translates the code comments, variable names, and string content in the examples? One of the strengths of Python as a programming language is that it not only enables sharing between programmers around the world, but also between Python programmers and experts in other domains. So even beyond the question of which is easier to learn, if someone is preparing something like a Jupyter notebook, and their primary audience is folks that don't speak English as their preferred language, then it may make sense to use as many native terms as possible, and only use English for the Python keywords. A fully translated tutorial (examples and all) helps make that capability clearer for everyone, not only beginners. Cheers, Nick. -- Nick Coghlan | ncoghlan at gmail.com | Brisbane, Australia From fromwheretowhere.service at gmail.com Tue Apr 17 14:07:23 2018 From: fromwheretowhere.service at gmail.com (Xuan Wu) Date: Tue, 17 Apr 2018 11:07:23 -0700 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: References: <0bf5e3c8-e7ea-8e81-caac-81133dbaece2@gmail.com> Message-ID: <5d6ca990-8b93-b063-4bce-b407d4d7a7d3@gmail.com> Hi Nick, > While I'm hesitant to suggest this (since I'm not sure how much extra > work it would be, or if it's even practical at all), would it be > feasible to provide two different variants of the Chinese tutorial > translation, one that keeps the original "online open source > collaboration defaults to English for historical reasons" examples, > and another that also translates the code comments, variable names, > and string content in the examples? Thanks for the suggestion. There might be some devil in the details, like how to name the repositories. According to PEP 545 IETF Language Tag is used for each language. If two versions are kept, there may need some extra tag for each. Another alternative would be an additional language switcher in the UI of documentation page for programs only, but surely that's extra work and may make UI cumbersome. Not to mention the question of which version is set as default in the switcher. IMHO those who prefer to read original sample programs usually have fluency in English to read the original version of the tutorial. Nonetheless, as a workaround, they can still open another tab in the browser to have the English version on the side. So it seems to me can be deferred till there's a clear requirement for it. > > One of the strengths of Python as a programming language is that it > not only enables sharing between programmers around the world, but > also between Python programmers and experts in other domains. So even > beyond the question of which is easier to learn, if someone is > preparing something like a Jupyter notebook, and their primary > audience is folks that don't speak English as their preferred > language, then it may make sense to use as many native terms as > possible, and only use English for the Python keywords. A fully > translated tutorial (examples and all) helps make that capability > clearer for everyone, not only beginners. I can't agree more. In my view it'll be good advocate for using identifiers in native languages, which PEP 3131 initially designed for. Thanks, Xuan. From julien at palard.fr Wed Apr 18 03:06:45 2018 From: julien at palard.fr (Julien Palard) Date: Wed, 18 Apr 2018 03:06:45 -0400 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: <5d6ca990-8b93-b063-4bce-b407d4d7a7d3@gmail.com> References: <0bf5e3c8-e7ea-8e81-caac-81133dbaece2@gmail.com> <5d6ca990-8b93-b063-4bce-b407d4d7a7d3@gmail.com> Message-ID: <9kF9El9jhCM34vo-eJ-2qOg5UtiCpIlPTlpQnhfxzPkEvfpzDBEH-qWQpXujBr-_thdhebCKFC_BdqdkOpnJ0EjeNy54dZ4OMmmonEnZWbI=@palard.fr> Hi, > There might be some devil in the details, > like how to name the repositories. According to PEP 545 IETF Language > Tag is used for each language. If two versions are kept, there may need > some extra tag for each. Another alternative would be an additional > language switcher in the UI of documentation page for programs only, but > surely that's extra work and may make UI cumbersome. What about a switche per code block like the current ">>>" (top right of code blocs) "show the prompt and outputs"/"hide the prompt and outputs"? ?--? Julien Palard https://mdk.fr? From fromwheretowhere.service at gmail.com Wed Apr 18 05:23:41 2018 From: fromwheretowhere.service at gmail.com (Xuan Wu) Date: Wed, 18 Apr 2018 02:23:41 -0700 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: <9kF9El9jhCM34vo-eJ-2qOg5UtiCpIlPTlpQnhfxzPkEvfpzDBEH-qWQpXujBr-_thdhebCKFC_BdqdkOpnJ0EjeNy54dZ4OMmmonEnZWbI=@palard.fr> References: <0bf5e3c8-e7ea-8e81-caac-81133dbaece2@gmail.com> <5d6ca990-8b93-b063-4bce-b407d4d7a7d3@gmail.com> <9kF9El9jhCM34vo-eJ-2qOg5UtiCpIlPTlpQnhfxzPkEvfpzDBEH-qWQpXujBr-_thdhebCKFC_BdqdkOpnJ0EjeNy54dZ4OMmmonEnZWbI=@palard.fr> Message-ID: <61a788cd-39a6-edc5-ed30-b3b31c3a898b@gmail.com> Hi Julien, thanks I agree that's another option. Still IMHO there's not yet clear requirement about this yet. As I imagine some users might prefer the 'global' switcher while some others might prefer the 'local' one as you suggested. Could we show the translated programs by default first, and then improve potential usability after gathering more feedback? Best regards, Xuan. On 4/18/18 12:06 AM, Julien Palard wrote: > Hi, > >> There might be some devil in the details, >> like how to name the repositories. According to PEP 545 IETF Language >> Tag is used for each language. If two versions are kept, there may need >> some extra tag for each. Another alternative would be an additional >> language switcher in the UI of documentation page for programs only, but >> surely that's extra work and may make UI cumbersome. > What about a switche per code block like the current ">>>" (top right of code blocs) "show the prompt and outputs"/"hide the prompt and outputs"? > > ?-- > Julien Palard > https://mdk.fr? > > From ncoghlan at gmail.com Wed Apr 18 05:43:10 2018 From: ncoghlan at gmail.com (Nick Coghlan) Date: Wed, 18 Apr 2018 19:43:10 +1000 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: <61a788cd-39a6-edc5-ed30-b3b31c3a898b@gmail.com> References: <0bf5e3c8-e7ea-8e81-caac-81133dbaece2@gmail.com> <5d6ca990-8b93-b063-4bce-b407d4d7a7d3@gmail.com> <9kF9El9jhCM34vo-eJ-2qOg5UtiCpIlPTlpQnhfxzPkEvfpzDBEH-qWQpXujBr-_thdhebCKFC_BdqdkOpnJ0EjeNy54dZ4OMmmonEnZWbI=@palard.fr> <61a788cd-39a6-edc5-ed30-b3b31c3a898b@gmail.com> Message-ID: On 18 April 2018 at 19:23, Xuan Wu wrote: > Hi Julien, > > thanks I agree that's another option. Still IMHO there's not yet clear > requirement about this yet. As I imagine some users might prefer the > 'global' switcher while some others might prefer the 'local' one as you > suggested. Could we show the translated programs by default first, and then > improve potential usability after gathering more feedback? If the translation of the examples in the tutorial can be handled by the docs build process, then making this a per-translation policy decision does sound like it would be the simplest near term approach. As Xuan notes, if folks following a translation with translated examples also want to look at the English language examples, they'll always be able to switch back to the English translation of the tutorial. Cheers, Nick. -- Nick Coghlan | ncoghlan at gmail.com | Brisbane, Australia From songofacandy at gmail.com Wed Apr 18 06:06:46 2018 From: songofacandy at gmail.com (INADA Naoki) Date: Wed, 18 Apr 2018 19:06:46 +0900 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: References: <0bf5e3c8-e7ea-8e81-caac-81133dbaece2@gmail.com> Message-ID: > IMO it's almost impossible to verify if this practice is generally better for beginners or not, without actually trying it out in limited scope, like the official tutorial. > > To clarify, I'm not pushing other languages to do the same. > How about starting it other than docs.python.org, as your personal project? There is no option for "exporting code only for these files" option in Sphinx currently. And if we include example codes in message files, all languages are affected, at least on the Transifex. I feel your motivation is just you want to promote non-ASCII identifier. And I think the cost required to do it on the docs.python.org is too much. But trying it on other site must be much easier. If you demonstrates benefits of non-ASCII identifier and Chinese translation team really want it on the docs.python.org, I'm pleasure to think about it. But as far as it's just your personal preference, I don't want to push example codes to Transifex. Regards, -- INADA Naoki From fromwheretowhere.service at gmail.com Wed Apr 18 06:54:23 2018 From: fromwheretowhere.service at gmail.com (Xuan Wu) Date: Wed, 18 Apr 2018 03:54:23 -0700 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: References: <0bf5e3c8-e7ea-8e81-caac-81133dbaece2@gmail.com> Message-ID: <11f8518e-0aef-1728-bf73-9f6571b4d93c@gmail.com> If example codes are included in message files, what will happen if one locale chooses not to translate them? If they will just show as original codes, I don't see problem there. I imagine part of the extra work is to convert existing PO files to new ones. Please correct me if I'm wrong, but over top of my head it's achievable by some script. Instead of just my personal preference, benefits of using identifiers in native languages seem to have been proven long time ago, as stated in the rationale part of PEP 3131. Pitifully I've not seen any active member from Chinese translation team here yet. Thanks, Xuan. On 4/18/18 3:06 AM, INADA Naoki wrote: >> IMO it's almost impossible to verify if this practice is generally better for beginners or not, without actually trying it out in limited scope, like the official tutorial. >> >> To clarify, I'm not pushing other languages to do the same. >> > How about starting it other than docs.python.org, as your personal project? > > There is no option for "exporting code only for these files" option in > Sphinx currently. > And if we include example codes in message files, all languages are > affected, at least on the Transifex. > > I feel your motivation is just you want to promote non-ASCII identifier. > And I think the cost required to do it on the docs.python.org is too much. > But trying it on other site must be much easier. > > If you demonstrates benefits of non-ASCII identifier and Chinese translation > team really want it on the docs.python.org, I'm pleasure to think about it. > > But as far as it's just your personal preference, I don't want to push > example codes to Transifex. > > Regards, > From songofacandy at gmail.com Wed Apr 18 07:18:59 2018 From: songofacandy at gmail.com (INADA Naoki) Date: Wed, 18 Apr 2018 20:18:59 +0900 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: <11f8518e-0aef-1728-bf73-9f6571b4d93c@gmail.com> References: <0bf5e3c8-e7ea-8e81-caac-81133dbaece2@gmail.com> <11f8518e-0aef-1728-bf73-9f6571b4d93c@gmail.com> Message-ID: On Wed, Apr 18, 2018 at 7:54 PM, Xuan Wu wrote: > If example codes are included in message files, what will happen if one > locale chooses not to translate them? If they will just show as original > codes, I don't see problem there. I imagine part of the extra work is to > convert existing PO files to new ones. Please correct me if I'm wrong, but > over top of my head it's achievable by some script. > It's difficult to distinguish example code and others on Transifex. We're targeting 100% translation on Transifex, but it's impossible if example codes are included and Japanese team doesn't translate it. > Instead of just my personal preference, benefits of using identifiers in > native languages seem to have been proven long time ago, as stated in the > rationale part of PEP 3131. I think "enabling" to do it and "encouraging" to do it have different bar. So I don't agree PEP 3131 is enough reason to do it. > Pitifully I've not seen any active member from > Chinese translation team here yet. > There is no official team yet, but there is zh_CN team on the Transifex. See https://www.transifex.com/python-doc/teams/5390/zh_CN/ I think there is an active community because there are many Python developers in China. Please build active language team there. Without official language team, we won't add Chinese translation to docs.python.org. Regards, From fromwheretowhere.service at gmail.com Wed Apr 18 12:36:20 2018 From: fromwheretowhere.service at gmail.com (Xuan Wu) Date: Wed, 18 Apr 2018 09:36:20 -0700 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: References: <0bf5e3c8-e7ea-8e81-caac-81133dbaece2@gmail.com> <11f8518e-0aef-1728-bf73-9f6571b4d93c@gmail.com> Message-ID: <68ff3cd6-8fa9-ca7a-0a81-880f7ad04c34@gmail.com> > It's difficult to distinguish example code and others on Transifex. > > We're targeting 100% translation on Transifex, but it's impossible if > example codes are included and Japanese team doesn't translate it. How about including example codes in PO files only when a language team asks to? So by default, PO files won't change for locales who prefer to use original code, thus your percentage wouldn't be affected. >> Instead of just my personal preference, benefits of using identifiers in >> native languages seem to have been proven long time ago, as stated in the >> rationale part of PEP 3131. > I think "enabling" to do it and "encouraging" to do it have different bar. > So I don't agree PEP 3131 is enough reason to do it. I'd rather not start a debate about whether the benefits are big enough to 'encourage' the practice rather than just 'enabling' it, because it depends on too many factors like language differences and personal experiences. Similar to PEP 3131, here I'm just asking to support such practice when translating official documentation, but certainly not enforcing it. IMO this feature would be potentially beneficial for other languages too. > > >> Pitifully I've not seen any active member from >> Chinese translation team here yet. >> > There is no official team yet, but there is zh_CN team on the Transifex. > See https://www.transifex.com/python-doc/teams/5390/zh_CN/ > > I think there is an active community because there are > many Python developers in China. > Please build active language team there. Without official language team, > we won't add Chinese translation to docs.python.org. I wonder what's difference between the official team and zh_CN team on Transifex? I'd like to see if I could help building the official one. Thanks, Xuan. From songofacandy at gmail.com Wed Apr 18 13:20:23 2018 From: songofacandy at gmail.com (INADA Naoki) Date: Thu, 19 Apr 2018 02:20:23 +0900 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: <68ff3cd6-8fa9-ca7a-0a81-880f7ad04c34@gmail.com> References: <0bf5e3c8-e7ea-8e81-caac-81133dbaece2@gmail.com> <11f8518e-0aef-1728-bf73-9f6571b4d93c@gmail.com> <68ff3cd6-8fa9-ca7a-0a81-880f7ad04c34@gmail.com> Message-ID: On Thu, Apr 19, 2018 at 1:36 AM, Xuan Wu wrote: > >> It's difficult to distinguish example code and others on Transifex. >> >> We're targeting 100% translation on Transifex, but it's impossible if >> example codes are included and Japanese team doesn't translate it. > > > How about including example codes in PO files only when a language team asks > to? So by default, PO files won't change for locales who prefer to use > original code, thus your percentage wouldn't be affected. Haven't you contributed translation on Transifex? We translate from one source language (English, of course) to multiple target languages. All target languages shares one source message catalog. It's difficult to upload special message catalog only for Chinese. Of course, you can create yor own project on Transifex and upload message catalog you created, which includes example code. >>> >>> Instead of just my personal preference, benefits of using identifiers in >>> native languages seem to have been proven long time ago, as stated in the >>> rationale part of PEP 3131. >> >> I think "enabling" to do it and "encouraging" to do it have different bar. >> So I don't agree PEP 3131 is enough reason to do it. > > > I'd rather not start a debate about whether the benefits are big enough to > 'encourage' the practice rather than just 'enabling' it, because it depends > on too many factors like language differences and personal experiences. > Similar to PEP 3131, here I'm just asking to support such practice when > translating official documentation, but certainly not enforcing it. IMO this > feature would be potentially beneficial for other languages too. If support it for Chinese and you translate it, all Chinese readers are affected. But the document should be maintained by sustainable team, not only you. That's why I want team's conclusion before trying it on docs.python.org. On the other hand, if you upload translated document to another domain, you can try anything you want. Additionally, it requires much effort of us. I don't want to pay my effort only for trying idea of just one person. That's main reason I recommend you to try it on site other than docs.python.org. >>> Pitifully I've not seen any active member from >>> Chinese translation team here yet. >>> >> There is no official team yet, but there is zh_CN team on the Transifex. >> See https://www.transifex.com/python-doc/teams/5390/zh_CN/ >> >> I think there is an active community because there are >> many Python developers in China. >> Please build active language team there. Without official language team, >> we won't add Chinese translation to docs.python.org. > > > I wonder what's difference between the official team and zh_CN team on > Transifex? I'd like to see if I could help building the official one. > The Transifex project is used only for Japanese. It is maintained by me and @cocoatomo. It is not official project of PSF or doc-sig yet. Some day, people want to use the project for translating document to their language. I accepted them. It happened before PEP 545. So there are no strict relation between the Transifex project and docs.python.org. You can use the Transifex project, or create another project on Transifex, or you can even create another project on other translation tools. To build official language team, you meed to read PEP 545. https://www.python.org/dev/peps/pep-0545/ If you succeeded to built team in China and you want to use our Transifex project, I'll assign the coordinator role to the coordinator of Chinese team. Bests, -- INADA Naoki From fromwheretowhere.service at gmail.com Wed Apr 18 14:42:04 2018 From: fromwheretowhere.service at gmail.com (Xuan Wu) Date: Wed, 18 Apr 2018 11:42:04 -0700 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: References: <0bf5e3c8-e7ea-8e81-caac-81133dbaece2@gmail.com> <11f8518e-0aef-1728-bf73-9f6571b4d93c@gmail.com> <68ff3cd6-8fa9-ca7a-0a81-880f7ad04c34@gmail.com> Message-ID: <9f776fa6-e9d6-d41d-3eee-1b18d26bde01@gmail.com> Hi, > > >>>> Instead of just my personal preference, benefits of using identifiers in >>>> native languages seem to have been proven long time ago, as stated in the >>>> rationale part of PEP 3131. >>> I think "enabling" to do it and "encouraging" to do it have different bar. >>> So I don't agree PEP 3131 is enough reason to do it. >> >> I'd rather not start a debate about whether the benefits are big enough to >> 'encourage' the practice rather than just 'enabling' it, because it depends >> on too many factors like language differences and personal experiences. >> Similar to PEP 3131, here I'm just asking to support such practice when >> translating official documentation, but certainly not enforcing it. IMO this >> feature would be potentially beneficial for other languages too. > If support it for Chinese and you translate it, all Chinese readers > are affected. > But the document should be maintained by sustainable team, not only you. > That's why I want team's conclusion before trying it on docs.python.org. As pointed out before in this thread, there are workarounds if one really want to see original code, and we also started discussing technical ways to enable more convenient switching. Clearly you want to avoid naming identifiers in your native language. Like I said I have no intention to change your mind, but I only hope you could keep an open mind to bear with others using other languages who want to try this practice. Seems single contributor in other language like Korean was able to make the goals to add it to language switcher. So I don't think it's impossible. > > Additionally, it requires much effort of us. I don't want to pay my effort > only for trying idea of just one person. I'll certainly try to work it out by myself, before asking for help from those who are interested and willing to give a hand. Once again, I'm *not* asking other language teams to follow the same practice. Besides, based on feedback from this thread and the other one in python-dev that shows support for this idea, it's definitely not just one person's idea. > The Transifex project is used only for Japanese. It is maintained > by me and @cocoatomo. It is not official project of PSF or doc-sig yet. If so, I'd follow your suggestion to create my own project on Transifex or use other translation tools. > To build official language team, you meed to read PEP 545. > https://www.python.org/dev/peps/pep-0545/ According to "New Translation Procedure", could I sign up as a single-person team for now, and look for teammates during the way? Thanks, Xuan. From songofacandy at gmail.com Wed Apr 18 23:46:48 2018 From: songofacandy at gmail.com (INADA Naoki) Date: Thu, 19 Apr 2018 12:46:48 +0900 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: <9f776fa6-e9d6-d41d-3eee-1b18d26bde01@gmail.com> References: <0bf5e3c8-e7ea-8e81-caac-81133dbaece2@gmail.com> <11f8518e-0aef-1728-bf73-9f6571b4d93c@gmail.com> <68ff3cd6-8fa9-ca7a-0a81-880f7ad04c34@gmail.com> <9f776fa6-e9d6-d41d-3eee-1b18d26bde01@gmail.com> Message-ID: >> >> If support it for Chinese and you translate it, all Chinese readers >> are affected. >> But the document should be maintained by sustainable team, not only you. >> That's why I want team's conclusion before trying it on docs.python.org. > > > As pointed out before in this thread, there are workarounds if one really > want to see original code, and we also started discussing technical ways to > enable more convenient switching. But implementing it is significant efforts. > Clearly you want to avoid naming identifiers in your native language. Like I > said I have no intention to change your mind, but I only hope you could keep > an open mind to bear with others using other languages who want to try this > practice. You're misunderstand me. It's not reason I'm against trying it on docs.python.org. My main point is it's not proposal from working Chinese language team, while implementing it (language switcher) requires significant efforts to docs.python.org maintainer. >> Additionally, it requires much effort of us. I don't want to pay my >> effort >> only for trying idea of just one person. > > > I'll certainly try to work it out by myself, before asking for help from > those who are interested and willing to give a hand. Once again, I'm *not* > asking other language teams to follow the same practice. Besides, based on > feedback from this thread and the other one in python-dev that shows support > for this idea, it's definitely not just one person's idea. Technical discussion doesn't imply +1, it may be "deferred" or "-0". >> >> The Transifex project is used only for Japanese. It is maintained >> by me and @cocoatomo. It is not official project of PSF or doc-sig yet. > > > If so, I'd follow your suggestion to create my own project on Transifex or > use other translation tools. I recommend you to host translated document on somewhere like Github pages. We have it for testing, see this: * https://python-doc-ja.github.io/py36/ * https://github.com/python-doc-ja/py36 You can try translating code before implement language switcher. PEP 545 requires 100% translation of bugs.html, tutorial, and library/functions. https://www.python.org/dev/peps/pep-0545/#add-translation-to-the-language-switcher By having your own host, you can test your translation and get feedback without waiting that milestone. >> >> To build official language team, you meed to read PEP 545. >> https://www.python.org/dev/peps/pep-0545/ > > According to "New Translation Procedure", could I sign up as a single-person > team for now, and look for teammates during the way? > Hm, if we accept you as single person team, what should we do when other Chinese team proposing us? I recommend you to start looking teammate and trying some translation before sign up team. Bests, -- INADA Naoki From fromwheretowhere.service at gmail.com Thu Apr 19 13:08:10 2018 From: fromwheretowhere.service at gmail.com (Xuan Wu) Date: Thu, 19 Apr 2018 10:08:10 -0700 Subject: [Doc-SIG] Translating sample programs in documentation In-Reply-To: References: <0bf5e3c8-e7ea-8e81-caac-81133dbaece2@gmail.com> <11f8518e-0aef-1728-bf73-9f6571b4d93c@gmail.com> <68ff3cd6-8fa9-ca7a-0a81-880f7ad04c34@gmail.com> <9f776fa6-e9d6-d41d-3eee-1b18d26bde01@gmail.com> Message-ID: > You're misunderstand me. It's not reason I'm against trying it on > docs.python.org. > My main point is it's not proposal from working Chinese language team, while > implementing it (language switcher) requires significant efforts to > docs.python.org > maintainer. IMO the language switcher for sample programs is not a pre-condition or blocker for translating programs, but more like a nice-to-have feature, but like I said before we'll know better after getting feedback from users when they actually try out the translated version. > I recommend you to host translated document on somewhere like Github pages. > We have it for testing, see this: > > * https://python-doc-ja.github.io/py36/ > * https://github.com/python-doc-ja/py36 > > You can try translating code before implement language switcher. > > PEP 545 requires 100% translation of bugs.html, tutorial, and library/functions. > https://www.python.org/dev/peps/pep-0545/#add-translation-to-the-language-switcher > > By having your own host, you can test your translation and get feedback > without waiting that milestone. Thanks a lot for the suggestion and references. > >>> To build official language team, you meed to read PEP 545. >>> https://www.python.org/dev/peps/pep-0545/ >> According to "New Translation Procedure", could I sign up as a single-person >> team for now, and look for teammates during the way? >> > Hm, if we accept you as single person team, what should we do when other > Chinese team proposing us? > > I recommend you to start looking teammate and trying some translation > before sign up team. Though I'm still not clear about the criteria to start the official team, I'll let you know the progress of translation, and see when it's good time to sign up. I appreciate all the feedback and open discussion. Best regards, Xuan.