Code comments and docstrings in the French lectures: French or English? #88
Description
Decided 2026-10-12: option A (decision). Code comments and docstrings in the French lectures: translated or kept in English? Matt settles this with Emile, the edition's editor of record, as for other house-style questions; it sets the --localize value for the fresh drafts and whether a consistency pass is needed.
#82 settled on fresh drafts on 2026-10-06, so the ruling is needed before the first one; corrections in progress carry on and are aligned with it afterwards.
Emile, the edition's editor, asked on #84 (2026-10-02):
Hey Matt, I have a quick question on convention. I've noticed the chapters aren't fully consistent about whether comments and docstrings inside code cells get translated into French. about_py.md already has French comments like # Charger la bibliothèque, but some other chapters leave comments and docstrings in English. Should we translate explanatory comments and docstrings consistently going forward, while leaving code identifiers, API names, and executable output strings as-is? Want to make sure I'm applying the same rule across chapters rather than deciding it one by one.
How the edition got here
- The first translation of each lecture (the 2026-07-15 seed, and the sync that added polars) translated the
#comments in most lectures, as inabout_py.md's# Charger la bibliothèque, but not in all: the comments inpython_oop.mdare almost all in English, andpandas.mdmixes the two. - Docstrings stayed in English in all but one lecture (
numpy.mdhas eight, for example; the one inautodiff.mdis in French), because the translation engine'scode-commentsrule covers#comments only. - Sync applies no localisation rule (Sync applies no localisation rules, so every organically-synced lecture lands with English figure labels and no font config action-translation#178), so whether a comment that sync adds or edits comes out in French is left to the model (the sync that added polars, 🌐 [translation-sync] Add Polars lecture to complement existing Pandas lecture #20, translated its comments).
- A new draft follows the engine's
--localizesetting, chosen when the draft is made. Its default translates#comments and figure labels;--localize nonetranslates neither.
Options
- A. Translate the explanatory text in code.
#comments and docstrings in French; code identifiers, API names and the strings a program prints stay as they are. This is the rule the question proposes, and most lectures already follow it for comments. - B. Keep code cells as in the English. Comments and docstrings in English throughout; only the prose is translated.
What the ruling sets
- The
--localizevalue for any fresh draft (Proposal: review each remaining lecture as a fresh draft on its own PR #82). Under A,#comments stay translated, and translating docstrings as well needs the engine'scode-commentsrule extended to cover them. Under B, the value isfigure-labelsornone. - Whether a consistency pass is needed, and how large it is. Under A, the English comments and docstrings that remain:
python_oop.md, part ofpandas.md, and the docstrings in about eight lectures. Under B, the French comments in most lectures. - Nothing for sync until Sync applies no localisation rules, so every organically-synced lecture lands with English figure labels and no font config action-translation#178 is settled: until then, whether a comment that sync adds or edits comes out in French is left to the model, whichever way this is ruled.
Done when
- the ruling is recorded in a comment on this issue, and the first line of this issue reads "Decided YYYY-MM-DD", with a link to that comment
- the drafting settings follow it: the
--localizevalue for any fresh draft and, if docstrings are to be translated, the engine rule that covers them
Activity
Honaminto commentedon Oct 11, 2026
Hi Matt, I'd go with option A. Readers of the French edition should be able to follow the code without switching languages, so I think the explanatory text belongs in French, while anything Python actually runs stays as it is.
In practice, I will now translate
#comments and docstrings, including the numpydoc headings (« Paramètres », « Renvoie ») and the text under them. I leave identifiers, function and argument names, module and API names, file names, and anything the program prints or returns untouched. When a type name appears as code, likesetorfloat, I keep it in code too.There's one edge case I ran into on python_essentials. When an output block echoes a docstring (the
f?example), I translated the docstring text so it matches the code cell, but I left the labels IPython generates (Type, String Form, File, Definition, Source) in English, since that's what readers will actually see when they run it. Commented-out code I'd also leave as code.That's the rule I've followed on #84 and #93. If it works
mmcky commentedon Oct 12, 2026
Decided 2026-10-12: option A. Thank you, Emile. Your answer settles it, and your rule becomes the edition's rule:
#comments and docstrings, including numpydoc section headings (« Paramètres », « Renvoie ») and the text under them.set,float), commented-out code, and anything the program prints or returns.f?): the docstring text is translated to match the code cell, and the labels IPython generates (Type,String Form,File,Definition,Source,Docstring) stay in English.What follows: