@agent-native/core 0.75.5 → 0.76.0

package/docs/content/locales/ja-JP/internationalization.md

@@ -0,0 +1,114 @@
+---
+title: "国際化"
+description: "共有 locale カタログ、言語ピッカー、ブラウザー言語フォールバック、locale 対応 docs コンテンツで Agent Native アプリをローカライズします。"
+---
+
+# 国際化
+
+Agent Native アプリは共有ランタイム `@agent-native/core/client/i18n` を通じて、フレームワークとテンプレートの UI をローカライズできます。フレームワークはユーザーの言語選択を SQL settings に保存し、それを actions として公開し、アプリがまだ翻訳していない文字列は English にフォールバックします。
+
+## ランタイム {#runtime}
+
+`AppProviders` から provider を使います。
+
+```tsx
+import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
+import { i18nCatalog } from "./i18n";
+
+const LOCALE_INIT_SCRIPT = getLocaleInitScript();
+
+<script
+  data-agent-native-locale-init
+  dangerouslySetInnerHTML={{ __html: LOCALE_INIT_SCRIPT }}
+/>;
+
+<AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+  <Outlet />
+</AppProviders>;
+```
+
+`getLocaleInitScript()` は React の hydration 前に初期 `lang`、`dir`、`window.__AGENT_NATIVE_LOCALE__` を設定します。公開 SSR ルートでは `@agent-native/core/server` の `resolveLocaleFromRequest()` を呼び、解決された locale/catalog をこの script に渡すことで hydration mismatch を避けられます。
+
+## カタログ {#catalogs}
+
+ローカライズされた各テンプレートは `app/i18n/` にカタログを置きます。
+
+```ts
+// app/i18n/index.ts
+import enUS from "./en-US";
+import type { AgentNativeI18nCatalog } from "@agent-native/core/client";
+
+export const i18nCatalog = {
+  sourceLocale: "en-US",
+  messages: enUS,
+  loadMessages: async (locale) => {
+    switch (locale) {
+      case "zh-CN":
+        return (await import("./zh-CN")).default;
+      default:
+        return null;
+    }
+  },
+} satisfies AgentNativeI18nCatalog;
+```
+
+`en-US` は必ずバンドルします。English 以外のカタログは動的 import にして、ユーザーが現在の locale だけをダウンロードするようにします。対応する locale codes は `en-US`、`zh-CN`、`es-ES`、`fr-FR`、`de-DE`、`ja-JP`、`ko-KR`、`pt-BR`、`hi-IN`、`ar-SA` です。
+
+## UI {#ui}
+
+インターフェイス文字列には `useT()` を使い、アプリの `/settings` ページに `<LanguagePicker />` を置きます。サイドバーを持つアプリは、アプリのサイドバーに **Settings** を表示してください。ヘッダーの言語アイコンはショートカットです。
+
+```tsx
+import {
+  LanguagePicker,
+  openAgentSettings,
+  useT,
+} from "@agent-native/core/client";
+
+function SettingsPage() {
+  const t = useT();
+  return (
+    <>
+      <h2>{t("settings.languageTitle")}</h2>
+      <LanguagePicker label={t("settings.languageLabel")} />
+
+      <h2>{t("settings.agentTitle")}</h2>
+      <p>{t("settings.agentDescription")}</p>
+      <button type="button" onClick={() => openAgentSettings()}>
+        {t("settings.openAgentSettings")}
+      </button>
+    </>
+  );
+}
+```
+
+「Agent settings」コントロールは、モデル、API キー、自動化、音声などの framework-level controls のために、右側の agent sidebar の Settings tab を開くべきです。その設定がアプリの中心的な体験なら、アプリ自身の settings page に重要な framework 設定を重複表示してもかまいません。ただし source of truth は sidebar settings tab です。
+
+日付、数値、相対時間、リストには `useFormatters()` を使います。locale に依存する日付や数値の整形を翻訳文字列の中に入れないでください。
+
+## Docs サイトのコンテンツ {#docs-site-content}
+
+公開 docs ページは同じ core provider を使いますが、`persistPreference={false}` にして匿名 docs トラフィックが SQL settings actions ではなく localStorage とブラウザー言語を使うようにします。English のソースは `packages/core/docs/content/*.md` に残ります。ローカライズされたページ override は `packages/core/docs/content/locales/<locale>/<slug>.md` に置きます。
+
+アプリのカタログと同じ BCP-47 locale codes を使ってください。English ソースと同じ slug を維持し、翻訳された見出しでは `{#anchor}` で安定したアンカーを保ち、routes、action names、protocol fields、env vars、provider names は翻訳しません。ある locale に翻訳 Markdown がないページは English にフォールバックしつつ、ナビゲーションと chrome はローカライズされます。
+
+## Actions と永続化 {#actions-and-persistence}
+
+すべてのアプリは以下を継承します。
+
+- `get-localization-preference` — 現在のユーザーの `{ locale }` を読む
+- `set-localization-preference` — `"system"` または対応 locale を設定する
+
+永続値はユーザー単位の SQL settings の `localization` に保存されます。`localStorage` は pre-hydration と匿名フォールバックにだけ使います。アクティブな locale は application state に環境コンテキストとして反映されるため、agents は現在の UI 言語を確認できます。
+
+## Guard {#guard}
+
+実行:
+
+```bash
+pnpm guard:i18n-catalogs
+```
+
+guard は対応 locale ファイル名、key parity、placeholder parity、stale keys、`Intl.PluralRules` による CLDR plural categories を検証します。構造を検証するもので、翻訳品質は検証しません。目立つ文字列は人によるレビューが必要です。
+
+action names、routes、enum values、app-state keys、database values、protocol fields、env var names、provider names などの安定した識別子は翻訳しないでください。

package/docs/content/locales/ko-KR/internationalization.md

@@ -0,0 +1,102 @@
+---
+title: "국제화"
+description: "공유 locale 카탈로그, 언어 선택기, 브라우저 언어 fallback, locale-aware docs 콘텐츠로 Agent Native 앱을 현지화합니다."
+---
+
+# 국제화
+
+Agent Native 앱은 공유 `@agent-native/core/client/i18n` 런타임으로 framework 및 template UI를 현지화할 수 있습니다. framework는 사용자의 언어 선택을 SQL settings에 저장하고 actions로 노출하며, 앱에 번역되지 않은 문자열이 있으면 English로 fallback합니다.
+
+## 런타임 {#runtime}
+
+`AppProviders`를 통해 provider를 사용합니다.
+
+```tsx
+import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
+import { i18nCatalog } from "./i18n";
+
+const LOCALE_INIT_SCRIPT = getLocaleInitScript();
+
+<script
+  data-agent-native-locale-init
+  dangerouslySetInnerHTML={{ __html: LOCALE_INIT_SCRIPT }}
+/>;
+
+<AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+  <Outlet />
+</AppProviders>;
+```
+
+`getLocaleInitScript()`는 React hydration 전에 초기 `lang`, `dir`, `window.__AGENT_NATIVE_LOCALE__`를 설정합니다. 공개 SSR route는 `@agent-native/core/server`에서 `resolveLocaleFromRequest()`를 호출하고 해결된 locale/catalog를 script에 전달해 hydration mismatch를 피할 수 있습니다.
+
+## 카탈로그 {#catalogs}
+
+현지화된 각 template은 `app/i18n/` 아래에 카탈로그를 둡니다.
+
+```ts
+// app/i18n/index.ts
+import enUS from "./en-US";
+import type { AgentNativeI18nCatalog } from "@agent-native/core/client";
+
+export const i18nCatalog = {
+  sourceLocale: "en-US",
+  messages: enUS,
+  loadMessages: async (locale) => {
+    switch (locale) {
+      case "zh-CN":
+        return (await import("./zh-CN")).default;
+      default:
+        return null;
+    }
+  },
+} satisfies AgentNativeI18nCatalog;
+```
+
+항상 `en-US`를 bundle에 포함하세요. English가 아닌 카탈로그는 dynamic import로 불러와 사용자가 활성 locale만 다운로드하게 합니다. 지원 locale codes는 `en-US`, `zh-CN`, `es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN`, `ar-SA`입니다.
+
+## UI {#ui}
+
+인터페이스 문자열에는 `useT()`를 사용하고 settings에는 `<LanguagePicker />`를 둡니다.
+
+```tsx
+import { LanguagePicker, useT } from "@agent-native/core/client";
+
+function SettingsLanguageCard() {
+  const t = useT();
+  return (
+    <>
+      <h2>{t("settings.languageTitle")}</h2>
+      <LanguagePicker label={t("settings.languageLabel")} />
+    </>
+  );
+}
+```
+
+날짜, 숫자, 상대 시간, 목록에는 `useFormatters()`를 사용하세요. locale에 민감한 날짜나 숫자 formatting을 번역 문자열 안에 넣지 마세요.
+
+## Docs 사이트 콘텐츠 {#docs-site-content}
+
+공개 docs 페이지는 같은 core provider를 사용하지만 `persistPreference={false}`로 설정해 익명 docs 트래픽이 SQL settings actions가 아니라 localStorage와 브라우저 언어를 사용하게 합니다. English 원본은 `packages/core/docs/content/*.md`에 남습니다. 현지화된 페이지 override는 `packages/core/docs/content/locales/<locale>/<slug>.md`에 둡니다.
+
+앱 카탈로그와 같은 BCP-47 locale codes를 사용하세요. English 원본과 같은 slug를 유지하고, 번역된 heading에는 `{#anchor}`로 안정적인 anchor를 보존하며, routes, action names, protocol fields, env vars, provider names는 번역하지 마세요. 특정 locale에 번역 Markdown이 없으면 그 페이지는 English로 fallback하고 navigation과 chrome은 계속 현지화됩니다.
+
+## Actions 및 지속성 {#actions-and-persistence}
+
+모든 앱은 다음을 상속합니다.
+
+- `get-localization-preference` — 현재 사용자의 `{ locale }` 읽기
+- `set-localization-preference` — `"system"` 또는 지원 locale 설정
+
+지속 값은 user-scoped SQL settings의 `localization`에 저장됩니다. `localStorage`는 pre-hydration과 익명 fallback에만 사용됩니다. 활성 locale은 ambient context로 application state에 반영되어 agents가 현재 UI 언어를 볼 수 있습니다.
+
+## Guard {#guard}
+
+실행:
+
+```bash
+pnpm guard:i18n-catalogs
+```
+
+guard는 지원 locale filename, key parity, placeholder parity, stale keys, 그리고 `Intl.PluralRules`를 통한 CLDR plural categories를 검증합니다. 구조만 확인하며 번역 품질은 확인하지 않습니다. 노출도가 높은 문자열은 사람의 검토가 필요합니다.
+
+action names, routes, enum values, app-state keys, database values, protocol fields, env var names, provider names 같은 안정적인 식별자는 번역하지 마세요.

