Translating sample programs in documentation
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's 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.
Well, I'm not sure weather or not this is what you're looking for, but pep-8 (https://www.python.org/dev/peps/pep-0008/) suggest like this: For Python 3.0 and beyond, the following policy is prescribed for the standard library (see PEP 3131): All identifiers in the Python standard library MUST use ASCII-only identifiers, and SHOULD use English words wherever feasible (in many cases, abbreviations and technical terms are used which aren't English). In addition, string literals and comments must also be in ASCII. The only exceptions are (a) test cases testing the non-ASCII features, and (b) names of authors. Authors whose names are not based on the Latin alphabet (latin-1, ISO/IEC 8859-1 character set) MUST provide a transliteration of their names in this character set. So, I guess translate symbols to Chinese are not gonna help reader to figure out what kind of code should they writing... On Mon, Apr 16, 2018 at 12:41 AM, Xuan Wu < fromwheretowhere.service@gmail.com> wrote:
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's 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 3window 6defenestrate 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.
_______________________________________________ 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/ shell909090%40gmail.com
-- 彼節者有間，而刀刃者無厚；以無厚入有間，恢恢乎其於游刃必有餘地矣。 blog: http://shell909090.org/ twitter: @shell909090 <https://twitter.com/shell909090> about.me: http://about.me/shell909090
FYI I already post this in Doc-SIG mailing list, as it seems to be more relevant there. @Shell, thanks for the reference. Please correct me if I'm wrong, but I don't think the code standard for Python standard library applies to sample programs in the tutorials. Best, Xuan. On 4/15/18 7:49 PM, Shell Xu wrote:
Well, I'm not sure weather or not this is what you're looking for, but pep-8 (https://www.python.org/dev/peps/pep-0008/) suggest like this:
For Python 3.0 and beyond, the following policy is prescribed for the standard library (see PEP 3131): All identifiers in the Python standard library MUST use ASCII-only identifiers, and SHOULD use English words wherever feasible (in many cases, abbreviations and technical terms are used which aren't English). In addition, string literals and comments must also be in ASCII. The only exceptions are (a) test cases testing the non-ASCII features, and (b) names of authors. Authors whose names are not based on the Latin alphabet (latin-1, ISO/IEC 8859-1 character set) MUST provide a transliteration of their names in this character set.
So, I guess translate symbols to Chinese are not gonna help reader to figure out what kind of code should they writing...
On Mon, Apr 16, 2018 at 12:41 AM, Xuan Wu <fromwheretowhere.service@gmail.com <mailto:fromwheretowhere.service@gmail.com>> wrote:
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's 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.
_______________________________________________ Python-Dev mailing list Python-Dev@python.org <mailto:Python-Dev@python.org> https://mail.python.org/mailman/listinfo/python-dev <https://mail.python.org/mailman/listinfo/python-dev> Unsubscribe: https://mail.python.org/mailman/options/python-dev/shell909090%40gmail.com <https://mail.python.org/mailman/options/python-dev/shell909090%40gmail.com>
-- 彼節者有間，而刀刃者無厚；以無厚入有間，恢恢乎其於游刃必有餘地矣。 blog: http://shell909090.org/ twitter: @shell909090 <https://twitter.com/shell909090> about.me <http://about.me>: http://about.me/shell909090
On Mon, Apr 16, 2018 at 4:49 AM, Shell Xu <shell909090@gmail.com> wrote:
Well, I'm not sure weather or not this is what you're looking for, but pep-8 (https://www.python.org/dev/peps/pep-0008/) suggest like this:
For Python 3.0 and beyond, the following policy is prescribed for the standard library (see PEP 3131): All identifiers in the Python standard library MUST use ASCII-only identifiers, and SHOULD use English words wherever feasible (in many cases, abbreviations and technical terms are used which aren't English). In addition, string literals and comments must also be in ASCII. The only exceptions are (a) test cases testing the non-ASCII features, and (b) names of authors. Authors whose names are not based on the Latin alphabet (latin-1, ISO/IEC 8859-1 character set) MUST provide a transliteration of their names in this character set.
So, I guess translate symbols to Chinese are not gonna help reader to figure out what kind of code should they writing...
That only applies to the Python stdlib itself. It's a feature that Python allows unicode identifiers, and there's nothing about that against PEP-8 for sure. I think it's a great idea; I'm not sure how it works out technically in terms of providing .po files for .rst documentation or if there's some better mechanism for that... Best, E
On Mon, Apr 16, 2018 at 12:41 AM, Xuan Wu <fromwheretowhere.service@gmail.com> wrote:
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's 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.
_______________________________________________ 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/shell909090%40gmail.com
-- 彼節者有間，而刀刃者無厚；以無厚入有間，恢恢乎其於游刃必有餘地矣。 blog: http://shell909090.org/ twitter: @shell909090 about.me: http://about.me/shell909090
_______________________________________________ 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/erik.m.bray%40gmail.com
Hi Erik, thanks a lot for the support. As mentioned in the thread in Doc-Sig list, IMO it can be great showcase to use identifiers in native languages, which PEP 3131 was designed for initially, while even now many beginners don't even know it's possible. Besides, thanks to the references from that thread, it seems some change in Sphinx config is needed before the programs can be translated. Help or pointers are greatly appreciated, as I'm brand new to the documentation system. I've setup translation system locally and got a testing Chinese version up and running, but haven't got far on Sphinx config. Last but not least, please let me know if it is OK to continue this topic here, especially the technical details. Best wishes, Xuan. On 4/16/18 5:35 AM, Erik Bray wrote:
On Mon, Apr 16, 2018 at 4:49 AM, Shell Xu <shell909090@gmail.com> wrote:
Well, I'm not sure weather or not this is what you're looking for, but pep-8 (https://www.python.org/dev/peps/pep-0008/) suggest like this:
For Python 3.0 and beyond, the following policy is prescribed for the standard library (see PEP 3131): All identifiers in the Python standard library MUST use ASCII-only identifiers, and SHOULD use English words wherever feasible (in many cases, abbreviations and technical terms are used which aren't English). In addition, string literals and comments must also be in ASCII. The only exceptions are (a) test cases testing the non-ASCII features, and (b) names of authors. Authors whose names are not based on the Latin alphabet (latin-1, ISO/IEC 8859-1 character set) MUST provide a transliteration of their names in this character set.
So, I guess translate symbols to Chinese are not gonna help reader to figure out what kind of code should they writing...
That only applies to the Python stdlib itself. It's a feature that Python allows unicode identifiers, and there's nothing about that against PEP-8 for sure.
I think it's a great idea; I'm not sure how it works out technically in terms of providing .po files for .rst documentation or if there's some better mechanism for that...
Best, E
On Mon, Apr 16, 2018 at 12:41 AM, Xuan Wu <fromwheretowhere.service@gmail.com> wrote:
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's 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.
_______________________________________________ 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/shell909090%40gmail.com
-- 彼節者有間，而刀刃者無厚；以無厚入有間，恢恢乎其於游刃必有餘地矣。 blog: http://shell909090.org/ twitter: @shell909090 about.me: http://about.me/shell909090
_______________________________________________ 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/erik.m.bray%40gmail.com
participants (3)
-
Erik Bray -
Shell Xu -
Xuan Wu