i18n locale fill (release time)

Contributors add ENGLISH only; the maintainer fills every locale at release. This skill is that fill workflow. The release-tier gate (I18N_RELEASE_TIER=1, automatic on release/** branches) hard-fails on any pending registry row, so a release is not shippable until the fill lands.

1. Generate the worklist

npm run i18n:gen        # refresh the registry first
npm run i18n:worklist   # writes one batch per language under docs/i18n-scaling/worklist/ (gitignored)

scripts/i18n_fill_worklist.mjs is data-only (no translation): each batch entry carries { scope, key, english, placeholders, siblings }.

• main-scope keys are filled in the matching src/ui/i18n.locales/<lang>.ts overlay.
• sim / server / admin scope keys are filled in their matcher DICTs (the worklist header in scripts/i18n_fill_worklist.mjs names the exact files).
• Sim-scope keys DO reach the worklist (since Masterwrought Phase 19F, ruling qr-19-sim-scope-pending-is-unreachable): the registry reads each locale's OWN source blocks through simDictProvidedKeys in src/ui/sim_i18n.ts, never the assembled DICT (which is dense by construction, baseEnTable spread under every locale), so a sim row with no fill in a locale's block is pending and lands in that locale's batch. Fill a sim key in the locale's BASE_DICT block of src/ui/sim_i18n.ts (the eight newest locales keep theirs in BASE_NEW of src/ui/sim_i18n.newlocales.ts, a hand-maintained file despite its old banner; each of those locales' own block in sim_i18n.ts spreads BASE_NEW in the MIDDLE of its literal rows, so a key spelled in both is read from whichever spelling comes last in the block, and the registry's row-count anchor in tests/i18n_status_registry.test.ts reds on the duplicate either way), and NEVER paste the English into a locale block: a copied row reads translated and ships English (the sim scope has no copied-English guard; only tests/localization_fixes.test.ts's release-tier s3_localized arm sees it late). Run npm run i18n:gen before the suites: the registry pin compares the artifact against the live source and reds on a stale one. The five per-locale *_EXTRA tables the RULES matchers read (arena, battleground, quest, item, raid) are tsc-forced dense and stay outside the registry; check them by eye at release.
• humanRequired entries are blocked by default (quest narratives, names, lore, SEO copy): never machine-fill them; only autoFillable entries are fair game for a model pass.

Batches are per-language and independent: fan out one fill agent per language when the volume is large, then regenerate once at the end.

1b. The chunk families OUTSIDE the registry (deeds and reliquary)

The Deeds and Reliquary systems keep their locale tables in lazy per-base-locale chunks that the registry and scripts/i18n_fill_worklist.mjs never see: src/ui/deed_i18n.locales/<locale>.ts and src/ui/reliquary_i18n.locales/<locale>.ts (loader contract pinned by tests/deed_i18n_lazy.test.ts and tests/reliquary_i18n_lazy.test.ts). Consequences:

• Zero pending registry rows does NOT prove full coverage. A fill pass driven only by the worklist ships English deed/reliquary rows while the registry reads clean. Their coverage is enforced only by the release-tier arms (it.runIf(I18N_RELEASE_TIER === '1')) in tests/deed_i18n.test.ts and tests/reliquary_i18n.test.ts, which walk deedTranslationManifest() / reliquaryTranslationManifest() against every base locale table. Run those release-tier to prove this surface, not the pending count.
• Fill every base locale chunk in the family; a chunk carries only real catalog ids (the same tests reject a stale id or a title on a deed that rewards none).
• The overlay punctuation exemption does NOT extend here. These chunk files sit outside the src/ui/i18n.locales copy-scan exemption: no em/en dashes or emoji in any value, even where the locale would natively use them (the pin tests enforce it).

2. The fill contract

• Translate, never transplant. The registry counts PRESENCE, not language: pasting the English value into an overlay marks the row filled and silently ships English. Do not.
• Placeholder parity. Every {token} in the English value must appear verbatim in the fill (the worklist lists them). The scanner checks parity; a dropped token is a break.
• Locked terminology. Classic-MMO terms per locale live in scripts/i18n_glossary.json and are locked; follow them, and extend the glossary when a new recurring term appears.
• Matcher DICT values must be literal string copies. Never alias or share a reference between DICT rows; the matcher relies on per-row literals.
• Native punctuation in overlays is legitimate. Russian and other locales use real em dashes; NEVER strip them. The repo copy scans deliberately exclude src/ui/i18n.locales.
• The placeholder guard flags a bare "todo" value, which is also a real word in es/pt. Phrase such fills differently (for example "por hacer") so the guard does not trip.

3. Regenerate, verify

1. npm run i18n:gen regenerates the resolved bundles and the status registry.
2. Biome-format every overlay file the fill touched in the same change: npx @biomejs/biome check --write src/ui/i18n.locales/<touched>.ts .... CJK and other wide-glyph fills blow the 100-column lineWidth silently (the line LOOKS short in an editor but is over by bytes), and the changed-files biome gate then fails a later round on a format diff you never saw (it cost the phase 13 closing gate its first round). Note biome SIZE-SKIPS files over 1.0 MiB (ru_RU is there already): gate green is not format evidence for those, and that is a known accepted state, not something to fix.
3. Stage the regenerated artifacts in the SAME commit as the fills. The freshness gate diffs the regenerated output against the staged/committed copies; unstaged artifacts fail it.
4. Prove completion: run the i18n steps release-tier, I18N_RELEASE_TIER=1 npm run gate (or at minimum i18n:gen + the guard tests), and confirm zero pending rows remain. Zero pending covers the REGISTRY only: the deed/reliquary chunk families (section 1b) are proven by their own release-tier test arms, not by the pending count.

4. Reword staleness (the silent trap)

Rewording an EXISTING English value does not mark its translations pending: every locale silently keeps the old meaning. After any English copy change, diff the resolved en output between the base branch and HEAD and re-fill the touched keys in the same change.