Japanese terminology and house style: rulings before the glossary merges #337

Open. Ruled 2026-10-02 (comment): T1–T4, H3, H4, H6 (for the drafts) and C2. Awaiting answers: H1 (question), and H2, H5 and C1 (in the rulings comment).

#69 adds Japanese to the translation engine: a 357-term glossary (glossary/ja.json, v1.1) and seven Japanese prompt rules (LANGUAGE_CONFIGS.ja in src/language-config.ts; "rule 1" below means the first of them), both shaped by the review on that PR. Before it merges (#338), two things need a ruling: four glossary points raised since the v1.1 rebuild (T1–T4), and the house style for prose (H1–H4), which the rules cover only in part. The Japanese edition will be drafted from these rules one lecture at a time, and no lecture is drafted until they are settled.

None of the four glossary terms occurs in the Python Programming lectures (FRED appears there only as the bare acronym, in pandas.md and polars.md), so T1–T4 finish the glossary, while H1–H4 shape every page of the edition. Code comments (H5) and figure labels (H6) are open questions, to become a formal action-translation rule later; they do not block the glossary merge. C1 and C2 are optional.

Settled on #69 and not reopened here: Japanese only where a well-known, standard Japanese term exists, otherwise English, and English if in doubt (2026-08-01 and 2026-08-12); personal names in Latin script; ・ rather than ＝ in compound names; lake モデル and cost-to-go 関数; abbreviations as the Japanese term followed by the acronym in parentheses, 国内総生産（GDP） (the width of the parentheses is H3); 市場清算 for market clearing; 産業連関モデル for the input-output model. Programming vocabulary (function, list, namespace and the like) is not decided here either: #339 handles it separately, as a short glossary PR with evidence from test translations.

Glossary terms

Positions are from the comments on #69 by the edition's two translators, Chihiro (Chihiro2000GitHub) and Kenko (xuanguang-li).

T1. Authority centrality

• v1.1: Authority centrality (English). v1.0 had オーソリティ中心性.
• Chihiro (2026-08-11): keep English, as オーソリティ is not a familiar word in Japanese.
• Kenko (2026-09-08): オーソリティ中心性, for consistency with the glossary's Hub centrality → ハブ中心性.
• Chihiro (2026-09-10): agrees with オーソリティ中心性, for that consistency.
• Proposed: オーソリティ中心性.

T2. Marginal product of capital

• v1.1: 資本の限界生産物.
• Kenko (2026-09-08): 資本の限界生産力, because Japanese Wikipedia translates marginal product as 限界生産力.
• Chihiro (2026-09-10): agrees. 資本の限界生産物 sounded slightly more natural personally, but the Wikipedia check points the other way, and a search also suggested 限界生産力 is more common.
• Checked 2026-10-01: Japanese Wikipedia's article is 限界生産力, and there is no article at 限界生産物.
• Proposed: 資本の限界生産力.

T3. Federal Reserve Economic Data

• v1.1: 連邦準備経済データ（FRED）, unchanged since v1.0.
• Kenko (2026-09-08): 連邦準備 on its own reads oddly (literally "the Federal's preparation"); proposed 連邦準備銀行経済データ.
• Chihiro (2026-09-10): 銀行 is fine too, but a rough search suggested 連邦準備制度経済データ (制度 rather than 銀行) is more common; only the English Wikipedia has an article on FRED, so this is not certain.
• Kenko (2026-09-21): agrees with 制度.
• Note: rule 7 says "named datasets and surveys keep their English name (FRED, Survey of Consumer Finances)", yet the glossary has translated this full name since v1.0. So either the full name is translated and rule 7 is amended to say how a dataset's name is written, or the full name goes back to English.
• Proposed: 連邦準備制度経済データ（FRED）, with rule 7 amended.

T4. Survey of Consumer Finances

• v1.1: Survey of Consumer Finances (English, with no （SCF）). v1.0 had 消費者金融調査（SCF）.
• Chihiro (2026-08-11): keep English, because 消費者金融 means the consumer-lending business, so 消費者金融調査 misleads, and a survey's proper name can stay as it is, like the FRED and NBER entries.
• Chihiro (2026-09-10): inclined to add the abbreviation after all, because the lectures use it on its own: inequality writes "Survey of Consumer Finances (SCF)" and then uses the SCF_plus dataset. (The other lecture that names the survey, mle, also writes "(SCF)".)
• Kenko (2026-09-21): the glossary's Japanese-plus-abbreviation pattern, 消費者金融調査（SCF）.
• Options: (a) Survey of Consumer Finances, as in v1.1; (b) Survey of Consumer Finances（SCF）; (c) 消費者金融調査（SCF）, which runs into the consumer-lending objection of 2026-08-11. Parentheses follow H3.
• No proposal: the two positions differ.

House style

H1. Register. Which sentence style should the edition use?

• (a) です・ます調 throughout: この関数はリストを返します。
• (b) である調 throughout: この関数はリストを返す。
• (c) です・ます for explanation and である for definitions, the example given in the engine's add-language tutorial.
• Today: no rule sets the register, so the model chooses.
• For comparison: the introduction page of the Japanese Python tutorial writes です・ます, with no である endings; the passage of Prof. Abe's DP notes quoted on feat(glossary): add Japanese (ja) translation glossary #69 is in the plain style (…消費水準を割り当てる。).

H2. Sentence punctuation.

• (a) 、。 as today: まず、配列を作ります。
• (b) ，． as is common in Japanese mathematics and economics writing: まず，配列を作ります．
• Today: rule 1 asks for "full-width Japanese punctuation marks (、。「」) not ASCII punctuation (,.)". It is a prompt instruction only; nothing checks it mechanically.
• For comparison: that tutorial page and the Abe passage use 、。; the article cited on feat(glossary): add Japanese (ja) translation glossary #69 for 状態条件付き請求権 uses ， (…請求権を用い，).

H3. Parentheses around Latin text and abbreviations.

• (a) full-width: 国内総生産（GDP）
• (b) half-width: 国内総生産 (GDP)
• Today: full-width, by rule 7 and in the 12 glossary entries that add a Latin abbreviation in parentheses (the two that wrap a katakana gloss are C1's question). Nothing covers other parentheses, such as an English term given after a Japanese one.
• For comparison: the Japanese Python documentation uses half-width with a space, as in 型 (list) and 引数 (argument). If (b), those 12 glossary entries change with it.

H4. Spacing between Japanese and Latin words or inline code.

• (a) a half-width space: NumPy の配列, x の値
• (b) no space: NumPyの配列, xの値
• Today: rule 2 asks for a space only next to inline MyST roles ({doc}, {ref} …) and Markdown links. Nothing covers plain Latin words or inline code, and the glossary has both forms (lake モデル and cost-to-go 関数, but AR(1)過程).
• For comparison: the same tutorial page almost always puts a space between Japanese and Latin words, and always around inline code. This choice shows on most lines of the edition: names.md alone has over 100 inline-code spans.

Open: code comments and figure labels

H5. Code comments. Should comments in code cells be translated into Japanese?

• (a) yes, as the Chinese and French editions do.
• (b) no, keep them in English, as the Malayalam edition does by its own rule.
• Today: comments are translated when a lecture is drafted with the code-comments localisation option (--localize code-comments), which carries Chinese and Persian examples but no Japanese one yet.

H6. Figure labels. Should plot titles, axis labels and legends be translated into Japanese?

• Today: the engine has no Japanese font set-up for matplotlib (its font rule covers Chinese only), and Japanese labels drawn without a Japanese font render as empty boxes. The CLI's --localize option decides at drafting time: its default translates comments and labels, and --localize code-comments translates comments only.
• Japanese labels need Japanese font support, whose mechanism is open in W2 — localisation becomes deterministic (after D1) [P1] #260.

Optional consistency points

Where no ruling is recorded, the glossary stays as it is.

C1. Katakana glosses. Seigniorage → 通貨発行益（シニョリッジ） and Support → 台（サポート） keep a katakana gloss, while Annuity's （アニュイティ） was dropped as unnecessary (Chihiro, 2026-08-11). Keep both glosses, drop both, or decide each?

C2. Acronym-only entries. The entries for CPI, GDP, OLS, CCDF, GFC and SSR expand the acronym (消費者物価指数（CPI） and so on), while the entries for FRED and NBER keep the bare acronym. Keep the difference, or expand FRED and NBER on first use as well? This decides what pandas.md and polars.md say where they introduce FRED.

After the rulings

@mmcky records the rulings in one comment here, as the exact glossary values and rule wording, and changes the first line of this issue to "Decided YYYY-MM-DD". #338 applies them to #69 (glossary v1.2, the Japanese rules and the decision record); the programming terms (#339) and an engine release (#340) follow, and only then is the first lecture of the Japanese edition drafted.

Done when

• T1–T4 and H1–H4 each have a ruling recorded in one comment on this issue (C1 and C2 too, where ruled)
• the first line of this issue reads "Decided YYYY-MM-DD", with a link to that comment