@agent-native/core 0.75.5 → 0.76.0

package/corpus/core/src/client/app-providers.tsx

@@ -53,6 +53,10 @@ import { TooltipProvider } from "@radix-ui/react-tooltip";
 import { Toaster } from "sonner";
 import { ClientOnly } from "./ClientOnly.js";
 import { DefaultSpinner } from "./DefaultSpinner.js";
+import {
+  AgentNativeI18nProvider,
+  type AgentNativeI18nProviderProps,
+} from "./i18n.js";
 
 export interface AppProvidersProps {
   /** QueryClient instance — create with `createAgentNativeQueryClient()`. */
@@ -94,6 +98,13 @@ export interface AppProvidersProps {
    */
   disableThemeTransitions?: boolean;
 
+  /**
+   * Optional localization runtime configuration. When omitted, AppProviders
+   * still mounts the i18n provider with an English fallback so templates can
+   * call useT/useLocale before they add catalogs. Pass false to opt out.
+   */
+  i18n?: Omit<AgentNativeI18nProviderProps, "children"> | false;
+
   /**
    * When true the providers render without a `<ClientOnly>` gate so SSR
    * streams real markup for public/unauthenticated paths.
@@ -119,6 +130,7 @@ function ProvidersInner({
   tooltipDelayDuration,
   toaster = DEFAULT_TOASTER,
   disableThemeTransitions = true,
+  i18n,
   children,
 }: {
   queryClient: QueryClient;
@@ -127,8 +139,18 @@ function ProvidersInner({
   tooltipDelayDuration?: number;
   toaster?: React.ReactNode | null;
   disableThemeTransitions?: boolean;
+  i18n?: Omit<AgentNativeI18nProviderProps, "children"> | false;
   children: React.ReactNode;
 }) {
+  const localizedChildren =
+    i18n === false ? (
+      children
+    ) : (
+      <AgentNativeI18nProvider {...(i18n ?? {})}>
+        {children}
+      </AgentNativeI18nProvider>
+    );
+
   return (
     <QueryClientProvider client={queryClient}>
       <ThemeProvider
@@ -138,7 +160,7 @@ function ProvidersInner({
         disableTransitionOnChange={disableThemeTransitions}
       >
         <TooltipProvider delayDuration={tooltipDelayDuration}>
-          {children}
+          {localizedChildren}
           {toaster}
         </TooltipProvider>
       </ThemeProvider>
@@ -155,6 +177,7 @@ export function AppProviders({
   tooltipDelayDuration,
   toaster,
   disableThemeTransitions,
+  i18n,
   children,
 }: AppProvidersProps) {
   const fallback = clientOnlyFallback ?? <DefaultSpinner />;
@@ -168,6 +191,7 @@ export function AppProviders({
         tooltipDelayDuration={tooltipDelayDuration}
         toaster={toaster}
         disableThemeTransitions={disableThemeTransitions}
+        i18n={i18n}
       >
         {children}
       </ProvidersInner>
@@ -183,6 +207,7 @@ export function AppProviders({
         tooltipDelayDuration={tooltipDelayDuration}
         toaster={toaster}
         disableThemeTransitions={disableThemeTransitions}
+        i18n={i18n}
       >
         {children}
       </ProvidersInner>

package/corpus/core/src/client/i18n.tsx

@@ -0,0 +1,605 @@
+import * as SelectPrimitive from "@radix-ui/react-select";
+import { IconCheck, IconChevronDown, IconLanguage } from "@tabler/icons-react";
+import i18next, { type i18n as I18nInstance } from "i18next";
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import {
+  I18nextProvider,
+  initReactI18next,
+  useTranslation,
+} from "react-i18next";
+import { callAction } from "./use-action.js";
+import { setClientAppState } from "./application-state.js";
+import {
+  DEFAULT_LOCALE,
+  LOCALE_HYDRATION_GLOBAL,
+  LOCALE_METADATA,
+  LOCALE_STORAGE_KEY,
+  SUPPORTED_LOCALES,
+  localeDirection,
+  normalizeLocalizationPreference,
+  resolveLocaleFromCandidates,
+  resolveLocaleFromPreference,
+  type LocaleCode,
+  type LocaleMetadata,
+  type LocalePreference,
+  type LocalizationPreference,
+} from "../localization/shared.js";
+
+export {
+  DEFAULT_LOCALE,
+  LOCALE_HYDRATION_GLOBAL,
+  LOCALE_METADATA,
+  LOCALE_STORAGE_KEY,
+  SUPPORTED_LOCALES,
+  localeDirection,
+  normalizeLocaleCode,
+  normalizeLocalePreference,
+  normalizeLocalizationPreference,
+  resolveLocaleFromCandidates,
+  resolveLocaleFromPreference,
+  type LocaleCode,
+  type LocaleMetadata,
+  type LocalePreference,
+  type LocalizationPreference,
+} from "../localization/shared.js";
+export { getLocaleInitScript } from "../localization/server.js";
+
+export type LocaleMessages = Record<string, unknown>;
+
+export interface LocaleHydrationPayload {
+  locale?: LocaleCode;
+  preference?: LocalizationPreference;
+  dir?: "ltr" | "rtl";
+  messages?: LocaleMessages;
+}
+
+export interface AgentNativeI18nCatalog {
+  namespace?: string;
+  sourceLocale?: LocaleCode;
+  messages?: LocaleMessages;
+  loadMessages?: (locale: LocaleCode) => Promise<LocaleMessages | null>;
+}
+
+export interface AgentNativeI18nProviderProps {
+  children: React.ReactNode;
+  catalog?: AgentNativeI18nCatalog;
+  initialLocale?: LocaleCode;
+  initialPreference?: LocalizationPreference | LocalePreference;
+  initialMessages?: LocaleMessages | null;
+  persistPreference?: boolean;
+}
+
+interface LocaleContextValue {
+  locale: LocaleCode;
+  preference: LocalePreference;
+  dir: "ltr" | "rtl";
+  metadata: LocaleMetadata;
+  setPreference: (preference: LocalePreference) => Promise<void>;
+  loading: boolean;
+}
+
+declare global {
+  interface Window {
+    __AGENT_NATIVE_LOCALE__?: LocaleHydrationPayload;
+  }
+}
+
+const LocaleContext = createContext<LocaleContextValue | null>(null);
+
+const LANGUAGE_PICKER_COPY: Record<
+  LocaleCode,
+  { label: string; system: string; systemDescription: string }
+> = {
+  "en-US": {
+    label: "Language",
+    system: "System",
+    systemDescription: "Use your browser language",
+  },
+  "zh-CN": {
+    label: "语言",
+    system: "系统",
+    systemDescription: "使用浏览器语言",
+  },
+  "es-ES": {
+    label: "Idioma",
+    system: "Sistema",
+    systemDescription: "Usar el idioma del navegador",
+  },
+  "fr-FR": {
+    label: "Langue",
+    system: "Système",
+    systemDescription: "Utiliser la langue du navigateur",
+  },
+  "de-DE": {
+    label: "Sprache",
+    system: "System",
+    systemDescription: "Browsersprache verwenden",
+  },
+  "ja-JP": {
+    label: "言語",
+    system: "システム",
+    systemDescription: "ブラウザーの言語を使用",
+  },
+  "ko-KR": {
+    label: "언어",
+    system: "시스템",
+    systemDescription: "브라우저 언어 사용",
+  },
+  "pt-BR": {
+    label: "Idioma",
+    system: "Sistema",
+    systemDescription: "Usar o idioma do navegador",
+  },
+  "hi-IN": {
+    label: "भाषा",
+    system: "सिस्टम",
+    systemDescription: "ब्राउज़र की भाषा का उपयोग करें",
+  },
+  "ar-SA": {
+    label: "اللغة",
+    system: "النظام",
+    systemDescription: "استخدام لغة المتصفح",
+  },
+};
+
+function browserLanguageCandidates(): string[] {
+  if (typeof navigator === "undefined") return [];
+  return navigator.languages?.length
+    ? [...navigator.languages]
+    : navigator.language
+      ? [navigator.language]
+      : [];
+}
+
+function readStoredPreference(): LocalePreference | null {
+  if (typeof window === "undefined") return null;
+  try {
+    return normalizeLocalizationPreference(
+      window.localStorage.getItem(LOCALE_STORAGE_KEY),
+    ).locale;
+  } catch {
+    return null;
+  }
+}
+
+function writeStoredPreference(preference: LocalePreference) {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(LOCALE_STORAGE_KEY, preference);
+  } catch {
+    // Ignore storage-denied browsers; the in-memory provider state still works.
+  }
+}
+
+function readHydrationPayload(): LocaleHydrationPayload {
+  if (typeof window === "undefined") return {};
+  return window[LOCALE_HYDRATION_GLOBAL] ?? {};
+}
+
+function resolveInitialState(args: {
+  initialLocale?: LocaleCode;
+  initialPreference?: LocalizationPreference | LocalePreference;
+}): { locale: LocaleCode; preference: LocalePreference } {
+  const hydration = readHydrationPayload();
+  const preference = normalizeLocalizationPreference(
+    args.initialPreference ?? hydration.preference ?? readStoredPreference(),
+  ).locale;
+  const locale =
+    args.initialLocale ??
+    hydration.locale ??
+    resolveLocaleFromPreference(preference, browserLanguageCandidates());
+  return { locale, preference };
+}
+
+function normalizeLoadedMessages(value: unknown): LocaleMessages | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const maybeDefault = (value as { default?: unknown }).default;
+  if (
+    maybeDefault &&
+    typeof maybeDefault === "object" &&
+    !Array.isArray(maybeDefault)
+  ) {
+    return maybeDefault as LocaleMessages;
+  }
+  return value as LocaleMessages;
+}
+
+function createI18nInstance(args: {
+  namespace: string;
+  sourceLocale: LocaleCode;
+  messages: LocaleMessages;
+  initialLocale: LocaleCode;
+  initialMessages?: LocaleMessages | null;
+}): I18nInstance {
+  const instance = i18next.createInstance();
+  const resources: Record<string, Record<string, LocaleMessages>> = {
+    [args.sourceLocale]: {
+      [args.namespace]: args.messages,
+    },
+  };
+  if (args.initialLocale !== args.sourceLocale && args.initialMessages) {
+    resources[args.initialLocale] = {
+      [args.namespace]: args.initialMessages,
+    };
+  }
+  void instance.use(initReactI18next).init({
+    resources,
+    lng: args.initialLocale,
+    fallbackLng: args.sourceLocale,
+    defaultNS: args.namespace,
+    ns: [args.namespace],
+    interpolation: { escapeValue: false },
+    react: { useSuspense: false },
+    returnNull: false,
+    initAsync: false,
+  });
+  return instance;
+}
+
+export function AgentNativeI18nProvider({
+  children,
+  catalog,
+  initialLocale,
+  initialPreference,
+  initialMessages,
+  persistPreference = true,
+}: AgentNativeI18nProviderProps) {
+  const namespace = catalog?.namespace ?? "translation";
+  const sourceLocale = catalog?.sourceLocale ?? DEFAULT_LOCALE;
+  const sourceMessages = catalog?.messages ?? {};
+  const loadMessages = catalog?.loadMessages;
+  const hydration = readHydrationPayload();
+  const initialState = useMemo(
+    () => resolveInitialState({ initialLocale, initialPreference }),
+    [initialLocale, initialPreference],
+  );
+  const [preference, setPreferenceState] = useState<LocalePreference>(
+    initialState.preference,
+  );
+  const [locale, setLocale] = useState<LocaleCode>(initialState.locale);
+  const [loading, setLoading] = useState(false);
+  const i18nRef = useRef<I18nInstance | null>(null);
+
+  if (!i18nRef.current) {
+    const preloadedMessages = normalizeLoadedMessages(
+      hydration.locale === initialState.locale && hydration.messages
+        ? hydration.messages
+        : initialMessages,
+    );
+    i18nRef.current = createI18nInstance({
+      namespace,
+      sourceLocale,
+      messages:
+        hydration.locale === sourceLocale && hydration.messages
+          ? hydration.messages
+          : sourceMessages,
+      initialLocale: initialState.locale,
+      initialMessages: preloadedMessages,
+    });
+  }
+
+  const i18n = i18nRef.current;
+
+  useEffect(() => {
+    if (i18n.hasResourceBundle(sourceLocale, namespace)) {
+      i18n.addResourceBundle(
+        sourceLocale,
+        namespace,
+        sourceMessages,
+        true,
+        true,
+      );
+    }
+  }, [i18n, namespace, sourceLocale, sourceMessages]);
+
+  useEffect(() => {
+    const nextLocale =
+      preference === "system"
+        ? resolveLocaleFromCandidates(browserLanguageCandidates())
+        : preference;
+    setLocale(nextLocale);
+  }, [preference]);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function applyLocale() {
+      setLoading(true);
+      try {
+        if (
+          locale !== sourceLocale &&
+          !i18n.hasResourceBundle(locale, namespace)
+        ) {
+          const preloaded =
+            hydration.locale === locale && hydration.messages
+              ? hydration.messages
+              : initialLocale === locale && initialMessages
+                ? initialMessages
+                : null;
+          const loaded = preloaded ?? (await loadMessages?.(locale));
+          const messages = normalizeLoadedMessages(loaded);
+          if (messages) {
+            i18n.addResourceBundle(locale, namespace, messages, true, true);
+          }
+        }
+        if (!cancelled) {
+          await i18n.changeLanguage(locale);
+        }
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    }
+
+    void applyLocale();
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    hydration.locale,
+    hydration.messages,
+    i18n,
+    initialLocale,
+    initialMessages,
+    loadMessages,
+    locale,
+    namespace,
+    sourceLocale,
+  ]);
+
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const dir = localeDirection(locale);
+    const root = document.documentElement;
+    root.setAttribute("lang", locale);
+    root.setAttribute("dir", dir);
+    root.setAttribute("data-locale", locale);
+  }, [locale]);
+
+  useEffect(() => {
+    if (!persistPreference) return;
+    let cancelled = false;
+    callAction<LocalizationPreference>(
+      "get-localization-preference",
+      undefined,
+      { method: "GET" },
+    )
+      .then((value) => {
+        if (cancelled) return;
+        const normalized = normalizeLocalizationPreference(value).locale;
+        setPreferenceState(normalized);
+        writeStoredPreference(normalized);
+      })
+      .catch(() => {
+        // Anonymous/public routes use localStorage/browser language only.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [persistPreference]);
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const onStorage = (event: StorageEvent) => {
+      if (event.key !== LOCALE_STORAGE_KEY || event.newValue == null) return;
+      setPreferenceState(
+        normalizeLocalizationPreference(event.newValue).locale,
+      );
+    };
+    window.addEventListener("storage", onStorage);
+    return () => window.removeEventListener("storage", onStorage);
+  }, []);
+
+  useEffect(() => {
+    void setClientAppState(
+      "localization",
+      {
+        locale,
+        preference,
+        dir: localeDirection(locale),
+      },
+      { requestSource: "localization" },
+    ).catch(() => {
+      // Public/anonymous pages cannot write app-state; localization still works.
+    });
+  }, [locale, preference]);
+
+  const setPreference = useCallback(
+    async (next: LocalePreference) => {
+      const normalized = normalizeLocalizationPreference(next).locale;
+      setPreferenceState(normalized);
+      writeStoredPreference(normalized);
+      if (!persistPreference) return;
+      try {
+        await callAction<LocalizationPreference>(
+          "set-localization-preference",
+          {
+            locale: normalized,
+          },
+        );
+      } catch (error) {
+        const status = (error as { status?: unknown })?.status;
+        if (status !== 401 && status !== 403) {
+          throw error;
+        }
+      }
+    },
+    [persistPreference],
+  );
+
+  const context = useMemo<LocaleContextValue>(
+    () => ({
+      locale,
+      preference,
+      dir: localeDirection(locale),
+      metadata: LOCALE_METADATA[locale],
+      setPreference,
+      loading,
+    }),
+    [loading, locale, preference, setPreference],
+  );
+
+  return (
+    <LocaleContext.Provider value={context}>
+      <I18nextProvider i18n={i18n}>{children}</I18nextProvider>
+    </LocaleContext.Provider>
+  );
+}
+
+export function useLocale(): LocaleContextValue {
+  const value = useContext(LocaleContext);
+  if (!value) {
+    throw new Error("useLocale must be used within AgentNativeI18nProvider");
+  }
+  return value;
+}
+
+export function useT() {
+  return useTranslation().t;
+}
+
+export function useFormatters() {
+  const { locale } = useLocale();
+  return useMemo(
+    () => ({
+      formatDate(
+        value: Date | number | string,
+        options?: Intl.DateTimeFormatOptions,
+      ) {
+        return new Intl.DateTimeFormat(locale, options).format(
+          value instanceof Date ? value : new Date(value),
+        );
+      },
+      formatNumber(value: number, options?: Intl.NumberFormatOptions) {
+        return new Intl.NumberFormat(locale, options).format(value);
+      },
+      formatRelativeTime(
+        value: number,
+        unit: Intl.RelativeTimeFormatUnit,
+        options?: Intl.RelativeTimeFormatOptions,
+      ) {
+        return new Intl.RelativeTimeFormat(locale, options).format(value, unit);
+      },
+      formatList(value: string[], options?: Intl.ListFormatOptions) {
+        return new Intl.ListFormat(locale, options).format(value);
+      },
+    }),
+    [locale],
+  );
+}
+
+export function LanguagePicker({
+  className,
+  includeSystem = true,
+  label,
+  variant = "select",
+}: {
+  className?: string;
+  includeSystem?: boolean;
+  label?: string;
+  variant?: "select" | "icon";
+}) {
+  const { locale, preference, setPreference } = useLocale();
+  const copy =
+    LANGUAGE_PICKER_COPY[locale] ?? LANGUAGE_PICKER_COPY[DEFAULT_LOCALE];
+  const resolvedLabel = label ?? copy.label;
+  const options = [
+    ...(includeSystem
+      ? [
+          {
+            value: "system" as const,
+            label: copy.system,
+            description: copy.systemDescription,
+          },
+        ]
+      : []),
+    ...SUPPORTED_LOCALES.map((code) => ({
+      value: code,
+      label:
+        LOCALE_METADATA[code].nativeName === LOCALE_METADATA[code].englishName
+          ? LOCALE_METADATA[code].nativeName
+          : `${LOCALE_METADATA[code].nativeName} (${LOCALE_METADATA[code].englishName})`,
+      description: code,
+    })),
+  ];
+  const selected = options.find((option) => option.value === preference);
+
+  return (
+    <div className={className}>
+      <SelectPrimitive.Root
+        value={preference}
+        onValueChange={(value) =>
+          void setPreference(normalizeLocalizationPreference(value).locale)
+        }
+      >
+        <SelectPrimitive.Trigger
+          className={
+            variant === "icon"
+              ? "flex h-8 w-8 items-center justify-center rounded-md border border-border bg-background text-foreground outline-none transition-colors hover:bg-accent/40 data-[placeholder]:text-muted-foreground"
+              : "flex h-9 w-full items-center justify-between rounded-md border border-border bg-background px-3 text-left text-[12px] text-foreground outline-none transition-colors hover:bg-accent/40 data-[placeholder]:text-muted-foreground"
+          }
+          aria-label={resolvedLabel}
+          title={selected?.label ?? resolvedLabel}
+        >
+          <span className="flex min-w-0 items-center gap-2">
+            <IconLanguage className="h-4 w-4 shrink-0 text-muted-foreground" />
+            {variant === "select" ? (
+              <SelectPrimitive.Value>
+                <span className="truncate">
+                  {selected?.label ?? preference}
+                </span>
+              </SelectPrimitive.Value>
+            ) : null}
+          </span>
+          {variant === "select" ? (
+            <SelectPrimitive.Icon asChild>
+              <IconChevronDown className="h-3.5 w-3.5 text-muted-foreground" />
+            </SelectPrimitive.Icon>
+          ) : null}
+        </SelectPrimitive.Trigger>
+        <SelectPrimitive.Portal>
+          <SelectPrimitive.Content
+            position="popper"
+            sideOffset={6}
+            className={
+              variant === "icon"
+                ? "z-[9999] min-w-56 overflow-hidden rounded-lg border border-border bg-popover shadow-lg"
+                : "z-[9999] w-[var(--radix-select-trigger-width)] overflow-hidden rounded-lg border border-border bg-popover shadow-lg"
+            }
+          >
+            <SelectPrimitive.Viewport className="p-1">
+              {options.map((option) => (
+                <SelectPrimitive.Item
+                  key={option.value}
+                  value={option.value}
+                  className="relative flex w-full cursor-pointer select-none items-start gap-2 rounded-md px-8 py-2.5 text-[12px] outline-none data-[highlighted]:bg-accent/60 data-[state=checked]:bg-accent/40"
+                >
+                  <span className="absolute left-2 top-2.5 flex h-4 w-4 items-center justify-center text-muted-foreground">
+                    <SelectPrimitive.ItemIndicator>
+                      <IconCheck className="h-3.5 w-3.5" />
+                    </SelectPrimitive.ItemIndicator>
+                  </span>
+                  <div className="flex min-w-0 flex-col">
+                    <SelectPrimitive.ItemText>
+                      <span className="text-foreground">{option.label}</span>
+                    </SelectPrimitive.ItemText>
+                    <span className="mt-0.5 text-[11px] leading-relaxed text-muted-foreground">
+                      {option.description}
+                    </span>
+                  </div>
+                </SelectPrimitive.Item>
+              ))}
+            </SelectPrimitive.Viewport>
+          </SelectPrimitive.Content>
+        </SelectPrimitive.Portal>
+      </SelectPrimitive.Root>
+    </div>
+  );
+}