edgeever/docs/i18n.md

Localization (i18n)

简体中文

Tracking issue: #606. Goal: adding a language is a catalog change, not a code change.

Where UI text lives

Surface	Source
Web, desktop renderer, API, browser extension	Shared catalogs in packages/shared/src/i18n/ (zh-CN.ts, en-US.ts, ja.ts, pl.ts, ru.ts) — the source of truth.
Desktop main process	apps/desktop/src/main/desktop-copy.mjs and desktop-menu.mjs keep their own tables keyed by the same codes (desktopLocales), because the main process cannot import the TS catalogs.
Android (apps/mobile), iOS (apps/ios)	Not migrated yet; follow-up PRs under #606.

Locale codes and helpers are in packages/shared/src/i18n/locales.ts: supportedLocales, matchSupportedLocale, resolveSupportedLocale, localeEnglishNames (English names used in AI prompts such as "Reply in Polish").

Rule

Resolve a locale code, then read text from the catalog. Do not compare language strings in code (if (lang === "zh-CN") ...). Format dates and numbers with Intl using the locale code.

packages/shared/src/i18n/hardcoded-locale-guard.test.mjs rejects new hard-coded language comparisons outside i18n code. It has an explicit allowlist for content-language logic, such as subtitle tracks, sample data, and docs that exist only in some languages.

Adding a language

1. In locales.ts: add the code to supportedLocales, a branch in matchSupportedLocale (e.g. xx / xx-*), and an entry in localeEnglishNames.
2. Add packages/shared/src/i18n/<code>.ts with every key. catalog.test.mjs enforces key parity across locales.
3. Export it from packages/shared/src/i18n/index.ts and add ./i18n/<code> to exports in packages/shared/package.json.
4. Web: add apps/web/src/i18n/resources/<code>.ts (re-export), load it lazily in apps/web/src/i18n/index.ts (isOptionalLocale, loadOptionalCatalog, fallbackLng), and add a label in localeLabels (apps/web/src/i18n/locales.ts).
5. Desktop main: add the code to desktopLocales and its entries to the tables in desktop-copy.mjs and desktop-menu.mjs.
6. Run the tests: bun test packages/shared/src/i18n, then bun run typecheck.

Adding a string

Add the key to all five catalogs in the same change. The parity test fails if any catalog is missing it. Strings shown by the desktop main process go into its tables instead, again for every code.