@agent-native/core 0.75.5 → 0.76.0

package/docs/content/internationalization.md

@@ -0,0 +1,145 @@
+---
+title: "Internationalization"
+description: "Localize Agent Native apps with shared locale catalogs, a language picker, browser-language fallback, and locale-aware docs content."
+---
+
+# Internationalization
+
+Agent Native apps can localize framework and template UI through the shared
+`@agent-native/core/client/i18n` runtime. The framework stores the user's
+language choice in SQL settings, exposes it as actions, and falls back to
+English when an app has not translated a string yet.
+
+## Runtime
+
+Use the provider through `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()` sets the initial `lang`, `dir`, and
+`window.__AGENT_NATIVE_LOCALE__` before React hydrates. Public SSR routes can
+call `resolveLocaleFromRequest()` from `@agent-native/core/server` and pass the
+resolved locale/catalog into that script to avoid hydration mismatches.
+
+## Catalogs
+
+Each localized template keeps catalogs under `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;
+```
+
+Always bundle `en-US`. Dynamic-import non-English catalogs so users only
+download the active locale. The supported locale codes are `en-US`, `zh-CN`,
+`es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN`, and `ar-SA`.
+
+## UI
+
+Use `useT()` for interface strings and put `<LanguagePicker />` on the app's
+`/settings` page. Sidebar apps should expose **Settings** in the app sidebar;
+the header language icon is only a shortcut.
+
+```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>
+    </>
+  );
+}
+```
+
+The "Agent settings" control should open the right agent sidebar's Settings tab
+for model, API key, automation, voice, and other framework-level controls.
+Apps may duplicate high-value framework settings in their own settings page
+when the setting is central to the app, but the sidebar settings tab remains the
+source of truth.
+
+Use `useFormatters()` for dates, numbers, relative time, and lists. Do not put
+locale-sensitive date/number formatting inside translation strings.
+
+## Docs Site Content {#docs-site-content}
+
+Public docs pages use the same core provider, but with
+`persistPreference={false}` so anonymous docs traffic uses localStorage and the
+browser language instead of SQL settings actions. The English source remains in
+`packages/core/docs/content/*.md`. Localized page overrides live next to it under
+`packages/core/docs/content/locales/<locale>/<slug>.md`.
+
+Use the same BCP-47 locale codes as app catalogs. Keep the same slug as the
+English source, preserve stable anchors with `{#anchor}` on translated headings,
+and leave routes, action names, protocol fields, env vars, and provider names
+untranslated. If a locale has no translated Markdown for a page, the docs site
+falls back to English for that page while still localizing navigation and chrome.
+
+## Actions And Persistence
+
+Every app inherits:
+
+- `get-localization-preference` — read the current user's `{ locale }`
+- `set-localization-preference` — set `"system"` or a supported locale
+
+The durable value lives in user-scoped SQL settings under `localization`.
+`localStorage` is only used for pre-hydration and anonymous fallback. The active
+locale is mirrored into application state as ambient context so agents can see
+the current interface language.
+
+## Guard
+
+Run:
+
+```bash
+pnpm guard:i18n-catalogs
+```
+
+The guard verifies supported locale filenames, key parity, placeholder parity,
+stale keys, and CLDR plural categories through `Intl.PluralRules`. It checks
+structure, not translation quality; high-visibility strings still need human
+review.
+
+Do not translate stable identifiers such as action names, routes, enum values,
+app-state keys, database values, protocol fields, env var names, or provider
+names.

package/docs/content/locales/ar-SA/internationalization.md

@@ -0,0 +1,102 @@
+---
+title: "التدويل"
+description: "قم بتعريب تطبيقات Agent Native باستخدام كتالوجات locale مشتركة، واختيار اللغة، والرجوع إلى لغة المتصفح، ومحتوى docs حسب locale."
+---
+
+# التدويل
+
+يمكن لتطبيقات Agent Native تعريب واجهة framework و templates عبر runtime المشترك `@agent-native/core/client/i18n`. يخزن framework اختيار لغة المستخدم في SQL settings، ويعرضه كـ actions، ويرجع إلى English عندما لا تكون string مترجمة في التطبيق بعد.
+
+## Runtime {#runtime}
+
+استخدم provider عبر `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()` قيم `lang` و `dir` و `window.__AGENT_NATIVE_LOCALE__` قبل React hydration. يمكن لمسارات SSR العامة استدعاء `resolveLocaleFromRequest()` من `@agent-native/core/server` وتمرير locale/catalog الناتج إلى script لتجنب hydration mismatches.
+
+## Catalogs {#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` دائماً. استخدم dynamic import للكتالوجات غير English حتى ينزل المستخدمون 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()` لنصوص الواجهة و `<LanguagePicker />` في 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")} />
+    </>
+  );
+}
+```
+
+استخدم `useFormatters()` للتواريخ، والأرقام، والوقت النسبي، والقوائم. لا تضع تنسيق التاريخ أو الرقم المعتمد على locale داخل strings المترجمة.
+
+## محتوى موقع docs {#docs-site-content}
+
+تستخدم صفحات docs العامة نفس core provider، لكن مع `persistPreference={false}` حتى يستخدم زوار docs المجهولون localStorage ولغة المتصفح بدلاً من SQL settings actions. يبقى مصدر English في `packages/core/docs/content/*.md`. توجد overrides المترجمة في `packages/core/docs/content/locales/<locale>/<slug>.md`.
+
+استخدم نفس BCP-47 locale codes الخاصة بكتالوجات التطبيقات. حافظ على نفس slug الموجود في مصدر English، واحفظ anchors ثابتة باستخدام `{#anchor}` على headings المترجمة، ولا تترجم routes أو action names أو protocol fields أو env vars أو provider names. إذا لم يملك locale ملف Markdown مترجماً لصفحة ما، يعود موقع docs إلى English لتلك الصفحة مع استمرار تعريب navigation و chrome.
+
+## Actions والاستمرارية {#actions-and-persistence}
+
+كل تطبيق يرث:
+
+- `get-localization-preference` — يقرأ `{ locale }` للمستخدم الحالي
+- `set-localization-preference` — يضبط `"system"` أو locale مدعوماً
+
+القيمة الدائمة موجودة في SQL settings بنطاق المستخدم تحت `localization`. يستخدم `localStorage` فقط قبل hydration وللرجوع المجهول. ينعكس locale النشط في application state كسياق محيط حتى تتمكن agents من رؤية لغة الواجهة الحالية.
+
+## Guard {#guard}
+
+شغّل:
+
+```bash
+pnpm guard:i18n-catalogs
+```
+
+يتحقق guard من أسماء ملفات locale المدعومة، و key parity، و placeholder parity، و stale keys، وفئات CLDR plural عبر `Intl.PluralRules`. هو يتحقق من البنية لا جودة الترجمة؛ strings البارزة ما زالت تحتاج مراجعة بشرية.
+
+لا تترجم المعرفات الثابتة مثل action names أو routes أو enum values أو app-state keys أو database values أو protocol fields أو env var names أو provider names.

package/docs/content/locales/de-DE/internationalization.md

@@ -0,0 +1,102 @@
+---
+title: "Internationalisierung"
+description: "Lokalisiere Agent Native Apps mit gemeinsamen Locale-Katalogen, Sprachauswahl, Browser-Fallback und locale-bewussten Docs."
+---
+
+# Internationalisierung
+
+Agent Native Apps können Framework- und Template-UI über die gemeinsame Runtime `@agent-native/core/client/i18n` lokalisieren. Das Framework speichert die Sprachwahl des Benutzers in SQL-Settings, stellt sie als actions bereit und fällt auf English zurück, wenn eine App einen String noch nicht übersetzt hat.
+
+## Runtime {#runtime}
+
+Verwende den Provider über `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()` setzt das anfängliche `lang`, `dir` und `window.__AGENT_NATIVE_LOCALE__`, bevor React hydriert. Öffentliche SSR-Routen können `resolveLocaleFromRequest()` aus `@agent-native/core/server` aufrufen und den aufgelösten locale/catalog an das Script übergeben, um Hydration-Abweichungen zu vermeiden.
+
+## Kataloge {#catalogs}
+
+Jedes lokalisierte Template hält Kataloge unter `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;
+```
+
+Bundle immer `en-US`. Importiere Nicht-English-Kataloge dynamisch, damit Benutzer nur den aktiven locale herunterladen. Unterstützte locale codes sind `en-US`, `zh-CN`, `es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN` und `ar-SA`.
+
+## UI {#ui}
+
+Verwende `useT()` für UI-Texte und `<LanguagePicker />` in den 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")} />
+    </>
+  );
+}
+```
+
+Verwende `useFormatters()` für Datumswerte, Zahlen, relative Zeiten und Listen. Lege locale-abhängige Datums- oder Zahlenformatierung nicht in Übersetzungsstrings ab.
+
+## Docs-Site-Inhalt {#docs-site-content}
+
+Öffentliche Docs-Seiten verwenden denselben core provider, aber mit `persistPreference={false}`, damit anonymer Docs-Traffic localStorage und die Browsersprache nutzt statt SQL-Settings-actions. Die English-Quelle bleibt in `packages/core/docs/content/*.md`. Lokalisierte Seiten-Overrides liegen unter `packages/core/docs/content/locales/<locale>/<slug>.md`.
+
+Verwende dieselben BCP-47 locale codes wie App-Kataloge. Behalte denselben slug wie die English-Quelle, bewahre stabile Anker mit `{#anchor}` auf übersetzten Überschriften und übersetze keine routes, action names, protocol fields, env vars oder provider names. Wenn ein locale keine übersetzte Markdown-Datei für eine Seite hat, fällt die Docs-Site für diese Seite auf English zurück, lokalisiert aber weiterhin Navigation und Chrome.
+
+## Actions und Persistenz {#actions-and-persistence}
+
+Jede App erbt:
+
+- `get-localization-preference` — liest `{ locale }` des aktuellen Benutzers
+- `set-localization-preference` — setzt `"system"` oder einen unterstützten locale
+
+Der dauerhafte Wert liegt in benutzerbezogenen SQL-Settings unter `localization`. `localStorage` wird nur für Pre-Hydration und anonymen Fallback genutzt. Der aktive locale wird als Umgebungskontext in application state gespiegelt, damit agents die aktuelle UI-Sprache sehen.
+
+## Guard {#guard}
+
+Ausführen:
+
+```bash
+pnpm guard:i18n-catalogs
+```
+
+Der Guard prüft unterstützte locale-Dateinamen, key parity, placeholder parity, stale keys und CLDR-Pluralkategorien über `Intl.PluralRules`. Er prüft Struktur, nicht Übersetzungsqualität; gut sichtbare Strings brauchen weiterhin menschliche Prüfung.
+
+Übersetze keine stabilen Bezeichner wie action names, routes, enum values, app-state keys, database values, protocol fields, env var names oder provider names.

package/docs/content/locales/es-ES/internationalization.md

@@ -0,0 +1,102 @@
+---
+title: "Internacionalización"
+description: "Localiza apps Agent Native con catálogos compartidos, selector de idioma, fallback al navegador y contenido de docs por locale."
+---
+
+# Internacionalización
+
+Las apps Agent Native pueden localizar la UI del framework y de las plantillas con el runtime compartido `@agent-native/core/client/i18n`. El framework guarda la elección de idioma del usuario en settings SQL, la expone como actions y vuelve a English cuando una app aún no tradujo una cadena.
+
+## Runtime {#runtime}
+
+Usa el provider a través 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 el `lang`, `dir` y `window.__AGENT_NATIVE_LOCALE__` iniciales antes de que React hidrate. Las rutas SSR públicas pueden llamar a `resolveLocaleFromRequest()` desde `@agent-native/core/server` y pasar el locale/catalog resuelto al script para evitar desajustes de hydration.
+
+## Catálogos {#catalogs}
+
+Cada plantilla localizada mantiene catálogos en `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;
+```
+
+Incluye siempre `en-US`. Importa dinámicamente los catálogos que no sean English para que cada usuario descargue solo el locale activo. Los locale codes admitidos son `en-US`, `zh-CN`, `es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN` y `ar-SA`.
+
+## UI {#ui}
+
+Usa `useT()` para textos de interfaz y `<LanguagePicker />` en 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")} />
+    </>
+  );
+}
+```
+
+Usa `useFormatters()` para fechas, números, tiempo relativo y listas. No pongas formatos sensibles al locale dentro de cadenas traducidas.
+
+## Contenido del sitio de docs {#docs-site-content}
+
+Las páginas públicas de docs usan el mismo core provider, pero con `persistPreference={false}` para que el tráfico anónimo use localStorage y el idioma del navegador en vez de actions de settings SQL. La fuente English queda en `packages/core/docs/content/*.md`. Las páginas localizadas que sobrescriben esa fuente viven en `packages/core/docs/content/locales/<locale>/<slug>.md`.
+
+Usa los mismos BCP-47 locale codes que los catálogos de app. Conserva el mismo slug que la fuente English, preserva anclas estables con `{#anchor}` en headings traducidos y no traduzcas routes, action names, protocol fields, env vars ni provider names. Si un locale no tiene Markdown traducido para una página, el sitio cae a English para esa página mientras sigue localizando la navegación y el chrome.
+
+## Actions y persistencia {#actions-and-persistence}
+
+Cada app hereda:
+
+- `get-localization-preference` — lee el `{ locale }` del usuario actual
+- `set-localization-preference` — define `"system"` o un locale admitido
+
+El valor durable vive en settings SQL con alcance de usuario bajo `localization`. `localStorage` solo se usa para pre-hydration y fallback anónimo. El locale activo se refleja en application state como contexto ambiental para que los agents vean el idioma actual de la interfaz.
+
+## Guard {#guard}
+
+Ejecuta:
+
+```bash
+pnpm guard:i18n-catalogs
+```
+
+El guard verifica nombres de archivos locale admitidos, key parity, placeholder parity, stale keys y categorías plurales CLDR mediante `Intl.PluralRules`. Revisa estructura, no calidad de traducción; las cadenas de alta visibilidad necesitan revisión humana.
+
+No traduzcas identificadores estables como action names, routes, enum values, app-state keys, database values, protocol fields, env var names o provider names.

package/docs/content/locales/fr-FR/internationalization.md

@@ -0,0 +1,102 @@
+---
+title: "Internationalisation"
+description: "Localisez les apps Agent Native avec des catalogues partagés, un sélecteur de langue, un fallback navigateur et du contenu docs par locale."
+---
+
+# Internationalisation
+
+Les apps Agent Native peuvent localiser l'UI du framework et des modèles via le runtime partagé `@agent-native/core/client/i18n`. Le framework stocke le choix de langue de l'utilisateur dans les settings SQL, l'expose sous forme d'actions et revient à English lorsqu'une app n'a pas encore traduit une chaîne.
+
+## Runtime {#runtime}
+
+Utilisez le provider via `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()` définit le `lang`, le `dir` et `window.__AGENT_NATIVE_LOCALE__` initiaux avant l'hydratation React. Les routes SSR publiques peuvent appeler `resolveLocaleFromRequest()` depuis `@agent-native/core/server` et transmettre le locale/catalog résolu au script pour éviter les écarts d'hydratation.
+
+## Catalogues {#catalogs}
+
+Chaque modèle localisé conserve ses catalogues dans `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;
+```
+
+Emballez toujours `en-US`. Importez dynamiquement les catalogues non English afin que les utilisateurs ne téléchargent que le locale actif. Les locale codes pris en charge sont `en-US`, `zh-CN`, `es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN` et `ar-SA`.
+
+## UI {#ui}
+
+Utilisez `useT()` pour les textes d'interface et `<LanguagePicker />` dans les 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")} />
+    </>
+  );
+}
+```
+
+Utilisez `useFormatters()` pour les dates, nombres, temps relatifs et listes. Ne placez pas de formatage sensible au locale dans les chaînes traduites.
+
+## Contenu du site docs {#docs-site-content}
+
+Les pages publiques de docs utilisent le même core provider, mais avec `persistPreference={false}` afin que le trafic anonyme utilise localStorage et la langue du navigateur au lieu des actions de settings SQL. La source English reste dans `packages/core/docs/content/*.md`. Les remplacements localisés vivent dans `packages/core/docs/content/locales/<locale>/<slug>.md`.
+
+Utilisez les mêmes BCP-47 locale codes que les catalogues d'app. Gardez le même slug que la source English, préservez les ancres stables avec `{#anchor}` sur les titres traduits, et ne traduisez pas les routes, action names, protocol fields, env vars ou provider names. Si un locale n'a pas de Markdown traduit pour une page, le site revient à English pour cette page tout en localisant la navigation et le chrome.
+
+## Actions et persistance {#actions-and-persistence}
+
+Chaque app hérite de :
+
+- `get-localization-preference` — lit le `{ locale }` de l'utilisateur actuel
+- `set-localization-preference` — définit `"system"` ou un locale pris en charge
+
+La valeur durable vit dans les settings SQL à portée utilisateur sous `localization`. `localStorage` sert uniquement au pre-hydration et au fallback anonyme. Le locale actif est reflété dans application state comme contexte ambiant afin que les agents voient la langue actuelle de l'interface.
+
+## Guard {#guard}
+
+Exécutez :
+
+```bash
+pnpm guard:i18n-catalogs
+```
+
+Le guard vérifie les noms de fichiers locale pris en charge, key parity, placeholder parity, stale keys et catégories plurales CLDR via `Intl.PluralRules`. Il vérifie la structure, pas la qualité de traduction ; les chaînes très visibles nécessitent encore une revue humaine.
+
+Ne traduisez pas les identifiants stables comme action names, routes, enum values, app-state keys, database values, protocol fields, env var names ou provider names.

package/docs/content/locales/hi-IN/internationalization.md

@@ -0,0 +1,102 @@
+---
+title: "अंतरराष्ट्रीयकरण"
+description: "shared locale catalogs, language picker, browser-language fallback और locale-aware docs content के साथ Agent Native apps को localize करें।"
+---
+
+# अंतरराष्ट्रीयकरण
+
+Agent Native apps shared `@agent-native/core/client/i18n` runtime के जरिए framework और template UI को localize कर सकते हैं। framework उपयोगकर्ता की भाषा पसंद को SQL settings में store करता है, उसे actions के रूप में expose करता है, और जब किसी app में कोई string translate नहीं होती तो English पर fallback करता है।
+
+## Runtime {#runtime}
+
+Provider को `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()` React hydration से पहले शुरुआती `lang`, `dir`, और `window.__AGENT_NATIVE_LOCALE__` सेट करता है। Public SSR routes `@agent-native/core/server` से `resolveLocaleFromRequest()` call कर सकते हैं और resolved locale/catalog को script में pass कर सकते हैं ताकि hydration mismatch न हो।
+
+## Catalogs {#catalogs}
+
+हर localized template 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` bundle करें। Non-English catalogs को dynamic import करें ताकि users केवल active locale download करें। Supported locale codes हैं `en-US`, `zh-CN`, `es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN`, और `ar-SA`।
+
+## UI {#ui}
+
+Interface strings के लिए `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")} />
+    </>
+  );
+}
+```
+
+Dates, numbers, relative time और lists के लिए `useFormatters()` इस्तेमाल करें। Locale-sensitive date/number formatting को translation strings में embed न करें।
+
+## Docs site content {#docs-site-content}
+
+Public docs pages वही core provider इस्तेमाल करते हैं, लेकिन `persistPreference={false}` के साथ, ताकि anonymous docs traffic SQL settings actions की जगह localStorage और browser language इस्तेमाल करे। English source `packages/core/docs/content/*.md` में रहता है। Localized page overrides `packages/core/docs/content/locales/<locale>/<slug>.md` में रहते हैं।
+
+App catalogs जैसे ही BCP-47 locale codes इस्तेमाल करें। English source जैसा slug रखें, translated headings पर `{#anchor}` से stable anchors preserve करें, और routes, action names, protocol fields, env vars या provider names translate न करें। अगर किसी locale में किसी page का translated Markdown नहीं है, docs site उस page के लिए English fallback करेगा और navigation/chrome फिर भी localize रहेगा।
+
+## Actions और persistence {#actions-and-persistence}
+
+हर app को मिलता है:
+
+- `get-localization-preference` — current user का `{ locale }` पढ़ता है
+- `set-localization-preference` — `"system"` या supported locale सेट करता है
+
+Durable value user-scoped SQL settings में `localization` key के तहत रहता है। `localStorage` केवल pre-hydration और anonymous fallback के लिए है। Active locale application state में ambient context के रूप में mirror होता है ताकि agents current interface language देख सकें।
+
+## Guard {#guard}
+
+चलाएं:
+
+```bash
+pnpm guard:i18n-catalogs
+```
+
+Guard supported locale filenames, key parity, placeholder parity, stale keys, और `Intl.PluralRules` के जरिए CLDR plural categories verify करता है। यह structure check करता है, translation quality नहीं; high-visibility strings को human review चाहिए।
+
+Stable identifiers जैसे action names, routes, enum values, app-state keys, database values, protocol fields, env var names या provider names translate न करें।