package/docs/content/locales/pt-BR/internationalization.md

@@ -0,0 +1,102 @@
+---
+title: "Internacionalização"
+description: "Localize apps Agent Native com catálogos compartilhados, seletor de idioma, fallback do navegador e conteúdo de docs por locale."
+---
+
+# Internacionalização
+
+Apps Agent Native podem localizar a UI do framework e dos templates com o runtime compartilhado `@agent-native/core/client/i18n`. O framework armazena a escolha de idioma do usuário em settings SQL, expõe essa preferência como actions e volta para English quando uma app ainda não traduziu uma string.
+
+## Runtime {#runtime}
+
+Use o provider por meio de `AppProviders`:
+
+```tsx
+import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
+import { i18nCatalog } from "./i18n";
+
+const LOCALE_INIT_SCRIPT = getLocaleInitScript();
+
+<script
+  data-agent-native-locale-init
+  dangerouslySetInnerHTML={{ __html: LOCALE_INIT_SCRIPT }}
+/>;
+
+<AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+  <Outlet />
+</AppProviders>;
+```
+
+`getLocaleInitScript()` define o `lang`, `dir` e `window.__AGENT_NATIVE_LOCALE__` iniciais antes da hydration do React. Rotas SSR públicas podem chamar `resolveLocaleFromRequest()` de `@agent-native/core/server` e passar o locale/catalog resolvido para o script, evitando divergências de hydration.
+
+## Catálogos {#catalogs}
+
+Cada template localizado mantém catálogos em `app/i18n/`:
+
+```ts
+// app/i18n/index.ts
+import enUS from "./en-US";
+import type { AgentNativeI18nCatalog } from "@agent-native/core/client";
+
+export const i18nCatalog = {
+  sourceLocale: "en-US",
+  messages: enUS,
+  loadMessages: async (locale) => {
+    switch (locale) {
+      case "zh-CN":
+        return (await import("./zh-CN")).default;
+      default:
+        return null;
+    }
+  },
+} satisfies AgentNativeI18nCatalog;
+```
+
+Sempre inclua `en-US` no bundle. Importe dinamicamente catálogos que não sejam English para que usuários baixem apenas o locale ativo. Os locale codes suportados são `en-US`, `zh-CN`, `es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN` e `ar-SA`.
+
+## UI {#ui}
+
+Use `useT()` para textos de interface e `<LanguagePicker />` em settings:
+
+```tsx
+import { LanguagePicker, useT } from "@agent-native/core/client";
+
+function SettingsLanguageCard() {
+  const t = useT();
+  return (
+    <>
+      <h2>{t("settings.languageTitle")}</h2>
+      <LanguagePicker label={t("settings.languageLabel")} />
+    </>
+  );
+}
+```
+
+Use `useFormatters()` para datas, números, tempo relativo e listas. Não coloque formatação sensível a locale dentro de strings traduzidas.
+
+## Conteúdo do site de docs {#docs-site-content}
+
+Páginas públicas de docs usam o mesmo core provider, mas com `persistPreference={false}` para que tráfego anônimo use localStorage e o idioma do navegador em vez de actions de settings SQL. A fonte English continua em `packages/core/docs/content/*.md`. Overrides localizados ficam em `packages/core/docs/content/locales/<locale>/<slug>.md`.
+
+Use os mesmos BCP-47 locale codes dos catálogos de app. Mantenha o mesmo slug da fonte English, preserve anchors estáveis com `{#anchor}` em headings traduzidos e não traduza routes, action names, protocol fields, env vars ou provider names. Se um locale não tiver Markdown traduzido para uma página, o site cai para English nessa página enquanto continua localizando navegação e chrome.
+
+## Actions e persistência {#actions-and-persistence}
+
+Toda app herda:
+
+- `get-localization-preference` — lê o `{ locale }` do usuário atual
+- `set-localization-preference` — define `"system"` ou um locale suportado
+
+O valor durável fica em settings SQL com escopo de usuário sob `localization`. `localStorage` só é usado para pre-hydration e fallback anônimo. O locale ativo é espelhado no application state como contexto ambiente para que agents vejam o idioma atual da interface.
+
+## Guard {#guard}
+
+Rode:
+
+```bash
+pnpm guard:i18n-catalogs
+```
+
+O guard verifica nomes de arquivos locale suportados, key parity, placeholder parity, stale keys e categorias plurais CLDR via `Intl.PluralRules`. Ele verifica estrutura, não qualidade de tradução; strings de alta visibilidade ainda precisam de revisão humana.
+
+Não traduza identificadores estáveis como action names, routes, enum values, app-state keys, database values, protocol fields, env var names ou provider names.

