@agent-native/core 0.75.5 → 0.76.1

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.1",
   "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

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

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