[Doc-SIG] Translating sample programs in documentation
fromwheretowhere.service at gmail.com
Sun Apr 15 17:56:04 EDT 2018
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
" 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
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Doc-SIG