Internationalization (i18n)

Localize OpenPets desktop UI, pet speech, and plugins with the shared fallback model and locale contribution workflow.

Internationalization (i18n)

OpenPets localizes three distinct surfaces, each with its own mechanism but a shared principle: resolve through fallback-aware catalogs, default to English, never crash on a missing key. This doc explains all three and how to add a locale.

Source maps: apps/desktop/src/i18n/codemap.md (+ locales/, reactions/), apps/desktop/src/codemap.md (plugin-i18n.ts).

Supported locales

The desktop host ships 8 locales (English plus seven):

The original target set is Asian + Latin American markets; French was added later. The repo README is translated into those original six (README.<locale>.md). The public web site currently localizes a narrower set (English unprefixed, Chinese under /zh; site docs are English-only) - see web/AGENTS.md; that is out of scope for the app docs here.

Surface 1 - desktop host UI

Tray entries, Control Center labels, pet status text, and other main-process strings.

• i18n/catalog.ts is the pure, dependency-free core: locale dictionaries, BCP-47 → supported-locale mapping, translate(), and brace interpolation ({name}). It’s pure so it can be unit-tested without Electron.
• i18n/index.ts is the Electron-aware layer: setLocaleFromPreference() maps "system" to app.getLocale() (or honors the user’s explicit choice), and getActiveMessages() returns the resolved dictionary.
• locales/<locale>.ts holds each dictionary; en.ts is the source of truth and the fallback for any missing key.
• The renderer hydrates via the openpets:get-i18n IPC hook in windows.ts, so the React UI renders in the active locale.

Locale preference is stored in app state and coordinated through app-state.ts. French covers every English host catalog key and all pet reaction types.

Surface 2 - pet reaction speech

What the pet says per reaction (see Pets).

• i18n/reactions/<locale>.ts provides localized message pools per reaction type; reactions/index.ts aggregates them.
• reaction-messages.ts picks a message from the pool for the active locale.

This keeps speech in the user’s language without coupling it to the host UI dictionary.

Surface 3 - plugins

Plugins localize their own manifest strings and runtime text.

• Manifests reference $t: keys for name, description, and config labels/descriptions; runtime code calls ctx.t(key, vars).
• plugin-i18n.ts loads each plugin’s locales/<locale>.json (flat, dotted keys) and resolves $t: and ctx.t() with English fallback.
• Every plugin must ship locales/en.json; the release validator fails on a missing one or an unresolved $t: in a catalog card (see Testing and validation and Plugin platform).

The locale-key audit for plugins is pnpm plugins:locales (scripts/check-plugin-locales.mjs), run as part of pnpm plugins:test. All official plugins ship French (locales/fr.json), including manifest and runtime text. The audit requires that file for every official plugin and checks its keys against English, just like other shipped locales. Community plugins are not required to ship French; their supplied locales still undergo key parity checks.

Fallback model (all surfaces)

1. Map the requested BCP-47 locale to a supported locale.
2. Look up the key in that locale.
3. On any miss (unknown locale, missing key), fall back to English.
4. Interpolate {var} tokens.

Nothing throws on a missing translation - it degrades to English. That is the contract; preserve it.

Adding a locale (desktop)

1. Add locales/<locale>.ts mirroring all keys in en.ts.
2. Add reactions/<locale>.ts with the reaction message pools and register it in reactions/index.ts.
3. Ensure the BCP-47 mapping in i18n/catalog.ts resolves the new locale.
4. Translate README.<locale>.md if you want parity with the others.
5. Add locales/<locale>.json to plugins you want covered (English remains the fallback). Every official plugin must retain complete French coverage.

Notes & known state

• Earlier project notes treated plugin i18n as “deferred”; it now exists and is enforced (plugin-i18n.ts, $t:, ctx.t(), plugins:locales). Treat plugin localization as a first-class requirement, not a future.
• Keep en.ts / en.json authoritative: add keys there first, then translate.