package/docs/content/locales/zh-CN/internationalization.md

@@ -0,0 +1,102 @@
+---
+title: "国际化"
+description: "使用共享语言目录、语言选择器、浏览器语言回退和按语言区分的文档内容来本地化 Agent Native 应用。"
+---
+
+# 国际化
+
+Agent Native 应用可以通过共享的 `@agent-native/core/client/i18n` 运行时来本地化框架和模板 UI。框架把用户的语言选择存储在 SQL 设置中，将它暴露为 actions，并在应用尚未翻译某个字符串时回退到 English。
+
+## 运行时 {#runtime}
+
+通过 `AppProviders` 使用 provider：
+
+```tsx
+import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
+import { i18nCatalog } from "./i18n";
+
+const LOCALE_INIT_SCRIPT = getLocaleInitScript();
+
+<script
+  data-agent-native-locale-init
+  dangerouslySetInnerHTML={{ __html: LOCALE_INIT_SCRIPT }}
+/>;
+
+<AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+  <Outlet />
+</AppProviders>;
+```
+
+`getLocaleInitScript()` 会在 React hydration 之前设置初始的 `lang`、`dir` 和 `window.__AGENT_NATIVE_LOCALE__`。公共 SSR 路由可以从 `@agent-native/core/server` 调用 `resolveLocaleFromRequest()`，并把解析出的 locale/catalog 传入脚本，避免 hydration 不一致。
+
+## 目录 {#catalogs}
+
+每个本地化模板都把目录放在 `app/i18n/` 下：
+
+```ts
+// app/i18n/index.ts
+import enUS from "./en-US";
+import type { AgentNativeI18nCatalog } from "@agent-native/core/client";
+
+export const i18nCatalog = {
+  sourceLocale: "en-US",
+  messages: enUS,
+  loadMessages: async (locale) => {
+    switch (locale) {
+      case "zh-CN":
+        return (await import("./zh-CN")).default;
+      default:
+        return null;
+    }
+  },
+} satisfies AgentNativeI18nCatalog;
+```
+
+始终打包 `en-US`。非 English 目录使用动态导入，这样用户只下载当前语言。支持的 locale codes 是 `en-US`、`zh-CN`、`es-ES`、`fr-FR`、`de-DE`、`ja-JP`、`ko-KR`、`pt-BR`、`hi-IN` 和 `ar-SA`。
+
+## UI {#ui}
+
+界面字符串使用 `useT()`，设置页使用 `<LanguagePicker />`：
+
+```tsx
+import { LanguagePicker, useT } from "@agent-native/core/client";
+
+function SettingsLanguageCard() {
+  const t = useT();
+  return (
+    <>
+      <h2>{t("settings.languageTitle")}</h2>
+      <LanguagePicker label={t("settings.languageLabel")} />
+    </>
+  );
+}
+```
+
+日期、数字、相对时间和列表使用 `useFormatters()`。不要把依赖 locale 的日期或数字格式直接放进翻译字符串。
+
+## 文档站点内容 {#docs-site-content}
+
+公共文档页使用同一个 core provider，但设置 `persistPreference={false}`，因此匿名文档流量使用 localStorage 和浏览器语言，而不是 SQL 设置 actions。English 源文件仍在 `packages/core/docs/content/*.md`。本地化页面覆盖文件放在 `packages/core/docs/content/locales/<locale>/<slug>.md`。
+
+使用与应用目录相同的 BCP-47 locale codes。文件 slug 要与 English 源保持一致，翻译后的标题要用 `{#anchor}` 保留稳定锚点，并且不要翻译 routes、action names、protocol fields、env vars 或 provider names。如果某个 locale 没有某页 Markdown，文档站点会对该页回退到 English，同时继续本地化导航和 chrome。
+
+## Actions 与持久化 {#actions-and-persistence}
+
+每个应用都会继承：
+
+- `get-localization-preference` — 读取当前用户的 `{ locale }`
+- `set-localization-preference` — 设置 `"system"` 或支持的 locale
+
+持久值存储在用户作用域 SQL 设置的 `localization` 下。`localStorage` 只用于 hydration 前和匿名回退。当前 locale 会同步到 application state，作为环境上下文，让 agents 能看到当前界面语言。
+
+## Guard {#guard}
+
+运行：
+
+```bash
+pnpm guard:i18n-catalogs
+```
+
+guard 会通过 `Intl.PluralRules` 验证支持的 locale 文件名、key parity、placeholder parity、stale keys 和 CLDR plural categories。它检查结构，不检查翻译质量；高可见度字符串仍需要人工审校。
+
+不要翻译稳定标识符，例如 action names、routes、enum values、app-state keys、database values、protocol fields、env var names 或 provider names。

package/docs/content/skills-guide.md

@@ -24,24 +24,25 @@ Every skill's frontmatter `name` and `description` are always injected into the
 
 These are the skills bundled with the **default template**. The exact set available in any given app depends on the template you scaffolded from — check that template's `.agents/skills/` directory for what it actually ships.
 
-| Skill                 | When to use                                             |
-| --------------------- | ------------------------------------------------------- |
-| `storing-data`        | Adding data models, reading/writing config or state     |
-| `real-time-sync`      | Wiring polling sync, debugging UI not updating          |
-| `delegate-to-agent`   | Delegating AI work from UI or actions to the agent      |
-| `actions`             | Creating or running agent actions                       |
-| `self-modifying-code` | Editing app source, components, or styles               |
-| `create-skill`        | Adding new skills for the agent                         |
-| `capture-learnings`   | Recording corrections and patterns                      |
-| `frontend-design`     | Building or styling any web UI, components, or pages    |
-| `adding-a-feature`    | The four-area checklist: UI, actions, skills, app-state |
-| `shadcn-ui`           | Using shadcn/ui primitives and components               |
-| `security`            | Auth, access control, and secret handling               |
-| `real-time-collab`    | Multi-user collaborative editing                        |
-| `agent-engines`       | Swapping or configuring the underlying agent engine     |
-| `notifications`       | In-app and push notification patterns                   |
-| `progress`            | Tracking and surfacing background task progress         |
-| `inline-embeds`       | Embedding apps or iframes inside the agent chat         |
+| Skill                  | When to use                                                        |
+| ---------------------- | ------------------------------------------------------------------ |
+| `storing-data`         | Adding data models, reading/writing config or state                |
+| `real-time-sync`       | Wiring polling sync, debugging UI not updating                     |
+| `delegate-to-agent`    | Delegating AI work from UI or actions to the agent                 |
+| `actions`              | Creating or running agent actions                                  |
+| `self-modifying-code`  | Editing app source, components, or styles                          |
+| `create-skill`         | Adding new skills for the agent                                    |
+| `capture-learnings`    | Recording corrections and patterns                                 |
+| `frontend-design`      | Building or styling any web UI, components, or pages               |
+| `adding-a-feature`     | The four-area checklist: UI, actions, skills, app-state            |
+| `internationalization` | Updating localized UI copy, language catalogs, and RTL-safe styles |
+| `shadcn-ui`            | Using shadcn/ui primitives and components                          |
+| `security`             | Auth, access control, and secret handling                          |
+| `real-time-collab`     | Multi-user collaborative editing                                   |
+| `agent-engines`        | Swapping or configuring the underlying agent engine                |
+| `notifications`        | In-app and push notification patterns                              |
+| `progress`             | Tracking and surfacing background task progress                    |
+| `inline-embeds`        | Embedding apps or iframes inside the agent chat                    |
 
 `context-awareness` and `a2a-protocol` are framework-level skills available in the `.agents/skills/` directory at the repo root — see each template's own `.agents/skills/` for what it inherits.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.75.5",
