[Doc-SIG] Translating sample programs in documentation

[Julien Palard]

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​