write-terva-locale

Translating terva

Use this skill when the user wants to localize terva — start a new UI language, finish or fix an existing one, or make a newly added string translatable. terva ships English and loads translations from a per-key catalog that an operator can edit and contribute back.

How terva's i18n works (read this first)

• English is the key. The message id is the English sentence. A locale file maps that English to your language: "start a fresh session": "aloita uusi istunto". There is no separate key to invent or look up.
• Embedded default + operator overlay. Shipped translations live in packages/i18n/locales/<lang>.json (embedded in the binary). Your edits live in $TERVA_HOME/locales/<lang>.json and shadow the embedded file per key — override one string without copying the rest.
• Graceful fallback. Any key you leave blank ("") or don't include falls back to English, so a partial translation is always safe to ship and run.
• Selecting a language. TERVA_LANG=<tag> terva, or set "language": "<tag>" in config.json. The tag is BCP-47: fi, pt-BR, de. en/en-* is the built-in source — no file read UNLESS the operator opts into an English overlay ($TERVA_HOME/locales/en.json or prompts/en.json) to reword or override strings in place. See docs/localization.md in the repo.

Translating a language — the workflow

1. Scaffold the file. terva locale init <lang> writes $TERVA_HOME/locales/<lang>.json listing every source string. Existing translations are pre-filled (so you tweak in place); the rest are blank.
2. Edit the JSON. For each entry, replace the empty value with your translation. The key stays exactly as-is — never edit a key.

   {
     "show this help": "näytä tämä ohje",
     "saved %d files": "",              // still to translate
     "%d agent|%d agents": { "one": "%d agentti", "other": "%d agenttia" }
   }
   

3. Preserve the machinery. Keep every %s / %d / %0.1f format verb — same ones, any order. Keep {{user}}/{{char}} macros, flag names (--persona), command names (terva locale), and file paths ($TERVA_HOME/..., docs/rpc.md) verbatim. Translate the prose around them.
4. Plurals. A plural entry's key is "english one|english other"; its value is an object of CLDR categories. Your language's set may be more than one/other (Polish has one/few/many/other) — terva locale init scaffolds the right categories for the tag. Fill each; other is required.
5. Check it. terva locale validate (JSON + that your %-args match the source), terva locale diff <lang> (what's missing or now-orphaned), terva locale list (coverage %).