@agent-native/core 0.75.4 → 0.76.0

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

package/corpus/core/src/vite/action-types-plugin.ts

@@ -78,6 +78,16 @@ const CORE_SHARING_ACTIONS: Array<{ name: string; specifier: string }> = [
     name: "context-report",
     specifier: "@agent-native/core/agent/context-xray/actions/context-report",
   },
+  {
+    name: "get-localization-preference",
+    specifier:
+      "@agent-native/core/localization/actions/get-localization-preference",
+  },
+  {
+    name: "set-localization-preference",
+    specifier:
+      "@agent-native/core/localization/actions/set-localization-preference",
+  },
 ];
 
 function isRuntimeSourceFile(filename: string): boolean {

package/corpus/templates/analytics/.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/templates/analytics/app/components/layout/Header.tsx

@@ -6,22 +6,23 @@ import {
   useHeaderTitle,
   useHeaderActions,
 } from "./HeaderActions";
-import { AgentToggleButton } from "@agent-native/core/client";
+import { AgentToggleButton, LanguagePicker } from "@agent-native/core/client";
 import { RunsTray } from "@agent-native/core/client/progress";
+import { useT } from "@agent-native/core/client";
 
-const pageTitles: Record<string, string> = {
-  "/": "Overview",
-  "/data-sources": "Data Sources",
-  "/data-dictionary": "Data Dictionary",
-  "/catalog": "Template Catalog",
-  "/analyses": "Analyses",
-  "/dashboards/explorer": "Explorer",
-  "/team": "Team",
-  "/settings": "Settings",
+const pageTitleKeys: Record<string, string> = {
+  "/": "navigation.overview",
+  "/data-sources": "navigation.dataSources",
+  "/data-dictionary": "navigation.dataDictionary",
+  "/catalog": "navigation.templateCatalog",
+  "/analyses": "navigation.analyses",
+  "/dashboards/explorer": "navigation.explorer",
+  "/team": "navigation.team",
+  "/settings": "navigation.settings",
 };
 
-function resolveTitle(pathname: string): ReactNode {
-  if (pageTitles[pathname]) return pageTitles[pathname];
+function resolveTitle(pathname: string, t: (key: string) => string): ReactNode {
+  if (pageTitleKeys[pathname]) return t(pageTitleKeys[pathname]);
 
   const adhocMatch = pathname.match(/^\/(?:adhoc|dashboards)\/(.+)$/);
   if (adhocMatch) {
@@ -30,16 +31,17 @@ function resolveTitle(pathname: string): ReactNode {
     return dash?.name || <DashboardTitleSkeleton />;
   }
 
-  if (pathname.startsWith("/analyses/")) return "Analyses";
+  if (pathname.startsWith("/analyses/")) return t("navigation.analyses");
 
-  return "Analytics";
+  return t("navigation.brand");
 }
 
 export function Header() {
   const location = useLocation();
+  const t = useT();
   const title = useHeaderTitle();
   const actions = useHeaderActions();
-  const fallbackTitle = resolveTitle(location.pathname);
+  const fallbackTitle = resolveTitle(location.pathname, t);
 
   return (
     <header className="flex h-12 items-center gap-3 border-b border-border bg-background px-4 lg:px-6 shrink-0">
@@ -55,6 +57,7 @@ export function Header() {
       </div>
       <div className="flex items-center gap-2 shrink-0">
         {actions}
+        <LanguagePicker variant="icon" />
         <RunsTray pollMs={1500} />
         <AgentToggleButton />
       </div>

package/corpus/templates/analytics/app/components/layout/Layout.tsx

@@ -12,6 +12,7 @@ import {
   useAgentChatHomeHandoff,
   useAgentChatHomeHandoffLinks,
   useGuidedQuestionFlow,
+  useT,
 } from "@agent-native/core/client";
 import { InvitationBanner } from "@agent-native/core/client/org";
 import { useNavigationState } from "@/hooks/use-navigation-state";
@@ -27,6 +28,7 @@ export function Layout({ children }: LayoutProps) {
   useNavigationState();
   const location = useLocation();
   const navigate = useNavigate();
+  const t = useT();
 
   // Analytics has two distinct "primary resources" — dashboards
   // (`/dashboards/:id`, legacy `/adhoc/:id`) and ad-hoc analyses
@@ -149,12 +151,12 @@ export function Layout({ children }: LayoutProps) {
             browserTabId={TAB_ID}
             openOnChatRunning={chatHomeHandoffActive}
             onFullscreenRequest={openAskAgentFullscreen}
-            emptyStateText="Ask me to analyze a dashboard, compare trends, or dig into data..."
+            emptyStateText={t("chat.emptyState")}
             suggestions={[
-              "What's driving ARR growth this quarter?",
-              "Show me churn trends over the last 6 months",
-              "Analyze the HubSpot Sales dashboard for anomalies",
-              "Compare MRR between enterprise and SMB",
+              t("chat.suggestionArrGrowth"),
+              t("chat.suggestionChurn"),
+              t("chat.suggestionAnomalies"),
+              t("chat.suggestionMrr"),
             ]}
             scope={sidebarScope}
           >

package/corpus/templates/analytics/app/components/layout/MobileNav.tsx

@@ -3,10 +3,12 @@ import { useLocation } from "react-router";
 import { IconMenu, IconChartBar } from "@tabler/icons-react";
 import { Sheet, SheetContent, SheetTitle } from "@/components/ui/sheet";
 import { Sidebar } from "./Sidebar";
+import { useT } from "@agent-native/core/client";
 
 export function MobileNav() {
   const [open, setOpen] = useState(false);
   const location = useLocation();
+  const t = useT();
 
   // Auto-close on route change
   useEffect(() => {
@@ -18,7 +20,7 @@ export function MobileNav() {
       <button
         onClick={() => setOpen(true)}
         className="mr-3 p-2.5 -ml-1 rounded-md hover:bg-sidebar-accent/50"
-        aria-label="Open navigation"
+        aria-label={t("navigation.openNavigation")}
       >
         <IconMenu className="h-5 w-5 text-foreground" />
       </button>
@@ -26,12 +28,16 @@ export function MobileNav() {
         <div className="flex h-7 w-7 items-center justify-center rounded-lg bg-primary text-primary-foreground">
           <IconChartBar className="h-4 w-4" />
         </div>
-        <span className="text-base font-bold tracking-tight">Analytics</span>
+        <span className="text-base font-bold tracking-tight">
+          {t("navigation.brand")}
+        </span>
       </div>
 
       <Sheet open={open} onOpenChange={setOpen}>
         <SheetContent side="left" className="p-0 w-[280px]">
-          <SheetTitle className="sr-only">Navigation</SheetTitle>
+          <SheetTitle className="sr-only">
+            {t("navigation.navigation")}
+          </SheetTitle>
           <Sidebar mobile />
         </SheetContent>
       </Sheet>

package/corpus/templates/analytics/app/components/layout/Sidebar.tsx

@@ -96,6 +96,7 @@ import {
   navigateWithAgentChatViewTransition,
   useActionMutation,
   useChangeVersions,
+  useT,
 } from "@agent-native/core/client";
 import { ExtensionsSidebarSection } from "@agent-native/core/client/extensions";
 import { NewDashboardDialog } from "./NewDashboardDialog";
@@ -143,8 +144,8 @@ import {
 import { CSS } from "@dnd-kit/utilities";
 
 const bottomItems = [
-  { icon: IconUsers, label: "Team", href: "/team" },
-  { icon: IconSettings, label: "Settings", href: "/settings" },
+  { icon: IconUsers, labelKey: "navigation.team", href: "/team" },
+  { icon: IconSettings, labelKey: "navigation.settings", href: "/settings" },
 ];
 
 function getStoredBoolean(key: string, fallback: boolean): boolean {
@@ -1143,6 +1144,7 @@ function persistThemePreference(theme: "light" | "dark") {
 export function Sidebar({ mobile }: { mobile?: boolean } = {}) {
   const location = useLocation();
   const navigate = useNavigate();
+  const t = useT();
   const { logout } = useAuth();
   const queryClient = useQueryClient();
   const { resolvedTheme, setTheme } = useTheme();
@@ -2191,7 +2193,7 @@ export function Sidebar({ mobile }: { mobile?: boolean } = {}) {
                   )}
                 >
                   <Icon className="h-4 w-4" />
-                  {item.label}
+                  {t(item.labelKey)}
                 </Link>
               );
             })}

package/corpus/templates/analytics/app/i18n/ar-SA.ts

@@ -0,0 +1,3 @@
+import { messagesByLocale } from "../i18n-data";
+
+export default messagesByLocale["ar-SA"];

package/corpus/templates/analytics/app/i18n/de-DE.ts

@@ -0,0 +1,3 @@
+import { messagesByLocale } from "../i18n-data";
+
+export default messagesByLocale["de-DE"];

package/corpus/templates/analytics/app/i18n/en-US.ts

@@ -0,0 +1,3 @@
+import { messagesByLocale } from "../i18n-data";
+
+export default messagesByLocale["en-US"];

package/corpus/templates/analytics/app/i18n/es-ES.ts

@@ -0,0 +1,3 @@
+import { messagesByLocale } from "../i18n-data";
+
+export default messagesByLocale["es-ES"];

package/corpus/templates/analytics/app/i18n/fr-FR.ts

@@ -0,0 +1,3 @@
+import { messagesByLocale } from "../i18n-data";
+
+export default messagesByLocale["fr-FR"];

package/corpus/templates/analytics/app/i18n/hi-IN.ts

@@ -0,0 +1,3 @@
+import { messagesByLocale } from "../i18n-data";
+
+export default messagesByLocale["hi-IN"];

package/corpus/templates/analytics/app/i18n/index.ts

@@ -0,0 +1,31 @@
+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;
+      case "es-ES":
+        return (await import("./es-ES")).default;
+      case "fr-FR":
+        return (await import("./fr-FR")).default;
+      case "de-DE":
+        return (await import("./de-DE")).default;
+      case "ja-JP":
+        return (await import("./ja-JP")).default;
+      case "ko-KR":
+        return (await import("./ko-KR")).default;
+      case "pt-BR":
+        return (await import("./pt-BR")).default;
+      case "hi-IN":
+        return (await import("./hi-IN")).default;
+      case "ar-SA":
+        return (await import("./ar-SA")).default;
+      default:
+        return null;
+    }
+  },
+} satisfies AgentNativeI18nCatalog;

package/corpus/templates/analytics/app/i18n/ja-JP.ts

@@ -0,0 +1,3 @@
+import { messagesByLocale } from "../i18n-data";
+
+export default messagesByLocale["ja-JP"];

package/corpus/templates/analytics/app/i18n/ko-KR.ts

@@ -0,0 +1,3 @@
+import { messagesByLocale } from "../i18n-data";
+
+export default messagesByLocale["ko-KR"];

package/corpus/templates/analytics/app/i18n/pt-BR.ts

@@ -0,0 +1,3 @@
+import { messagesByLocale } from "../i18n-data";
+
+export default messagesByLocale["pt-BR"];

package/corpus/templates/analytics/app/i18n/zh-CN.ts

@@ -0,0 +1,3 @@
+import { messagesByLocale } from "../i18n-data";
+
+export default messagesByLocale["zh-CN"];