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_LOADERSinsrc/i18n/catalogs.ts, arequire()inside a function). Metro evaluates a module on its firstrequire, 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 dynamicimport()each).
Configuration highlights:
lngandfallbackLngare bothen;supportedLngsis derived fromSUPPORTED_LANGUAGES.interpolation.escapeValue: false(React already escapes) andreturnNull: false(a missing key yields a string, nevernull).- The root layout imports
@/i18nfor its side effect. TheLanguageProviderapplies 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 mostLANGUAGE_WAIT_MS; see Language selection). - Every switch goes through
switchLanguage(code).ensureLanguageloads the catalog first when it isn't in yet (addResourceBundle), thenchangeLanguageruns. 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.tsholds 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/:
| Code | Label |
|---|---|
en | English (the source-of-truth catalog and the runtime fallback) |
es | Español |
fr | Français |
de | Deutsch |
pt | Português |
it | Italiano |
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:
- A persisted explicit preference wins (
resolveLanguage(pref)returns it unchanged). 'system'walks the device's preferred locales (Localization.getLocales(), in the user's OS-level preference order) and picks the first supportedlanguageCode.- 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.tsaugments i18next'sCustomTypeOptionswithtypeof enfromlocales/en.json, sot('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.tsassert 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
- Add the key to
src/i18n/locales/en.jsonfirst. That updates the type union, sot()calls compile. - Use it via
useTranslation()in components (const { t } = useTranslation()) ori18n.t(...)outside React. - 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.
- Create the UI catalog:
src/i18n/locales/<code>.json, translated fromen.json(same key structure). - Register it in three places:
- Add
{ code, label }toSUPPORTED_LANGUAGESinsrc/i18n/index.ts. The label is the language's own name; it appears untranslated in the picker. - Give it a loader in
CATALOG_LOADERSin bothsrc/i18n/catalogs.ts(native, arequire()) andsrc/i18n/catalogs.web.ts(web, animport()). - Add its "Fell asleep" note to
FELL_ASLEEP_NOTESinsrc/i18n/fell-asleep-notes.ts.
- Add
- Create the native-metadata file:
assets/locales/<code>.json. This is a different shape from the UI catalog. It holds the OS-level strings: iOSCFBundleDisplayNameandNSCameraUsageDescription(the QR-scanner permission prompt), and Androidapp_name. - Register it in
app.jsonunderexpo.locales("<code>": "./assets/locales/<code>.json"). This list deliberately omitsen, because English is the development language baked into the native projects.CFBundleAllowMixedLocalizationsis already set on iOS. - Run the full gate.
language.test.tsexercises detection and catalog switching, and the typecheck catches structural drift inen.jsonconsumers.
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
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,monthandyear(_oneand_other); yesterday,lastMonthandlastYearfor one day, month or year, asnumeric: '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.