mgocbr3/world-of-aphasya / .claude/skills/i18n-locale-fill
i18n-locale-fill
VerifiedFill pending i18n rows across every locale for World of ClaudeCraft, the release-time workflow. Use when the release-tier gate (I18N_RELEASE_TIER=1) fails on pending rows, when asked to translate or fill locales, overlays, or matcher DICTs, or when preparing a release branch whose registry still has pending entries. Covers the worklist generator, where each scope's fills land, the placeholder and glossary contracts, and the known traps (English-in-overlay, shared DICT references, the "todo" guard, reword staleness, native punctuation in overlays).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.7 KB |
SKILL.md
View on GitHub---
name: i18n-locale-fill
description: Fill pending i18n rows across every locale for World of ClaudeCraft, the release-time workflow. Use when the release-tier gate (I18N_RELEASE_TIER=1) fails on pending rows, when asked to translate or fill locales, overlays, or matcher DICTs, or when preparing a release branch whose registry still has pending entries. Covers the worklist generator, where each scope's fills land, the placeholder and glossary contracts, and the known traps (English-in-overlay, shared DICT references, the "todo" guard, reword staleness, native punctuation in overlays).
user-invocable: true
---
# 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).
- **`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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |