Internationalization
DevelopmentinternationalizationInternationalization is an Agent Skill for development published in the BuilderIO/agent-native repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
How to add or edit localized UI copy in agent-native apps. Use when adding, removing, or changing user-visible interface text, prompts, toasts, labels, empty states, or date/number/list formatting.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/BuilderIO/agent-native/blob/HEAD/.agents/skills/internationalization/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/internationalization, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Internationalization
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, update existing locale catalogs, and run the i18n guard.
Catalogs
Templates use app/i18n/:
en-US.tsis the canonical source tree and fallback.- Other locale files keep the same non-plural keys and the same placeholders.
index.tsexports anAgentNativeI18nCatalogwith 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.
UI Pattern
- Wrap apps with
AppProviders i18n={{ catalog: i18nCatalog }}. - Read strings with
useT()and keep keys stable. - Sidebar apps should expose a
/settingsroute in the app sidebar. Put<LanguagePicker />in that settings page, usually in a Language or General section, and keep the header language icon only as a quick-access shortcut. - Settings pages should include an "Agent settings" row/card that calls
openAgentSettings()from@agent-native/core/clientto open the right agent sidebar's Settings tab. Localize the title, description, and button. - 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
_oneand_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.