@agent-native/core 0.75.4 → 0.76.0

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/server/self-dispatch.ts

@@ -20,7 +20,10 @@
  * A2A, integration webhooks, and Agent Teams sub-agents share one tested
  * implementation.
  */
-import { withConfiguredAppBasePath } from "./app-base-path.js";
+import {
+  getConfiguredAppBasePath,
+  withConfiguredAppBasePath,
+} from "./app-base-path.js";
 import { isLocalDatabase } from "../db/client.js";
 import { signInternalToken } from "../integrations/internal-token.js";
 
@@ -119,11 +122,35 @@ async function dispatchResponseError(
  * processor accepts unsigned dispatches in dev and relies on the SQL atomic
  * claim for double-processing protection, mirroring the A2A/webhook flow.
  */
+/**
+ * For host-root dispatch targets (`/.netlify/functions/*`), strip the configured
+ * app base path suffix from the resolved base url so the request reaches the
+ * function at the host root rather than under the workspace app base path. For
+ * every other (framework-route) path the base-path-prefixed base url is returned
+ * unchanged, preserving the existing self-dispatch behavior.
+ */
+function rootBaseUrlForPath(baseUrl: string, path: string): string {
+  if (!path.startsWith("/.netlify/")) return baseUrl;
+  const basePath = getConfiguredAppBasePath();
+  if (!basePath) return baseUrl;
+  const trimmed = baseUrl.replace(/\/$/, "");
+  if (trimmed.endsWith(basePath)) {
+    return trimmed.slice(0, trimmed.length - basePath.length);
+  }
+  return trimmed;
+}
+
 export async function fireInternalDispatch(
   options: FireInternalDispatchOptions,
 ): Promise<void> {
   const baseUrl = options.baseUrl ?? resolveSelfDispatchBaseUrl(options.event);
-  const url = `${baseUrl}${options.path}`;
+  // Netlify function default urls (`/.netlify/functions/<name>`) live at the
+  // HOST ROOT, not under the workspace app base path. `resolveSelfDispatchBaseUrl`
+  // appends the configured base path (e.g. `https://host/starter`) so framework
+  // routes land on the right app; for a host-root function url we must dispatch
+  // to `https://host/.netlify/functions/<name>` instead. Strip the base path
+  // suffix from the resolved base url for `/.netlify/*` dispatch targets only.
+  const url = `${rootBaseUrlForPath(baseUrl, options.path)}${options.path}`;
   const headers: Record<string, string> = {
     "Content-Type": "application/json",
   };

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;

package/corpus/core/src/templates/default/app/root.tsx

@@ -14,11 +14,13 @@ import { useDbSync } from "@agent-native/core/client";
 import {
   AppProviders,
   appPath,
+  getLocaleInitScript,
   getThemeInitScript,
   createAgentNativeQueryClient,
 } from "@agent-native/core/client";
 import { configureTracking } from "@agent-native/core/client";
 import { useNavigationState } from "./hooks/use-navigation-state";
+import { i18nCatalog } from "./i18n";
 import { TAB_ID } from "./lib/tab-id";
 configureTracking({
   getDefaultProps: (_name, properties) => ({
@@ -29,6 +31,7 @@ configureTracking({
 import "./global.css";
 
 const THEME_INIT_SCRIPT_SELECTOR = "script[data-agent-native-theme-init]";
+const LOCALE_INIT_SCRIPT_SELECTOR = "script[data-agent-native-locale-init]";
 
 function getHydrationStableThemeInitScript() {
   if (typeof document !== "undefined") {
@@ -40,7 +43,18 @@ function getHydrationStableThemeInitScript() {
   return getThemeInitScript();
 }
 
+function getHydrationStableLocaleInitScript() {
+  if (typeof document !== "undefined") {
+    const existing = document.querySelector<HTMLScriptElement>(
+      LOCALE_INIT_SCRIPT_SELECTOR,
+    );
+    if (existing?.innerHTML) return existing.innerHTML;
+  }
+  return getLocaleInitScript();
+}
+
 const THEME_INIT_SCRIPT = getHydrationStableThemeInitScript();
+const LOCALE_INIT_SCRIPT = getHydrationStableLocaleInitScript();
 
 export function Layout({ children }: { children: React.ReactNode }) {
   return (
@@ -56,6 +70,11 @@ export function Layout({ children }: { children: React.ReactNode }) {
           suppressHydrationWarning
           dangerouslySetInnerHTML={{ __html: THEME_INIT_SCRIPT }}
         />
+        <script
+          data-agent-native-locale-init
+          suppressHydrationWarning
+          dangerouslySetInnerHTML={{ __html: LOCALE_INIT_SCRIPT }}
+        />
         <link rel="manifest" href={appPath("/manifest.json")} />
         <link rel="icon" type="image/svg+xml" href={appPath("/favicon.svg")} />
         <meta name="theme-color" content="#111111" />
@@ -88,7 +107,7 @@ function DbSyncSetup() {
 export default function Root() {
   const [queryClient] = useState(() => createAgentNativeQueryClient());
   return (
-    <AppProviders queryClient={queryClient}>
+    <AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
       <DbSyncSetup />
       <Outlet />
     </AppProviders>

package/corpus/core/src/templates/default/app/routes/_index.tsx

@@ -1,5 +1,6 @@
 import { useTheme } from "next-themes";
-import { useActionQuery } from "@agent-native/core/client";
+import { Link } from "react-router";
+import { useActionQuery, useT } from "@agent-native/core/client";
 
 export function meta() {
   return [{ title: "{{APP_TITLE}}" }];
@@ -7,6 +8,7 @@ export function meta() {
 
 export default function IndexPage() {
   const { resolvedTheme, setTheme } = useTheme();
+  const t = useT();
   const isDark = resolvedTheme === "dark";
   const { data } = useActionQuery("hello", { name: "{{APP_TITLE}}" });
 
@@ -15,10 +17,10 @@ export default function IndexPage() {
       <div className="max-w-md w-full space-y-8 text-center">
         <div className="space-y-3">
           <h1 className="text-2xl font-semibold tracking-tight text-foreground">
-            Your app is running
+            {t("home.title")}
           </h1>
           <p className="text-[14px] text-muted-foreground leading-relaxed">
-            Start building by editing{" "}
+            {t("home.intro")}{" "}
             <code className="text-[13px] bg-muted px-1.5 py-0.5 rounded font-mono">
               app/routes/_index.tsx
             </code>
@@ -29,10 +31,10 @@ export default function IndexPage() {
 
         <div className="rounded-lg border border-border/50 px-4 py-3 text-left">
           <p className="text-[13px] font-medium text-foreground">
-            Action-backed data
+            {t("home.actionCardTitle")}
           </p>
           <p className="text-[12px] text-muted-foreground mt-0.5">
-            {data?.message ?? "Loading action result..."}
+            {data?.message ?? t("home.loadingAction")}
           </p>
         </div>
 
@@ -44,21 +46,34 @@ export default function IndexPage() {
             className="group rounded-lg border border-border/50 px-4 py-3 hover:bg-accent/50 transition-colors"
           >
             <p className="text-[13px] font-medium text-foreground">
-              Documentation
+              {t("home.docsTitle")}
             </p>
             <p className="text-[12px] text-muted-foreground mt-0.5">
-              Learn the framework
+              {t("home.docsDescription")}
             </p>
           </a>
           <button
             onClick={() => setTheme(isDark ? "light" : "dark")}
             className="rounded-lg border border-border/50 px-4 py-3 hover:bg-accent/50 transition-colors text-left"
           >
-            <p className="text-[13px] font-medium text-foreground">Theme</p>
+            <p className="text-[13px] font-medium text-foreground">
+              {t("home.themeTitle")}
+            </p>
             <p className="text-[12px] text-muted-foreground mt-0.5">
-              Toggle dark / light
+              {t("home.themeDescription")}
             </p>
           </button>
+          <Link
+            to="/settings"
+            className="group rounded-lg border border-border/50 px-4 py-3 hover:bg-accent/50 transition-colors"
+          >
+            <p className="text-[13px] font-medium text-foreground">
+              {t("home.settingsTitle")}
+            </p>
+            <p className="text-[12px] text-muted-foreground mt-0.5">
+              {t("home.settingsDescription")}
+            </p>
+          </Link>
         </div>
       </div>
     </div>

package/corpus/core/src/templates/default/app/routes/settings.tsx

@@ -0,0 +1,67 @@
+import { Link } from "react-router";
+import {
+  LanguagePicker,
+  openAgentSettings,
+  useT,
+} from "@agent-native/core/client";
+
+export function meta() {
+  return [{ title: "Settings - {{APP_TITLE}}" }];
+}
+
+export default function SettingsPage() {
+  const t = useT();
+
+  return (
+    <main className="min-h-screen bg-background px-6 py-10">
+      <div className="mx-auto w-full max-w-2xl space-y-6">
+        <div className="space-y-2">
+          <Link
+            to="/"
+            className="text-[13px] text-muted-foreground hover:text-foreground"
+          >
+            {t("settings.backHome")}
+          </Link>
+          <h1 className="text-2xl font-semibold tracking-tight text-foreground">
+            {t("settings.title")}
+          </h1>
+          <p className="text-[14px] leading-relaxed text-muted-foreground">
+            {t("settings.description")}
+          </p>
+        </div>
+
+        <section className="rounded-lg border border-border/50 bg-card px-4 py-4">
+          <div className="space-y-1">
+            <h2 className="text-[15px] font-semibold text-foreground">
+              {t("settings.languageTitle")}
+            </h2>
+            <p className="text-[13px] leading-relaxed text-muted-foreground">
+              {t("settings.languageDescription")}
+            </p>
+          </div>
+          <div className="mt-4 max-w-xs">
+            <LanguagePicker label={t("settings.languageLabel")} />
+          </div>
+        </section>
+
+        <section className="rounded-lg border border-border/50 bg-card px-4 py-4">
+          <div className="space-y-1">
+            <h2 className="text-[15px] font-semibold text-foreground">
+              {t("settings.agentTitle")}
+            </h2>
+            <p className="text-[13px] leading-relaxed text-muted-foreground">
+              {t("settings.agentDescription")}
+            </p>
+          </div>
+          <button
+            type="button"
+            className="mt-4 rounded-md border border-border bg-background px-3 py-2 text-[13px] font-medium text-foreground transition-colors hover:bg-accent/50"
+            onClick={() => openAgentSettings()}
+          >
+            {t("settings.openAgentSettings")}
+          </button>
+        </section>
+      </div>
+    </main>
+  );
+}

package/corpus/core/src/templates/workspace-core/.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