[Doc-SIG] Translating sample programs in documentation

[Xuan Wu]

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: <http://mail.python.org/pipermail/doc-sig/attachments/20180415/caa0987a/attachment-0001.html>