Skip to content

mgocbr3/world-of-aphasya / .claude/skills/i18n-locale-fill

i18n-locale-fill

Verified

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).

FileKindSize
SKILL.mdskill md5.7 KB
---
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.
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall