W2 — localisation becomes deterministic (after D1) [P1]

[mmcky]

Sub-issue of the 2026-08-10 work-plan tracker. Every rule that must hold on every run becomes a deterministic transform, homed in #172's write-path choke point (pull it forward from Wave 2 — its Wave-3 trigger F23 fired via intro.zh-cn#285). Gated on D1 (global font mechanism): if global lands, #178 is unnecessary, #141's injection half collapses, and #182 is the whole remaining job.

• D1 (kickoff gate, moved from W0 2026-08-11) — decide the global font mechanism direction (env font + matplotlibrc is the better-verified route; IPython hook needs a verification spike). Determines the fate of Sync applies no localisation rules, so every organically-synced lecture lands with English figure labels and no font config #178 (unnecessary if global), init: i18n-font-config injection is nondeterministic (missed 5 of 37 lectures) and the font path is hard-coded #141 (collapses to emit-nothing), The #107 i18n-preservation guardrail is prompt prose and fails at scale — 21 lectures stripped, 9 now rendering tofu #182 (becomes the whole job). Context: Sync applies no localisation rules, so every organically-synced lecture lands with English figure labels and no font config #178 2026-07-24 comment + project-translation CJK review
• The deterministic target-local-read guard is in neither the action bundle nor sync mode, and is blind to URL-form reads #253 — wire the target-local-read guard into the sync path, bundle it (plus a build-time assertion the bundle contains it — today grep -c findTargetLocalReads dist-action/index.js = 0), resolve same-repo raw URLs before the URL skip
• The #107 i18n-preservation guardrail is prompt prose and fails at scale — 21 lectures stripped, 9 now rendering tofu #182 — deterministic i18n preservation: pre-write diff of target code cells; re-apply recognised adaptation lines (font registration/rcParams, LaTeX preamble/helpers, localised plot strings); # i18n markers stay a hint, not the signal
• Sync carries text.usetex into CJK targets, where LaTeX cannot typeset the labels — a permanent, recurring build break #181 — strip/report text.usetex for scripts LaTeX can't typeset (currently no usetex awareness anywhere in src/)
• French guillemets interior NBSP is prompt-only — needs a deterministic transform #217 — per-language typography rule list (fr guillemets interior NBSP; zh no-space around ——), applied pre-heading-map per tech-debt T2·3: Create the write-path choke point: finalizeTranslatedDocument #172's placement constraints
• Sync overwrites localised _toc.yml part captions with English, and nothing detects it #254/Figure captions ship untranslated: 74 of 237 on lecture-python.zh-cn across 18 lectures (re-measured 2026-08-20; was 85 of 222) #255 shared predicate — one deterministic check: a target-language file must not carry a caption byte-identical to its source (covers _toc.yml part captions and mystnb caption: metadata). Caption translation per D1's outcome; repair of the existing 85 is a separate hand pass
• init: i18n-font-config injection is nondeterministic (missed 5 of 37 lectures) and the font path is hard-coded #141 (path half) — font-path convention detection or --font-path (moot if D1 goes global)

Member issues: #141 #178 #181 #182 #217 #253 #255 · structural home #172

---

Generated by Claude Code

[mmcky]

What "after D1" gates — and what it does not, 2026-08-20

Resolved while re-verifying project-translation#37, whose item 1 carried "establish what W2's after-D1 dependency actually is and whether it gates the caption check" as an open question. Recording the answer here so the next reader does not have to re-derive it.

D1 is not an issue. It is a decision item — the editions-level global matplotlib font mechanism — with no issue number and no PR. It was moved out of W0 (#258) into this issue as a kickoff gate on 2026-08-11, and it is still undecided: the box here is unticked, .dev/decisions/ holds no font-mechanism record, and neither does project-translation. .dev/STATE.md still carries it on the resume list.

What D1 genuinely scopes is the font cluster — #178, #141, #182 — per the 2026-08-10 workplan table ("Decide the global font mechanism (editions-level). Scopes the whole of cluster C") plus the caption translation surface.

What it does not gate is the deterministic check. This issue's own caption bullet states the byte-identity predicate unconditionally and defers only translation: "one deterministic check: a target-language file must not carry a caption byte-identical to its source (covers _toc.yml part captions and mystnb caption: metadata). Caption translation per D1's outcome; repair of the existing 85 is a separate hand pass". Note that predicate already spans both surfaces — the _toc.yml part captions are inside W2's scope, not outside it.

What sits in W1 (#259, P0, v0.27.0) is the _toc.yml structured merge — "add/remove - file: entries only; never write captions from source; skip entries whose target document is absent from target ∪ PR. Plus #254's deterministic caption-script assertion." So the assertion is dual-homed across W1 and W2, and W1 is gated on #169 rather than on D1 — with #169 slice 1 landed 2026-08-19.

So neither home waits on D1, and a session reading "after D1" as a blocker would stall work that is already unblocked. Worth deciding the W1/W2 split explicitly when the design is drafted, since the assertion currently appears at two different priorities (P0 in W1, P1 here).

Two riders for whoever takes D1:

• #225 is a built PR for work D1 might delete. "Apply localisation rules on the sync path for newly-created files" (branch fix/178-sync-localisation) has been open since 2026-07-27, and D1's stated effect is that Sync applies no localisation rules, so every organically-synced lecture lands with English figure labels and no font config #178 becomes "unnecessary if global". Decide its fate in the same pass rather than leaving it waiting on a decision that may discard it.
• D1 is an overloaded token in this repo. It is also a question ID in the Malayalam reviewer questionnaire under experiments/ml-benchmark/, where it means something entirely unrelated — and more files carry that sense than the W-track one (6 versus 5), so a grep lands on the wrong referent easily. The W-track D1 lives in three issue bodies (#257, #258 and this one) plus .dev/STATE.md and the 2026-08-10/11 workplan log entries.

[mmcky]

Split proposed in the #254 design draft (#254 (comment)): detection (the shared byte-identity check, both surfaces) goes wholly to W1/#259; this issue keeps production — deterministic caption localisation and the font block, which genuinely wait on D1. Suggest recording D1 as deferred-with-owner in .dev/decisions/ so the non-gating conclusion stops being re-derived each session.