+  "version": "0.76.0",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -69,6 +69,7 @@
     "./client/route-state": "./dist/client/route-state.js",
     "./client/observability": "./dist/client/observability/index.js",
     "./client/onboarding": "./dist/client/onboarding/index.js",
+    "./client/i18n": "./dist/client/i18n.js",
     "./client/settings/useBuilderStatus": "./dist/client/settings/useBuilderStatus.js",
     "./embedding": "./dist/embedding/index.js",
     "./embedding/agent": "./dist/embedding/agent.js",
@@ -80,6 +81,9 @@
     "./scripts": "./dist/scripts/index.js",
     "./application-state": "./dist/application-state/index.js",
     "./settings": "./dist/settings/index.js",
+    "./localization": "./dist/localization/index.js",
+    "./localization/actions/get-localization-preference": "./dist/localization/actions/get-localization-preference.js",
+    "./localization/actions/set-localization-preference": "./dist/localization/actions/set-localization-preference.js",
     "./credentials": "./dist/credentials/index.js",
     "./event-bus": "./dist/event-bus/index.js",
     "./fetch-tool": "./dist/extensions/fetch-tool.js",
@@ -235,6 +239,7 @@
     "fzstd": "^0.1.1",
     "h3": "^2.0.1-rc.20",
     "highlight.js": "^11.11.1",
