zmNinjaNg: Skill for Claude Code

Adding a new interface language

The app bundles translations at build time. Adding a locale means touching three code locations plus two prose locations. Miss any one and the failure is silent: i18next falls back to English mid-screen, or the new locale ships with no key-parity coverage.

Run all npm commands from app/.

Below, {code} is the ISO code (it) and {Name} is the language's own name for itself (Italiano).

1. Create the translation file

mkdir -p app/src/locales/{code}
cp app/src/locales/en/translation.json app/src/locales/{code}/translation.json

2. Translate the values

Translate every value in app/src/locales/{code}/translation.json. Do not change, add, or drop keys. The key-parity test in step 5 fails if the shape drifts from en.

Labels must fit 320px (project rule in AGENTS.project.md), so prefer the concise translation where two options exist.

3. Add the language name to every translation file

The languages section of each locale lists all languages, so the picker reads correctly whatever language the UI is currently in. Add "{code}": "{Name}" to the languages section of every translation.json under app/src/locales/, the new one included. List them first rather than working from memory:

ls app/src/locales

Use the same string {Name} in all of them. Language names are not translated.

4. Register the locale

In app/src/locales/resources.ts, add the import alongside the others and the entry in LANGUAGE_RESOURCES:

import {code}Translation from './{code}/translation.json';

export const LANGUAGE_RESOURCES = {
  // ...
  {code}: { translation: {code}Translation },
};

Both pickers and i18next read this map, so nothing else registers a locale.

5. Nothing to do for the pickers

Both of them, Settings → Appearance and the sidebar globe dropdown, render useLanguageOptions (app/src/hooks/useLanguageOptions.ts), which reads the codes registered in step 4 and orders them English first, then by label. The order is covered by app/src/components/layout/__tests__/LanguageSwitcher.test.tsx, which pins the expected sequence, so add the new code there.