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.

6. Update the user doc

docs/user-guide/settings.md, Appearance table, Language row, names the available languages in English. Add the new one.

Also add the code to the Localization contract's list in AGENTS.project.md. app/src/tests/agents-contracts.test.ts fails until the list matches LANGUAGE_CODES.

7. Add the plural forms the language needs

English declares _one and _other. A language with more plural categories needs the rest, or i18next finds no key for those counts and silently renders English: Russian showed "2 monitors" until _few and _many were added. The parity test checks every category Intl.PluralRules reports for counts up to 100, so it tells you which keys are missing.

node -e "console.log(new Intl.PluralRules('{code}').resolvedOptions().pluralCategories)"

Nothing to do for dates, the assistant, or the parity test

These already take the active locale as data, so none of them needs a per-locale entry:

• app/src/lib/relative-time.ts passes the code straight to Intl.RelativeTimeFormat.
• app/src/lib/assistant/system-prompt.ts interpolates the locale into the prompt and asks the model to answer in the user's language.
• app/src/locales/__tests__/translation-keys.test.ts discovers locale directories on disk, so the new one is key-checked against en with no edit.

Verify

npm test
npx tsc -b
npm run build
npm run test:e2e -- settings.feature

settings.feature has a language-change scenario, so it is the relevant e2e run for this change.

Then check the UI by hand: Settings → Appearance → Language, and the sidebar globe dropdown. Both should list the new language, and selecting it should change the visible text.

Checklist

• app/src/locales/{code}/translation.json created and fully translated
• languages.{code} added to every translation file under app/src/locales/
• app/src/i18n.ts import and resources entry
• expected order updated in LanguageSwitcher.test.tsx
• plural forms for every category the language needs
• docs/user-guide/settings.md Language row
• code added to the Localization contract in AGENTS.project.md
• npm test, npx tsc -b, npm run build, npm run test:e2e -- settings.feature