Skip to main content

Internationalisation

The player's UI is localised with i18next + react-i18next, with device language detection via expo-localization. Everything lives in src/i18n/.

Setup (src/i18n/index.ts)​

i18next is initialised synchronously at import time from the bundled catalogs (BUNDLED_CATALOGS), so the instance is ready before the first useTranslation call. Only English is in from the start, on every platform. The other catalogs load differently per platform:

  • Native keeps them in its one bundle but runs each only when it is first used (CATALOG_LOADERS in src/i18n/catalogs.ts, a require() inside a function). Metro evaluates a module on its first require, so a cold start evaluates English alone.
  • The web (catalogs.web.ts) loads each one as its own chunk when it is the language in use (CATALOG_LOADERS, a dynamic import() each).

Configuration highlights:

  • lng and fallbackLng are both en; supportedLngs is derived from SUPPORTED_LANGUAGES.
  • interpolation.escapeValue: false (React already escapes) and returnNull: false (a missing key yields a string, never null).
  • The root layout imports @/i18n for its side effect. The LanguageProvider applies the real language afterwards. Until then the app renders under the fallback, and the provider holds first paint until the language is applied (on the web for at most LANGUAGE_WAIT_MS; see Language selection).
  • Every switch goes through switchLanguage(code). ensureLanguage loads the catalog first when it isn't in yet (addResourceBundle), then changeLanguage runs. The last switch asked for wins: a switch still loading its catalog when another is asked for never applies. A catalog that can't be loaded (offline, never cached) leaves that language's strings in English.
  • A string needed in every language at once can't be read from the catalogs, because only English and the language in use are loaded, on every platform. Such a string has its own table: FELL_ASLEEP_NOTES (fell-asleep-notes.ts, the sleep timer's automatic bookmark note). fell-asleep-notes.test.ts holds it to the catalogs.

src/i18n/locale.ts exposes getLocale(), the active BCP-47 code for Intl formatting. It is the UI language from the i18next singleton with the device's region for that language (regionalLocale, from 2.7.0): the first of the device's locales (expo-localization's getLocales()) in that language that names a region, as Intl.DateTimeFormat.supportedLocalesOf returns it (the bare language when Intl refuses that one; later locales aren't tried), so English on a British phone is en-GB ("12 Nov 2026") and on an American one en-US ("Nov 12, 2026"). A UI language that isn't the device's keeps its own conventions (German chosen on an English phone reads German dates). The device's locales are read once per UI language. It is a separate module so that locale-aware formatters (src/lib/format.ts) don't pull React into their dependency graph.

Available languages​

SUPPORTED_LANGUAGES currently ships six catalogs in src/i18n/locales/:

CodeLabel
enEnglish (the source-of-truth catalog and the runtime fallback)
esEspañol
frFrançais
deDeutsch
ptPortuguês
itItaliano

All are LTR; there is no RTL handling yet. The in-app Settings language picker derives its options from this list, so adding an entry here is what surfaces it in the UI.

Language selection (src/i18n/language-provider.tsx)​

The user preference is 'system' (default) or a concrete code, persisted under audiosilo.language in AsyncStorage. Resolution order:

  1. A persisted explicit preference wins (resolveLanguage(pref) returns it unchanged).
  2. 'system' walks the device's preferred locales (Localization.getLocales(), in the user's OS-level preference order) and picks the first supported languageCode.
  3. When nothing is supported, the language is en.

LanguageProvider restores the preference and applies it via switchLanguage(...) before first paint. Children render only after hydration, mirroring the ThemeProvider pattern. It exposes { pref, language, setPref } through useLanguage(). A failed storage read falls back to the default language rather than blocking first paint.

The wait is capped at LANGUAGE_WAIT_MS (1.5 s). On the web, a saved language other than English loads its chunk first, and a slow or failing fetch must not hold the app blank. Past the cap, the app paints in English and switches when the chunk lands. Native's switch is immediate, because its catalog is required from the bundle.

Outside React, restoreLanguage() applies the same preference as a launch step (bootstrapPlayback, src/lib/bootstrap.ts), so the car's headless task on Android, which has no LanguageProvider, writes the car snapshot's labels in the listener's language too.

Key conventions​

Keys are namespaced by surface, matching the top-level objects in en.json: common, settings, account, connect, home, library, downloads, search, book, player, reconnect, nav, ui, demo, shell, palette, covers, queue, upnext, series, people, annotations (bookmark and note rows, editors and labels) and journal. For example: t('settings.title'), t('common.cancel').

