Skip to content

A language folder falls back per field all the way down, or is refused - #609

Merged
maximsan merged 3 commits into
mainfrom
fix/language-overlay-loses-nested-text
Sep 17, 2026
Merged

maximsan merged 3 commits into
mainfrom
fix/language-overlay-loses-nested-text

Conversation

@maximsan

Copy link
Copy Markdown
Owner

Why

Found auditing #605. The overlay merged one level deep, so the per-field
fallback it promises stopped at the top of an entry — and most of the course's
prose sits below that. No ticket; the audit is in the conversation that
produced this.

Watch for

  • The bug was silent deletion, not a fallback gap. A folder translating a
    help entry's steps replaced the whole list: three English steps became one
    Polish step, with no error. A lesson with three of nine cards translated lost
    six cards of teaching. Every bank carries nested prose — lessons.cards,
    card_kind_help.steps, mini_games.steps, mini_game_content.rounds,
    visual_guides.notes.
  • Three things are now refused that were silently accepted, ruled by the
    owner: a list shorter than the master's, a field the master has no slot for
    (a misspelt key left the real one in English), and one id translated twice
    (whichever came last won). Each names the entry and the field to redraft.
  • Marks are stripped at every depth now, not only the record's top level,
    since ADR-0026 marks a piece of text wherever it sits.
  • A record broken by the folder names the folder. loadBank reported every
    parse failure against the English master, which is not where the bad field
    came from once an overlay is in play.
  • Unreachable today. English ships alone, so no folder exists to hit any of
    this. It becomes reachable the day one lands — and Draft a language folder from the English master #603, the tool meant to
    guarantee a folder is complete, is not built.

Not here

Mark granularity still mismatches ADR-0026. Marks are keyed by top-level
field, so a lesson's only key is cards and one fingerprint covers all of
them — fix a typo in card three and every card re-opens for retranslation,
which is what the ADR's "per piece of text, not per entry" exists to prevent.
That is the drafting tool's shape to settle (#603), not the loader's.

Checks

The gates, all green locally: format, analyze, the metrics gate, the comment
cap on the touched files, check_changelog.sh, and the full suite at 3236
passing. Seven new overlay tests and two loader tests; the nine existing
overlay tests pass unchanged. Both defects were reproduced against the real
card_kind_help content before the fix.

…efused

The overlay merged one level deep, so a folder translating a lesson's
cards or a help entry's steps replaced the whole list rather than falling
back per item: three English steps became one Polish step, silently, and
a lesson with three of nine cards translated lost six cards of teaching.

The fallback now reaches every depth, and the cases that would replace
English text rather than fall back to it are refused the way ADR-0018
refuses broken content — a list shorter than the master's, a field the
master has no slot for (a misspelt key leaves the real one untranslated),
and an id the folder translates twice, which silently kept whichever came
last. A record broken by the folder now names the folder, not only the
English master it never came from.

English ships alone, so none of this is reachable today; it is reachable
the day a folder lands, and the tool meant to guarantee completeness
(#603) does not exist yet.
The 1.2.0+5 release landed on main after this branch was cut, so merging
main carried the bullet into the released section. It is a fix, not an
addition, so it sits under Fixed.
@maximsan
maximsan merged commit a4502bf into main Sep 17, 2026
7 checks passed
@maximsan
maximsan deleted the fix/language-overlay-loses-nested-text branch September 17, 2026 17:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant