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:
- Signed in:
AuthContextcallssetAppLanguage(user.language)whenever the profile's language changes, so the UI follows the saved value once it round-trips. - Signed out:
getSystemLanguage()maps the device's first locale withmatchLanguage.
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
countand 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 noIntl.PluralRules, sopluralRules.tsinstalls 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()) orIntlwithgetLocale(). Never hardcode a locale. Compact relative units (5m,3h) come from thetime.*namespace. - Errors: alerts and toasts show
localizeApiError(e, t, 'fallback.key'), never a rawError.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 rootlangfrom 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 callsI18nManager.forceRTLand 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*andborder*StartRadiusfor anything that should follow reading order. Physicalleft/rightstay 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 computedtextAlign) readsuseIsRTL(). - 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 setstextAlign. - Embedded user text: a handle, name or message inside a translated sentence goes through
bidiIsolate(i18n/direction.ts), so@noanever renders asnoa@. A sentence that can open with a Latin handle also setswritingDirectionfromuseIsRTL(). - Horizontal scroll math: web RTL scrollers report a negative x. Read offsets with
scrollFromStartand passscrollXFromStarttoscrollTo. 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 thebackstagenamespace. - 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?)fromutils/backstage/labels.ts, readingbackstage.<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.tsparses 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.
Cross-links¶
- State Management:
AuthContextsyncsuser.languageto i18n - Components: feature folders consume
useTranslation()throughout