Internationalization — opt-in translations
English (en-US) is the default source locale. Do not create or update
additional locale catalogs unless the app's agent-native.config.ts lists them
under translations.locales.
Rule
Visible framework/template UI copy belongs in the app's i18n catalog, not
inline in components. When you add or edit UI text, update the English source
catalog first, then update only the locale catalogs listed in
translations.locales, and run the i18n guard.
Catalogs
Templates use app/i18n/:
en-US.ts is the canonical source tree and fallback.
- Other locale files keep the same non-plural keys and the same placeholders.
index.ts exports an AgentNativeI18nCatalog with English bundled and
non-English catalogs loaded by dynamic import.
Use BCP-47 filenames from the supported set: en-US, zh-CN, es-ES,
fr-FR, de-DE, ja-JP, ko-KR, pt-BR, hi-IN, ar-SA.
If an app only ships translations for a subset of that set, set
supportedLocales on the AgentNativeI18nCatalog to that subset. Without it,
<LanguagePicker /> lists every framework-supported locale regardless of
whether loadMessages can actually resolve it.
UI Pattern
- Wrap apps with
AppProviders i18n={{ catalog: i18nCatalog }}.
- Read strings with
useT() and keep keys stable.
- Apps expose a
/settings route without a sidebar item for it: Settings
opens from the account menu in the sidebar footer and from ⌘, (Ctrl+,
elsewhere). Core's Account › Preferences page already renders the Interface
language row (with Timezone; both are the per-user localization record, so
a change applies in every app); don't add a second picker to an app's
Settings page. Keep the header language icon only as a quick-access
shortcut.
- Don't add an "Agent settings" row to an app's settings page: the Agent
group's pages are part of Settings. Link to a page with
buildSettingsRoute(page, sub?), and localize the link's label.
- Settings copy follows the same rules: page and group labels are core
agentChat.settingsShell.* keys, and an app's own rows, areas, and search
entries take already translated strings from the app catalog.
- Use
useFormatters() for dates, numbers, relative time, and lists instead
of embedding formatted values in translation strings.
- Do not translate stable identifiers: action names, route names, enum values,
app-state keys, database values, protocol fields, env var names, or provider
names.
Plurals And Placeholders
Plural strings use i18next/CLDR suffixes. Do not force every locale to copy
English plural categories:
- English uses
_one and _other.
- Chinese and Japanese usually use
_other.
- Arabic uses
_zero, _one, _two, _few, _many, and _other.
Keep interpolation placeholders identical across locales, such as
{{count}}, {{name}}, or ICU-style {count} arguments.
RTL
New UI should be RTL-safe. Prefer logical CSS utilities/properties such as
ms-*, me-*, ps-*, pe-*, start-*, end-*, text-start, and
text-end when direction matters. Avoid hardcoded left/right positioning for
new localized UI unless it is genuinely physical.
Verification
Run:
pnpm guard:i18n-catalogs
For broader changes, also run the affected template tests and pnpm typecheck.
Machine translation is only a starting point; high-visibility strings need
human review.
1---2name: internationalization3description: >-4 How to add or edit localized UI copy in agent-native apps. Use when adding,5 removing, or changing user-visible interface text, prompts, toasts, labels,6 empty states, or date/number/list formatting. Apps opt in to additional7 locales from `agent-native.config.ts`.8scope: dev9metadata:10 source: https://skillmd.com/skills/builderio/internationalization11 internal: true12---1314# Internationalization — opt-in translations1516English (`en-US`) is the default source locale. Do not create or update17additional locale catalogs unless the app's `agent-native.config.ts` lists them18under `translations.locales`.1920## Rule2122Visible framework/template UI copy belongs in the app's i18n catalog, not23inline in components. When you add or edit UI text, update the English source24catalog first, then update only the locale catalogs listed in25`translations.locales`, and run the i18n guard.2627## Catalogs2829Templates use `app/i18n/`:3031- `en-US.ts` is the canonical source tree and fallback.32- Other locale files keep the same non-plural keys and the same placeholders.33- `index.ts` exports an `AgentNativeI18nCatalog` with English bundled and34 non-English catalogs loaded by dynamic import.3536Use BCP-47 filenames from the supported set: `en-US`, `zh-CN`, `es-ES`,37`fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN`, `ar-SA`.3839If an app only ships translations for a subset of that set, set40`supportedLocales` on the `AgentNativeI18nCatalog` to that subset. Without it,41`<LanguagePicker />` lists every framework-supported locale regardless of42whether `loadMessages` can actually resolve it.4344## UI Pattern4546- Wrap apps with `AppProviders i18n={{ catalog: i18nCatalog }}`.47- Read strings with `useT()` and keep keys stable.48- Apps expose a `/settings` route without a sidebar item for it: Settings49 opens from the account menu in the sidebar footer and from ⌘, (Ctrl+,50 elsewhere). Core's Account › Preferences page already renders the Interface51 language row (with Timezone; both are the per-user `localization` record, so52 a change applies in every app); don't add a second picker to an app's53 Settings page. Keep the header language icon only as a quick-access54 shortcut.55- Don't add an "Agent settings" row to an app's settings page: the Agent56 group's pages are part of Settings. Link to a page with57 `buildSettingsRoute(page, sub?)`, and localize the link's label.58- Settings copy follows the same rules: page and group labels are core59 `agentChat.settingsShell.*` keys, and an app's own rows, areas, and search60 entries take already translated strings from the app catalog.61- Use `useFormatters()` for dates, numbers, relative time, and lists instead62 of embedding formatted values in translation strings.63- Do not translate stable identifiers: action names, route names, enum values,64 app-state keys, database values, protocol fields, env var names, or provider65 names.6667## Plurals And Placeholders6869Plural strings use i18next/CLDR suffixes. Do not force every locale to copy70English plural categories:7172- English uses `_one` and `_other`.73- Chinese and Japanese usually use `_other`.74- Arabic uses `_zero`, `_one`, `_two`, `_few`, `_many`, and `_other`.7576Keep interpolation placeholders identical across locales, such as77`{{count}}`, `{{name}}`, or ICU-style `{count}` arguments.7879## RTL8081New UI should be RTL-safe. Prefer logical CSS utilities/properties such as82`ms-*`, `me-*`, `ps-*`, `pe-*`, `start-*`, `end-*`, `text-start`, and83`text-end` when direction matters. Avoid hardcoded left/right positioning for84new localized UI unless it is genuinely physical.8586## Verification8788Run:8990```bash91pnpm guard:i18n-catalogs92```9394For broader changes, also run the affected template tests and `pnpm typecheck`.95Machine translation is only a starting point; high-visibility strings need96human review.