Two mechanisms keep keys correct:

  • Typed keys. src/i18n/i18next.d.ts augments i18next's CustomTypeOptions with typeof en from locales/en.json, so t('settings.titel') is a compile error. Only the English catalog is type-checked; the others may lag behind it.
  • Runtime fallback. A key missing from the active catalog resolves to the English string, never the raw key. The catalog-switching tests in src/i18n/language.test.ts assert this. They register a deliberately partial throwaway locale to exercise the fallback.

There is no automated parity check between the catalogs. The shipped ones are currently complete; check with a quick diff of flattened keys when you touch them. English-first plus the runtime fallback keeps a lagging translation harmless rather than breaking.

Adding strings​

  1. Add the key to src/i18n/locales/en.json first. That updates the type union, so t() calls compile.
  2. Use it via useTranslation() in components (const { t } = useTranslation()) or i18n.t(...) outside React.
  3. Translate it in the other five catalogs in the same change where practical. A missing translation falls back to English at runtime, so a lagging catalog still works. Don't lean on that as a workflow.

Adding a language, step by step​

The UI catalogs and the native-metadata files are two separate, hand-maintained lists, and you must touch both. The comment block above SUPPORTED_LANGUAGES exists because this was missed once.

  1. Create the UI catalog: src/i18n/locales/<code>.json, translated from en.json (same key structure).
  2. Register it in three places:
    • Add { code, label } to SUPPORTED_LANGUAGES in src/i18n/index.ts. The label is the language's own name; it appears untranslated in the picker.
    • Give it a loader in CATALOG_LOADERS in both src/i18n/catalogs.ts (native, a require()) and src/i18n/catalogs.web.ts (web, an import()).
    • Add its "Fell asleep" note to FELL_ASLEEP_NOTES in src/i18n/fell-asleep-notes.ts.
  3. Create the native-metadata file: assets/locales/<code>.json. This is a different shape from the UI catalog. It holds the OS-level strings: iOS CFBundleDisplayName and NSCameraUsageDescription (the QR-scanner permission prompt), and Android app_name.
  4. Register it in app.json under expo.locales ("<code>": "./assets/locales/<code>.json"). This list deliberately omits en, because English is the development language baked into the native projects. CFBundleAllowMixedLocalizations is already set on iOS.
  5. Run the full gate. language.test.ts exercises detection and catalog switching, and the typecheck catches structural drift in en.json consumers.

The new language now shows in the Settings language picker. Steps 3 and 4 need a native rebuild to take effect, because they are prebuild inputs, not JS.

The Hermes Intl caveat​

CI cannot catch this class of crash

tsc, Jest (Node), and the web build all run on engines with full Intl. The iOS and Android runtime is Hermes, which ships Intl.NumberFormat and Intl.DateTimeFormat but not Intl.RelativeTimeFormat, Intl.ListFormat or Intl.Segmenter. An unguarded new Intl.RelativeTimeFormat(...) passes every gate and then hard-crashes on device. This has happened: the home "recently added" shelf crashed on device while CI was green. See the workspace CODE-HEALTH.md for the incident write-up.

The project rule: feature-detect any non-core Intl API and provide a fallback. The canonical example is formatRelative in src/lib/format.ts:

const rtf =
typeof Intl !== 'undefined' && typeof Intl.RelativeTimeFormat === 'function'
? new Intl.RelativeTimeFormat(locale, { numeric: 'auto' })
: null;
// … rtf ? rtf.format(-n, unit) : relativeFromStrings(n, unit, locale)

Where there is no Intl.RelativeTimeFormat (Hermes), relativeFromStrings words the time from the app's own strings, passing the locale as lng. The strings are common.ago.* in every language:

  • now;
  • plural second, minute, hour, day, month and year (_one and _other);
  • yesterday, lastMonth and lastYear for one day, month or year, as numeric: 'auto' says them.

Native relative times therefore read in the app's language ("il y a 3 heures", "hier") with no dependency. Hermes has no Intl.PluralRules either, so i18next falls back to _one for 1 and _other otherwise. That is right for these counts: they are never 0, and a single day, month or year has its own words.

Intl.NumberFormat and Intl.DateTimeFormat are safe to use directly (see formatBytes). If localised lists, or plural rules beyond one and other, ever become a requirement on native, the sanctioned path is adding the @formatjs/intl-* polyfills plus locale data, not removing the guards.

All Intl formatting should take its locale from getLocale(), or accept a locale parameter defaulting to it, so number and date formatting follows the active UI language and the device's region for it.