@agent-native/core 0.75.5 → 0.76.0

package/corpus/core/src/client/index.ts

@@ -170,6 +170,33 @@ export {
   type AgentDynamicSuggestionsOption,
 } from "./dynamic-suggestions.js";
 export { cn } from "./utils.js";
+export {
+  AgentNativeI18nProvider,
+  LanguagePicker,
+  getLocaleInitScript,
+  localeDirection,
+  normalizeLocaleCode,
+  normalizeLocalePreference,
+  normalizeLocalizationPreference,
+  resolveLocaleFromCandidates,
+  resolveLocaleFromPreference,
+  useFormatters,
+  useLocale,
+  useT,
+  DEFAULT_LOCALE,
+  LOCALE_HYDRATION_GLOBAL,
+  LOCALE_METADATA,
+  LOCALE_STORAGE_KEY,
+  SUPPORTED_LOCALES,
+  type AgentNativeI18nCatalog,
+  type AgentNativeI18nProviderProps,
+  type LocaleCode,
+  type LocaleHydrationPayload,
+  type LocaleMessages,
+  type LocaleMetadata,
+  type LocalePreference,
+  type LocalizationPreference,
+} from "./i18n.js";
 export {
   // Shared editor core (Phase 1): the ONE configurable surface both the plan
   // and content editors build on.
@@ -708,6 +735,7 @@ export {
   CommandMenu,
   useCommandMenuShortcut,
   openAgentSidebar,
+  openAgentSettings,
   submitToAgent,
   type CommandMenuProps,
   type CommandMenuDoc,

package/corpus/core/src/index.browser.ts

@@ -25,6 +25,23 @@ export {
   updateMcpAppModelContext,
   useMcpAppHostContext,
   CodeRequiredDialog,
+  AgentNativeI18nProvider,
+  LanguagePicker,
+  getLocaleInitScript,
+  localeDirection,
+  normalizeLocaleCode,
+  normalizeLocalePreference,
+  normalizeLocalizationPreference,
+  resolveLocaleFromCandidates,
+  resolveLocaleFromPreference,
+  useFormatters,
+  useLocale,
+  useT,
+  DEFAULT_LOCALE,
+  LOCALE_HYDRATION_GLOBAL,
+  LOCALE_METADATA,
+  LOCALE_STORAGE_KEY,
+  SUPPORTED_LOCALES,
   useDbSync,
   useFileWatcher,
   useSession,
@@ -48,6 +65,14 @@ export {
   type CodeRequiredDialogProps,
   type AuthSession,
   type UseAgentChatContextResult,
+  type AgentNativeI18nCatalog,
+  type AgentNativeI18nProviderProps,
+  type LocaleCode,
+  type LocaleHydrationPayload,
+  type LocaleMessages,
+  type LocaleMetadata,
+  type LocalePreference,
+  type LocalizationPreference,
 } from "./client/index.js";
 
 // Shared (isomorphic)

package/corpus/core/src/localization/actions/get-localization-preference.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { getUserSetting } from "../../settings/user-settings.js";
+import {
+  LOCALIZATION_SETTING_KEY,
+  normalizeLocalizationPreference,
+  type LocalizationPreference,
+} from "../shared.js";
+
+export default defineAction({
+  description:
+    "Get the current user's interface language preference. Returns { locale }, where locale is 'system' or a supported BCP-47 locale.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async (_args, ctx): Promise<LocalizationPreference> => {
+    if (!ctx?.userEmail) throw new Error("Not authenticated.");
+    const stored = await getUserSetting(
+      ctx.userEmail,
+      LOCALIZATION_SETTING_KEY,
+    );
+    return normalizeLocalizationPreference(stored);
+  },
+});

package/corpus/core/src/localization/actions/set-localization-preference.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { putUserSetting } from "../../settings/user-settings.js";
+import {
+  LOCALIZATION_SETTING_KEY,
+  normalizeLocalePreference,
+  type LocalizationPreference,
+} from "../shared.js";
+
+export default defineAction({
+  description:
+    "Set the current user's interface language preference to 'system' or a supported BCP-47 locale.",
+  schema: z.object({
+    locale: z
+      .string()
+      .describe("Language preference: 'system' or a supported BCP-47 locale."),
+  }),
+  run: async (args, ctx): Promise<LocalizationPreference> => {
+    if (!ctx?.userEmail) throw new Error("Not authenticated.");
+    const locale = normalizeLocalePreference(args.locale);
+    if (!locale) {
+      throw new Error(
+        "Unsupported locale. Use system, en-US, zh-CN, es-ES, fr-FR, de-DE, ja-JP, ko-KR, pt-BR, hi-IN, or ar-SA.",
+      );
+    }
+    const value: LocalizationPreference & Record<string, unknown> = { locale };
+    await putUserSetting(ctx.userEmail, LOCALIZATION_SETTING_KEY, value);
+    return value;
+  },
+});

package/corpus/core/src/localization/index.ts

@@ -0,0 +1,2 @@
+export * from "./shared.js";
+export * from "./server.js";

package/corpus/core/src/localization/server.ts

@@ -0,0 +1,131 @@
+import {
+  DEFAULT_LOCALE,
+  LOCALE_HYDRATION_GLOBAL,
+  LOCALE_STORAGE_KEY,
+  SUPPORTED_LOCALES,
+  localeDirection,
+  normalizeLocaleCode,
+  normalizeLocalizationPreference,
+  resolveLocaleFromPreference,
+  type LocaleCode,
+  type LocalePreference,
+  type LocalizationPreference,
+} from "./shared.js";
+
+interface RequestLike {
+  headers?: Headers | Record<string, string | string[] | undefined> | null;
+}
+
+type HeaderMap = Headers | Record<string, string | string[] | undefined>;
+
+export interface ResolvedRequestLocale {
+  locale: LocaleCode;
+  preference: LocalizationPreference;
+  dir: "ltr" | "rtl";
+}
+
+export interface ResolveLocaleFromRequestOptions {
+  request?: Request | RequestLike | null;
+  acceptLanguage?: string | null;
+  preference?: LocalizationPreference | LocalePreference | null;
+  fallback?: LocaleCode;
+}
+
+export interface LocaleInitScriptOptions {
+  locale?: LocaleCode;
+  preference?: LocalizationPreference | LocalePreference;
+  messages?: Record<string, unknown> | null;
+}
+
+function readHeader(
+  headers: HeaderMap | undefined | null,
+  key: string,
+): string | null {
+  if (!headers) return null;
+  if (typeof (headers as Headers).get === "function") {
+    return (headers as Headers).get(key);
+  }
+  const lowerKey = key.toLowerCase();
+  for (const [name, value] of Object.entries(headers)) {
+    if (name.toLowerCase() !== lowerKey) continue;
+    if (Array.isArray(value)) return value.join(",");
+    return value ?? null;
+  }
+  return null;
+}
+
+export function parseAcceptLanguage(header: string | null | undefined) {
+  if (!header) return [];
+  return header
+    .split(",")
+    .map((part) => {
+      const [tag, ...params] = part.trim().split(";");
+      const q = params
+        .map((param) => param.trim())
+        .find((param) => param.startsWith("q="));
+      const weight = q ? Number.parseFloat(q.slice(2)) : 1;
+      return {
+        tag,
+        weight: Number.isFinite(weight) ? weight : 0,
+      };
+    })
+    .filter((entry) => entry.tag && entry.weight > 0)
+    .sort((a, b) => b.weight - a.weight)
+    .map((entry) => entry.tag);
+}
+
+export function resolveLocaleFromRequest(
+  options: ResolveLocaleFromRequestOptions = {},
+): ResolvedRequestLocale {
+  const header =
+    options.acceptLanguage ??
+    readHeader(options.request?.headers, "accept-language");
+  const candidates = parseAcceptLanguage(header);
+  const preference = normalizeLocalizationPreference(
+    options.preference ?? { locale: "system" },
+  );
+  const locale =
+    preference.locale === "system"
+      ? resolveLocaleFromPreference(preference, [
+          ...candidates,
+          options.fallback ?? DEFAULT_LOCALE,
+        ])
+      : (normalizeLocaleCode(preference.locale) ??
+        options.fallback ??
+        DEFAULT_LOCALE);
+  return {
+    locale,
+    preference,
+    dir: localeDirection(locale),
+  };
+}
+
+export function getLocaleInitScript(options: LocaleInitScriptOptions = {}) {
+  const safeLocale = normalizeLocaleCode(options.locale) ?? DEFAULT_LOCALE;
+  const shouldStorePreference = options.preference !== undefined;
+  const safePreference = normalizeLocalizationPreference(
+    options.preference ?? { locale: "system" },
+  );
+  const payload = {
+    locale: safeLocale,
+    preference: safePreference,
+    dir: localeDirection(safeLocale),
+    messages: options.messages ?? undefined,
+  };
+
+  return `(function(){try{var supported=${JSON.stringify(
+    SUPPORTED_LOCALES,
+  )};var payload=${JSON.stringify(
+    payload,
+  )};var shouldStorePreference=${JSON.stringify(
+    shouldStorePreference,
+  )};function valid(x){return supported.indexOf(x)>=0}function canon(x){if(typeof x!=='string'||!x)return null;try{var c=Intl.getCanonicalLocales(x)[0];if(valid(c))return c;var lang=c&&c.split('-')[0].toLowerCase();for(var i=0;i<supported.length;i++){if(supported[i].split('-')[0].toLowerCase()===lang)return supported[i]}}catch(e){}return null}function storageGet(k){try{return window.localStorage.getItem(k)}catch(e){return null}}function storageSet(k,v){try{window.localStorage.setItem(k,v)}catch(e){}}var stored=storageGet(${JSON.stringify(
+    LOCALE_STORAGE_KEY,
+  )});var pref=payload.preference&&payload.preference.locale;var locale=payload.locale;if(!valid(locale)){locale=null}if(!locale&&stored&&stored!=='system'){locale=canon(stored)}if(!locale&&pref&&pref!=='system'){locale=canon(pref)}if(!locale){var langs=navigator.languages&&navigator.languages.length?navigator.languages:[navigator.language];for(var j=0;j<langs.length&&!locale;j++){locale=canon(langs[j])}}if(!locale)locale=${JSON.stringify(
+    DEFAULT_LOCALE,
+  )};var root=document.documentElement;root.setAttribute('lang',locale);root.setAttribute('dir',locale==='ar-SA'?'rtl':'ltr');root.setAttribute('data-locale',locale);payload.locale=locale;payload.dir=locale==='ar-SA'?'rtl':'ltr';window[${JSON.stringify(
+    LOCALE_HYDRATION_GLOBAL,
+  )}]=payload;if(shouldStorePreference&&pref){storageSet(${JSON.stringify(
+    LOCALE_STORAGE_KEY,
+  )},pref)}}catch(e){}})();`;
+}

package/corpus/core/src/localization/shared.ts

@@ -0,0 +1,163 @@
+export const SUPPORTED_LOCALES = [
+  "en-US",
+  "zh-CN",
+  "es-ES",
+  "fr-FR",
+  "de-DE",
+  "ja-JP",
+  "ko-KR",
+  "pt-BR",
+  "hi-IN",
+  "ar-SA",
+] as const;
+
+export type LocaleCode = (typeof SUPPORTED_LOCALES)[number];
+export type LocalePreference = "system" | LocaleCode;
+
+export interface LocaleMetadata {
+  code: LocaleCode;
+  englishName: string;
+  nativeName: string;
+  dir: "ltr" | "rtl";
+}
+
+export interface LocalizationPreference {
+  locale: LocalePreference;
+}
+
+export const DEFAULT_LOCALE: LocaleCode = "en-US";
+export const LOCALIZATION_SETTING_KEY = "localization";
+export const LOCALE_STORAGE_KEY = "agent-native:locale-preference";
+export const LOCALE_HYDRATION_GLOBAL = "__AGENT_NATIVE_LOCALE__";
+
+export const LOCALE_METADATA: Record<LocaleCode, LocaleMetadata> = {
+  "en-US": {
+    code: "en-US",
+    englishName: "English",
+    nativeName: "English",
+    dir: "ltr",
+  },
+  "zh-CN": {
+    code: "zh-CN",
+    englishName: "Chinese (Simplified)",
+    nativeName: "简体中文",
+    dir: "ltr",
+  },
+  "es-ES": {
+    code: "es-ES",
+    englishName: "Spanish",
+    nativeName: "Español",
+    dir: "ltr",
+  },
+  "fr-FR": {
+    code: "fr-FR",
+    englishName: "French",
+    nativeName: "Français",
+    dir: "ltr",
+  },
+  "de-DE": {
+    code: "de-DE",
+    englishName: "German",
+    nativeName: "Deutsch",
+    dir: "ltr",
+  },
+  "ja-JP": {
+    code: "ja-JP",
+    englishName: "Japanese",
+    nativeName: "日本語",
+    dir: "ltr",
+  },
+  "ko-KR": {
+    code: "ko-KR",
+    englishName: "Korean",
+    nativeName: "한국어",
+    dir: "ltr",
+  },
+  "pt-BR": {
+    code: "pt-BR",
+    englishName: "Portuguese (Brazil)",
+    nativeName: "Português (Brasil)",
+    dir: "ltr",
+  },
+  "hi-IN": {
+    code: "hi-IN",
+    englishName: "Hindi",
+    nativeName: "हिन्दी",
+    dir: "ltr",
+  },
+  "ar-SA": {
+    code: "ar-SA",
+    englishName: "Arabic",
+    nativeName: "العربية",
+    dir: "rtl",
+  },
+};
+
+const SUPPORTED_LOCALE_SET = new Set<string>(SUPPORTED_LOCALES);
+
+export function isLocaleCode(value: unknown): value is LocaleCode {
+  return typeof value === "string" && SUPPORTED_LOCALE_SET.has(value);
+}
+
+export function normalizeLocaleCode(value: unknown): LocaleCode | null {
+  if (typeof value !== "string" || value.trim().length === 0) return null;
+  try {
+    for (const canonical of Intl.getCanonicalLocales(value.trim())) {
+      if (isLocaleCode(canonical)) return canonical;
+      const language = canonical.split("-")[0]?.toLowerCase();
+      const match = SUPPORTED_LOCALES.find(
+        (locale) => locale.split("-")[0]?.toLowerCase() === language,
+      );
+      if (match) return match;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+export function normalizeLocalePreference(
+  value: unknown,
+): LocalePreference | null {
+  if (value === "system") return "system";
+  return normalizeLocaleCode(value);
+}
+
+export function normalizeLocalizationPreference(
+  value: unknown,
+): LocalizationPreference {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const locale = normalizeLocalePreference(
+      (value as { locale?: unknown }).locale,
+    );
+    if (locale) return { locale };
+  }
+  const locale = normalizeLocalePreference(value);
+  return { locale: locale ?? "system" };
+}
+
+export function localeDirection(locale: LocaleCode): "ltr" | "rtl" {
+  return LOCALE_METADATA[locale]?.dir ?? "ltr";
+}
+
+export function resolveLocaleFromCandidates(
+  candidates: Iterable<unknown>,
+): LocaleCode {
+  for (const candidate of candidates) {
+    const normalized = normalizeLocaleCode(candidate);
+    if (normalized) return normalized;
+  }
+  return DEFAULT_LOCALE;
+}
+
+export function resolveLocaleFromPreference(
+  preference: LocalizationPreference | LocalePreference | unknown,
+  systemCandidates: Iterable<unknown> = [],
+): LocaleCode {
+  const normalized =
+    typeof preference === "string"
+      ? normalizeLocalePreference(preference)
+      : normalizeLocalizationPreference(preference).locale;
+  if (normalized && normalized !== "system") return normalized;
+  return resolveLocaleFromCandidates(systemCandidates);
+}

package/corpus/core/src/server/action-discovery.ts

@@ -575,6 +575,14 @@ export async function mergeCoreSharingActions(
       "context-report",
       () => import("../agent/context-xray/actions/context-report.js"),
     ],
+    [
+      "get-localization-preference",
+      () => import("../localization/actions/get-localization-preference.js"),
+    ],
+    [
+      "set-localization-preference",
+      () => import("../localization/actions/set-localization-preference.js"),
+    ],
     [
       "change-appearance",
       () => import("../appearance/actions/change-appearance.js"),

package/corpus/core/src/server/index.ts

@@ -78,6 +78,14 @@ export {
 } from "./identity-sso.js";
 export { requireEnvKey, type MissingKeyResponse } from "./missing-key.js";
 export { verifyCaptcha, type CaptchaVerifyResult } from "./captcha.js";
+export {
+  getLocaleInitScript,
+  parseAcceptLanguage,
+  resolveLocaleFromRequest,
+  type LocaleInitScriptOptions,
+  type ResolveLocaleFromRequestOptions,
+  type ResolvedRequestLocale,
+} from "../localization/server.js";
 export {
   createProductionAgentHandler,
   type ActionEntry,

package/corpus/core/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/corpus/core/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/corpus/core/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

package/corpus/core/src/templates/default/AGENTS.md

@@ -143,21 +143,22 @@ repackage, or proxy an action.
 
 Skills in `.agents/skills/` provide detailed guidance for each architectural rule. Read them before making changes.
 
-| Skill                 | When to read                                                                      |
-| --------------------- | --------------------------------------------------------------------------------- |
-| `agent-native-docs`   | Before using advanced Agent Native framework APIs or generated-app features       |
-| `adding-a-feature`    | **Read first when adding ANY new feature** — the four-area parity checklist       |
-| `real-time-sync`      | Before wiring data fetching for anything the agent can mutate (must auto-refresh) |
-| `storing-data`        | Before storing or reading any app state                                           |
-| `delegate-to-agent`   | Before adding LLM calls or AI delegation                                          |
-| `actions`             | Before creating or modifying actions                                              |
-| `self-modifying-code` | Before editing source, components, or styles                                      |
-| `capture-learnings`   | Before recording user preferences or corrections                                  |
-| `frontend-design`     | Before building or restyling any UI component, page, or layout                    |
-| `shadcn-ui`           | Before adding, updating, or debugging shadcn/ui components                        |
-| `agent-engines`       | Before switching LLM providers or registering a custom engine                     |
-| `notifications`       | Before surfacing alerts/progress to the user or adding channels                   |
-| `progress`            | Before running any task that takes more than a few seconds                        |
+| Skill                  | When to read                                                                      |
+| ---------------------- | --------------------------------------------------------------------------------- |
+| `agent-native-docs`    | Before using advanced Agent Native framework APIs or generated-app features       |
+| `adding-a-feature`     | **Read first when adding ANY new feature** — the four-area parity checklist       |
+| `real-time-sync`       | Before wiring data fetching for anything the agent can mutate (must auto-refresh) |
+| `storing-data`         | Before storing or reading any app state                                           |
+| `internationalization` | Before adding or editing visible UI copy, prompts, toasts, labels, or formatting  |
+| `delegate-to-agent`    | Before adding LLM calls or AI delegation                                          |
+| `actions`              | Before creating or modifying actions                                              |
+| `self-modifying-code`  | Before editing source, components, or styles                                      |
+| `capture-learnings`    | Before recording user preferences or corrections                                  |
+| `frontend-design`      | Before building or restyling any UI component, page, or layout                    |
+| `shadcn-ui`            | Before adding, updating, or debugging shadcn/ui components                        |
+| `agent-engines`        | Before switching LLM providers or registering a custom engine                     |
+| `notifications`        | Before surfacing alerts/progress to the user or adding channels                   |
+| `progress`             | Before running any task that takes more than a few seconds                        |
 
 ## When Adding Features
 

package/corpus/core/src/templates/default/app/i18n/en-US.ts

@@ -0,0 +1,29 @@
+const messages = {
+  home: {
+    settingsTitle: "Settings",
+    settingsDescription: "Language and agent preferences",
+    title: "Your app is running",
+    intro: "Start building by editing",
+    actionCardTitle: "Action-backed data",
+    loadingAction: "Loading action result...",
+    docsTitle: "Documentation",
+    docsDescription: "Learn the framework",
+    themeTitle: "Theme",
+    themeDescription: "Toggle dark / light",
+  },
+  settings: {
+    title: "Settings",
+    description: "Language and workspace preferences for this app.",
+    languageTitle: "Language",
+    languageDescription:
+      "Choose the interface language. This preference is saved for your account.",
+    languageLabel: "Interface language",
+    agentTitle: "Agent settings",
+    agentDescription:
+      "Open the agent sidebar settings for model, API keys, automations, voice, and other agent controls.",
+    openAgentSettings: "Open agent settings",
+    backHome: "Back to home",
+  },
+};
+
+export default messages;

package/corpus/core/src/templates/default/app/i18n/index.ts

@@ -0,0 +1,13 @@
+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) {
+      default:
+        return null;
+    }
+  },
+} satisfies AgentNativeI18nCatalog;