+    "i18next": "26.3.1",
     "isbot": "^5",
     "jiti": "^2.6.1",
     "jose": "^6.2.2",
@@ -248,6 +253,7 @@
     "p-limit": "^7.3.0",
     "pako": "^2.1.0",
     "prettier": "^3.8.3",
+    "react-i18next": "17.0.8",
     "react-markdown": "^10.1.0",
     "recharts": "^3.8.1",
     "remark-gfm": "^4.0.1",

package/src/templates/default/.agents/skills/adding-a-feature/SKILL.md

@@ -86,6 +86,10 @@ Instruction examples may name secret keys like `SLACK_WEBHOOK`, but must use
 placeholders such as `${keys.SLACK_WEBHOOK}` or `<SLACK_WEBHOOK>`. Do not paste
 real keys, internal data, or customer data into instructions as examples.
 
+If the feature adds or changes visible UI copy, prompts, toasts, labels, empty
+states, or formatting, read `internationalization` and update the app's i18n
+catalogs in the same change.
+
 For app-backed skills, declare skill visibility in the app-skill manifest:
 
 - `internal` — only the app's own agents should use it.
@@ -177,3 +181,4 @@ TL;DR: spread `ownableColumns()` into the resource table, pair it with `createSh
 - **create-skill** — How to create skills for new patterns (area 3 in detail)
 - **storing-data** — Where to store the feature's data
 - **real-time-sync** — How the UI stays in sync when the agent writes data
+- **internationalization** — How to update localized UI copy and catalogs

package/src/templates/default/.agents/skills/internationalization/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: internationalization
+description: >-
+  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.
+scope: dev
+metadata:
+  internal: true
+---
+
+# 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.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`.
+
+## UI Pattern
+
+- Wrap apps with `AppProviders i18n={{ catalog: i18nCatalog }}`.
+- Read strings with `useT()` and keep keys stable.
+- Sidebar apps should expose a `/settings` route 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/client` to 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 `_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:
+
+```bash
+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.

package/src/templates/default/.agents/skills/self-modifying-code/SKILL.md

@@ -66,6 +66,11 @@ el.dataset.selectedId = selectedItem?.id || "";
 
 **Use configuration-driven rendering** — Extract visual decisions (colors, layouts, sizes) into JSON config files in `data/`. The agent can modify the config (Tier 1) instead of the component source (Tier 2).
 
+**Keep localized copy in catalogs** — When editing visible UI copy, labels,
+toasts, empty states, prompts, or formatting, read `internationalization` and
+update `app/i18n/en-US.ts` plus existing locale catalogs instead of leaving new
+inline strings in components.
+
 ## Don't
 
 - Don't modify `.env` files or files containing secrets
@@ -80,3 +85,4 @@ el.dataset.selectedId = selectedItem?.id || "";
 - **actions** — The agent can create or modify actions to add new capabilities
 - **delegate-to-agent** — Self-modification requests come through the agent chat
 - **real-time-sync** — Database writes trigger change events to update the UI
+- **internationalization** — UI copy, language catalogs, locale switching, and RTL-safe edits