Skip to content

Localization

The app UI ships in 27 languages through i18next + react-i18next. Members pick a language in Hub → Preferences; before sign-in the device language decides.

Supported languages

LANGUAGES in frontend/i18n/languages.ts is the single list: en-US, ja-JP, zh-CN, zh-TW, es, hi, pt, ar, ru, fr, de, ko, vi, id, tr, it, th, pl, nl, uk, sv, he, el, cs, da, fi, no. The picked code is saved unchanged as the user's language, and the backend localizes emails from the same list.

Code Notes
en-US Source of truth and fallback for every missing key
pt Brazilian Portuguese
no Norwegian Bokmål
zh-CN / zh-TW Simplified / Traditional (Taiwan usage), kept distinct
ar, he Right to left (rtl: true in LANGUAGES)

Product terms and the register each language uses (tú, du, вы, です・ます…) are recorded in frontend/i18n/glossary.md.

Bundle layout

frontend/i18n/
  languages.ts        LANGUAGES, matchLanguage, isRTL
  bundles.ts          lazy loader per non-English language
  index.ts            i18next init, setAppLanguage, getSystemLanguage
  pluralRules.ts      Intl.PluralRules for runtimes without it (Hermes)
  displayNames.ts     country and currency names for the Intl.DisplayNames polyfill (Hermes)
  backstage.json      Backstage UI strings, English only
  glossary.md         terms and register per language
  locales/<code>/     one folder per language
    auth.json capture.json chat.json common.json discover.json event.json
    hub.json map.json plan.json profile.json website.json
    index.ts          spreads the area files into one tree

Each area file holds a few top-level namespaces (chat.json has chat and link_preview), so keys stay plain dot paths: t('chat.settings.title'). Every locale folder has the same files, namespaces and index.ts.

Loading

English is bundled; every other language loads on demand through a small i18next backend over BUNDLES. On web each language is its own chunk, so a member downloads English plus their own language (about 20 to 25 KB gzipped each). Native bundles include every language but evaluate only the one in use.

Language resolution:

  1. Signed in: AuthContext calls setAppLanguage(user.language) whenever the profile's language changes, so the UI follows the saved value once it round-trips.
  2. Signed out: getSystemLanguage() maps the device's first locale with matchLanguage.

matchLanguage tries the exact code, then the base language (pt-BR → pt, es-MX → es, nb/nn → no, legacy iw → he, in → id). Chinese picks the script first (Hant → zh-TW, Hans → zh-CN), then the region (TW, HK, MO → zh-TW), else zh-CN. Anything else is en-US.

Usage

const { t } = useTranslation();
<Button title={t('auth.login.submit')} />
t('plan.list.ideas', { count })        // picks the plural form

Outside React, import the singleton: import i18n from '@/i18n'; i18n.t('common.error').

  • Plurals: pass count and let i18next choose. Each bundle carries exactly the CLDR categories of its language (Arabic zero/one/two/few/many/other; Russian, Ukrainian, Polish, Czech one/few/many/other; French, Spanish, Italian, Portuguese one/many/other; CJK, Korean, Thai, Vietnamese, Indonesian other). Hermes has no Intl.PluralRules, so pluralRules.ts installs CLDR rules for these languages when it is missing; a test checks them against ICU.
  • Dates, times, numbers: format through utils/date.ts (getLocale(), formatTime, formatRelativeTime, ago, formatDuration, dateFnsLocale()) or Intl with getLocale(). Never hardcode a locale. Compact relative units (5m, 3h) come from the time.* namespace.
  • Errors: alerts and toasts show localizeApiError(e, t, 'fallback.key'), never a raw Error.message.

Right to left

Arabic and Hebrew mirror the layout on iOS, Android and web: rows run right to left, start/end styles flip, and directional icons (chevrons, arrows, send) render mirrored through VectorIcon. Each text block still infers its own direction (dir="auto" on web, first-strong detection on native), so a Latin name inside an Arabic screen reads correctly.

  • Web sets <html dir> and a root lang from the app language (components/layout/LayoutDirectionRoot.tsx), so a language change mirrors live.
  • Native fixes direction at startup. syncNativeDirection (i18n/direction.ts) runs once the stored profile has loaded and on every language change; when the direction differs it calls I18nManager.forceRTL and reloads the app. It records the attempted direction first; if the next launch still has the old direction, it logs once and carries on instead of reloading again, and it clears the record once the layout matches.
  • Styles: use marginStart/marginEnd, paddingStart/paddingEnd, start/end, borderStart* and border*StartRadius for anything that should follow reading order. Physical left/right stay physical on every platform (swapLeftAndRightInRTL(false) on native), for geometry that must not flip: camera overlays, map markers, measured popover positions, swipe and slider tracks.
  • Code that needs the direction (a transformOrigin, a computed textAlign) reads useIsRTL().
  • Alignment on web: a text block keeps its own reading order but aligns to the layout start in RTL (a global rule in constants/webGlobalCss.ts), unless the component sets textAlign.
  • Embedded user text: a handle, name or message inside a translated sentence goes through bidiIsolate (i18n/direction.ts), so @noa never renders as noa@. A sentence that can open with a Latin handle also sets writingDirection from useIsRTL().
  • Horizontal scroll math: web RTL scrollers report a negative x. Read offsets with scrollFromStart and pass scrollXFromStart to scrollTo. Maps stay LTR (the web map container and native marker overlays), since marker anchors are physical.

Fonts

Bricolage Grotesque covers every Latin-script language, Vietnamese included. Greek, Cyrillic, Arabic, Hebrew, Devanagari, Thai, Hangul and CJK render through the platform's per-glyph fallback fonts (iOS cascade list, Android system fallback, the browser's script defaults).

Help center

Help articles are written in English (frontend/content/help/<slug>.md plus manifest.json). Each translated language is one optional file, frontend/content/help/i18n/<code>.md, holding that language's category titles and, per article, a === <slug> block with summary:, keywords: and the body (its # line is the title). hooks/useHelpCatalog.ts lazy-loads the file for the app language (its own chunk on web, like the bundles) and overlays it on English per article and per field, so a missing article or line shows English. Search runs over the translated text plus the English keywords.

Shipped today: ja-JP, zh-CN, zh-TW, ko, es, fr, de, pt. __tests__/constants/helpTranslations.test.ts fails on a translated slug or category that no longer exists and on links that differ from the English article, and warns with the untranslated articles per language. Writing and adding a language: the help-content skill.

Not localized

  • Backstage UI: English only, strings in i18n/backstage.json; Backstage screens use only the backstage namespace.
  • Backend-provided ids shown in Backstage (switches, queues, task types, audit resource types, data console entities, fields and values, enums) are labelled client-side with bl(t, group, id, fallback?) from utils/backstage/labels.ts, reading backstage.<group>.<id> (dots and colons in an id become underscores). A missing label falls back to the server's label where one exists, else a humanized id, never a raw key. __tests__/i18n/backstageLabels.test.ts parses the Go sources and fails when a new switch, task, queue, data field or enum value has no label.
  • Legal policies: English.
  • Server data: place categories, city names.

Checks

frontend/__tests__/i18n/locales.test.ts (part of npx vitest run) fails when a bundle is missing or has extra keys, lacks or adds a plural form, drops or renames a {{variable}} or tag, has empty strings, is mostly English, or when a t() key in code is undefined. It also checks that every LANGUAGES code has a folder and a loader, and the Backstage rules. For sweeps (hardcoded strings, unused keys) use the locale-reconcile skill.

Currency

Amounts arrive from the API as integer minor units plus an ISO 4217 code (see Currency). Never divide by 100 in a component: route display and input through utils/currency.ts, which reads each currency's exponent from the generated constants/currencies.ts.

Helper Use
formatAmount(amountMinor, currency, { locale, compact, currencyDisplay, signDisplay }) Display. Intl.NumberFormat in the app language (getLocale()): JPY shows no decimals, BHD three, and a whole amount uses the locale's usual decimals while any other keeps every minor-unit digit. compact abbreviates totals of 10,000 major units or more ("$1.2M", "¥12.3億"). Negative zero renders as zero.
parseAmountInput(text, currency, { locale, allowNegative }) Typed input to minor units. Accepts the locale's digits and separators, ASCII and full-width digits, and a stray currency symbol. A lone separator followed by three digits is grouping for currencies with fewer than three decimals (1.500 in de is 1,500), otherwise it is the decimal point (12.50 in de is 12.50). Returns { ok: false, error } for empty, invalid, negative, too_precise (more decimals than the currency has) and too_large.
formatAmountInput(amountMinor, currency, locale) Prefill an amount field: localized digits and decimal, no grouping, no symbol. Round-trips through parseAmountInput.
currencyName, currencySymbol, listCurrencies Names and symbols from Intl.DisplayNames and Intl.NumberFormat, so every language gets CLDR names with no locale-file strings. The English ISO name is the fallback when the runtime has no data.
suggestCurrencies, currencyForRegion, isCurrencyCode Picker ordering, region default, wire-value guard.
approxConversion(amountMinor, from, to, rate, options), convertMinor An amount in another currency at a reference rate (a decimal string the consuming domain returns alongside the amount), rounded half to even with exact integer math: "≈ $29.00". Returns undefined without a usable rate or for the same currency, so the caller hides the line. Display only; never send the result back as an amount. See Currency → Conversion.

components/forms/CurrencyPicker is the one currency chooser: a searchable SelectionSheet with a Suggested section (the current value, the caller's recent codes, the device currency, then common ones) above every active currency sorted by localized name. Search matches the localized name, the code and the symbol. Hub → Preferences uses it for Primary Currency (user.primary_currency, always set by the server).

Hermes has no Intl.DisplayNames, so i18n/index.ts installs a polyfill fed by i18n/displayNames.ts: CLDR country and currency names for every language in LANGUAGES (displayNames.json, generated by scripts/gen/gen-display-names.mjs). A test checks every language resolves to its own names and matches ICU.