@xndrjs/i18n-react 0.8.0 → 0.8.2-alpha.0

package/README.md

@@ -0,0 +1,125 @@
+# @xndrjs/i18n-react
+
+React bindings for [`@xndrjs/i18n`](../i18n): a shared root, colocated namespace gates, and codegen that emits typed `I18nRoot` / `withI18n` / `I18n` for your project.
+
+- **No Suspense** for translation loads — readiness is explicit via gate / HOC fallbacks.
+- **SSR → CSR** hydrate with `state` from `serialize()` so warm namespaces resolve via `peek` without a flash.
+- **Apps import generated bindings**; this package’s public surface is mainly what codegen and advanced wiring need.
+
+## Install
+
+```bash
+npm install @xndrjs/i18n @xndrjs/i18n-react zod
+```
+
+Peers: `@xndrjs/i18n` ^0.8, `react` ≥ 19, `zod`.
+
+## Codegen
+
+Uses the same `i18n.codegen.json` as core. Run **after** `xndrjs-i18n-codegen`:
+
+```bash
+npx xndrjs-i18n-react-codegen --config i18n/i18n.codegen.json
+```
+
+Optional `i18n-react.codegen.json` next to the core config can override the bindings output path (`output`). Default: `{codegenPath}/react-bindings.generated.tsx`.
+
+Prefer one script that runs core first, then React:
+
+```json
+{
+  "scripts": {
+    "i18n:codegen": "xndrjs-i18n-codegen --config i18n/i18n.codegen.json",
+    "i18n:react-codegen": "xndrjs-i18n-react-codegen --config i18n/i18n.codegen.json",
+    "i18n:generate": "pnpm i18n:codegen && pnpm i18n:react-codegen"
+  }
+}
+```
+
+Generated exports typically include:
+
+| Export        | Role                                                           |
+| ------------- | -------------------------------------------------------------- |
+| `I18nRoot`    | Provider over handle + load coordinator + locale               |
+| `withI18n`    | HOC gate — injects `{ t, locale }` when namespaces are ready   |
+| `I18n`        | Render-prop gate — same readiness model, shell can mount first |
+| `useI18nRoot` | Access the typed handle from under the root                    |
+
+With `loaderStrategy: "fetch"`, generated `I18nRoot` requires `fetchImpl` (same DI as `createI18n({ fetchImpl })`).
+
+## SSR → CSR
+
+On the server, load what the page needs and serialize:
+
+```ts
+import { createI18n } from "./generated/instance.generated.js";
+
+const i18n = createI18n();
+const { t } = await i18n.load({
+  namespaces: ["default", "billing"],
+  locale,
+});
+const state = i18n.serialize();
+```
+
+Pass `state` into the client root so hydration reuses loaded namespaces:
+
+```tsx
+import { I18nRoot, withI18n } from "./generated/react-bindings.generated";
+
+<I18nRoot locale={locale} state={state}>
+  <BillingPanel invoiceCount={3} />
+</I18nRoot>;
+```
+
+Omit `state` only when you intentionally cold-start on the client (gates show `fallback` until load settles).
+
+## `withI18n` (HOC)
+
+Prefer when you need `t` before the `return` (branching, derived labels, building children):
+
+```tsx
+const BillingPanel = withI18n<{ invoiceCount: number }>(
+  { namespaces: ["billing"], fallback: <p>Loading…</p> },
+  function BillingPanel({ invoiceCount }, { t }) {
+    return <p>{t("billing", "invoice_summary", { count: invoiceCount })}</p>;
+  }
+);
+```
+
+Own props stay yours; `t` / `locale` are the second argument. Wrong keys or params fail at compile time.
+
+Hooks inside the render function are supported across `pending` → `ready` (including when `I18nRoot` has no hydrated `state`). The Outer always invokes `render` so hook order stays stable; until namespaces are ready it still returns your `fallback` (with a no-op `t` during that discarded render).
+
+## `<I18n>` (gate)
+
+Prefer when the shell can render and translation is a leaf inside JSX:
+
+```tsx
+function BillingPanel({ invoiceCount }: { invoiceCount: number }) {
+  return (
+    <I18n namespaces={["billing"]} fallback={<p>Loading…</p>}>
+      {({ t }) => <p>{t("billing", "invoice_summary", { count: invoiceCount })}</p>}
+    </I18n>
+  );
+}
+```
+
+Missing namespaces show your fallback for **that gate only**. If a load fails and you omit `renderError`, the gate **throws** so a React error boundary can handle it; `fallback` is not used for errors.
+
+## Day-to-day loop
+
+**configure → codegen (core then React) → `load` on the server → `serialize` → `I18nRoot` → gate where you need more namespaces.**
+
+## Low-level exports
+
+Apps normally use generated bindings. Advanced / library wiring can import from `@xndrjs/i18n-react` directly:
+
+- `I18nRootProvider` / `useI18nRootContext`
+- `createI18nLoadGate` / `useNamespaceLoad`
+- `createLoadCoordinator`
+- `createScopedT` / `bindNamespaceTranslate`
+
+## Docs
+
+Full guide: [xndrjs i18n — React](https://xndrjs.dev/v0/infrastructure/i18n/react/) (or the docs app in this monorepo).

package/dist/cli/codegen.js

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+import fs2 from 'fs';
+import path2 from 'path';
+import { loadConfig, resolveCodegenPaths } from '@xndrjs/i18n/codegen';
+import { z } from 'zod';
+
+var GENERATED_FILE_BANNER = "// Automatically generated code. Do not edit manually.\n";
+function importExtensionSuffix(importExtension) {
+  return importExtension === "none" ? "" : importExtension;
+}
+function toModuleBasename(filePath) {
+  return path2.basename(filePath).replace(/\.tsx?$/, "");
+}
+function toRelativeModuleImport(moduleBasename, importExtension) {
+  return `./${moduleBasename}${importExtensionSuffix(importExtension)}`;
+}
+function formatMultiScopedTType(schemaTypeName, paramsTypeName, localeTypeName) {
+  const emptyBranch = `(namespace: never, key: never, ...args: never[]) => string`;
+  return `type ScopedT<Ns extends readonly AppNamespace[]> = Ns extends readonly []
+  ? ${emptyBranch}
+  : I18nScopeMultiForLocale<
+  SchemaForNamespaces<${schemaTypeName}, Ns>,
+  ParamsForNamespaces<${schemaTypeName}, ${paramsTypeName}, Ns>,
+  ${localeTypeName},
+  ${localeTypeName}
+>["t"];
+
+`;
+}
+function formatI18nRoot(options) {
+  const { factoryName, localeTypeName, loaderStrategy } = options;
+  if (loaderStrategy === "fetch") {
+    return `export function I18nRoot({
+  locale,
+  children,
+  state,
+  dictionary,
+  fetchImpl,
+}: {
+  locale: ${localeTypeName};
+  children: ReactNode;
+  state?: I18nCreateInput | undefined;
+  dictionary?: Record<string, unknown> | undefined;
+  fetchImpl: FetchArtifact;
+}) {
+  return (
+    <I18nRootProvider
+      createI18n={${factoryName}}
+      locale={locale}
+      fetchImpl={fetchImpl}
+      {...(state !== undefined ? { state } : {})}
+      {...(dictionary !== undefined ? { dictionary } : {})}
+    >
+      {children}
+    </I18nRootProvider>
+  );
+}
+`;
+  }
+  return `export function I18nRoot({
+  locale,
+  children,
+  state,
+  dictionary,
+}: {
+  locale: ${localeTypeName};
+  children: ReactNode;
+  state?: I18nCreateInput | undefined;
+  dictionary?: Record<string, unknown> | undefined;
+}) {
+  return (
+    <I18nRootProvider
+      createI18n={${factoryName}}
+      locale={locale}
+      {...(state !== undefined ? { state } : {})}
+      {...(dictionary !== undefined ? { dictionary } : {})}
+    >
+      {children}
+    </I18nRootProvider>
+  );
+}
+`;
+}
+function formatReactBindingsFile(options) {
+  const {
+    factoryName,
+    localeTypeName,
+    instanceImport,
+    paramsTypeName,
+    schemaTypeName,
+    typesImport,
+    loaderStrategy = "import"
+  } = options;
+  const createInputImport = loaderStrategy === "fetch" ? `import type { FetchArtifact, I18nCreateInput } from "@xndrjs/i18n";
+` : `import type { I18nCreateInput } from "@xndrjs/i18n";
+`;
+  return `${GENERATED_FILE_BANNER}"use client";
+
+import {
+  type ForwardedRef,
+  type ForwardRefExoticComponent,
+  type ReactNode,
+  type RefAttributes,
+} from "react";
+import {
+  createI18nLoadGate,
+  I18nRootProvider,
+  useI18nRootContext,
+} from "@xndrjs/i18n-react";
+` + createInputImport + `import type {
+  I18nScopeMultiForLocale,
+  ParamsForNamespaces,
+  SchemaForNamespaces,
+} from "@xndrjs/i18n";
+import { ${factoryName} } from "${instanceImport}";
+import type { ${paramsTypeName}, ${schemaTypeName}, ${localeTypeName} } from "${typesImport}";
+
+export function useI18nRoot(): ReturnType<typeof ${factoryName}> {
+  return useI18nRootContext().handle as ReturnType<typeof ${factoryName}>;
+}
+
+type AppNamespace = keyof ${schemaTypeName} & string;
+
+` + formatMultiScopedTType(schemaTypeName, paramsTypeName, localeTypeName) + `type I18nInjected<Ns extends readonly AppNamespace[]> = {
+  t: ScopedT<Ns>;
+  locale: ${localeTypeName};
+  pendingLocale?: ${localeTypeName};
+  error?: unknown;
+  retry?: () => void;
+};
+export type I18nProps<Ns extends readonly AppNamespace[]> = I18nInjected<Ns>;
+
+export type WithI18nFallback<P extends object> = ReactNode | ((props: P) => ReactNode);
+
+const gate = createI18nLoadGate({
+  useLoadArgs: () => {
+    const root = useI18nRootContext();
+    const { handle, coordinator, locale } = root;
+    return {
+      coordinator,
+      engineRef: handle,
+      partition: locale,
+      locale,
+      load: (namespaces: readonly string[]) =>
+        handle.load({
+          namespaces: namespaces as [AppNamespace, ...AppNamespace[]],
+          locale,
+        }),
+      tryResolveSync: (namespaces: readonly string[]) =>
+        handle.peek({
+          namespaces: namespaces as [AppNamespace, ...AppNamespace[]],
+          locale,
+        }),
+    };
+  },
+});
+
+export function withI18n<
+  P extends object = object,
+  R = never,
+  const Ns extends readonly AppNamespace[] = readonly AppNamespace[],
+>(
+  options: {
+    namespaces: Ns;
+    fallback?: WithI18nFallback<P>;
+    renderError?: (args: { error: unknown; retry: () => void; props: P }) => ReactNode;
+  },
+  render: (props: P, i18n: I18nProps<Ns>, ref?: ForwardedRef<R>) => ReactNode
+): ForwardRefExoticComponent<P & RefAttributes<R>> {
+  return gate.withI18n(options, render as never) as ForwardRefExoticComponent<
+    P & RefAttributes<R>
+  >;
+}
+
+export function I18n<
+  const Ns extends readonly AppNamespace[],
+>(props: {
+  namespaces: Ns;
+  fallback?: ReactNode;
+  renderError?: (args: { error: unknown; retry: () => void }) => ReactNode;
+  children: (value: I18nProps<Ns>) => ReactNode;
+}) {
+  return gate.I18n(props as never);
+}
+
+` + formatI18nRoot({ factoryName, localeTypeName, loaderStrategy });
+}
+var DEFAULT_REACT_BINDINGS_BASENAME = "react-bindings.generated.tsx";
+var reactCodegenConfigSchema = z.object({
+  output: z.string().min(1).optional()
+}).strict();
+function defaultReactBindingsOutput(instanceOutput) {
+  return path2.join(path2.dirname(instanceOutput), DEFAULT_REACT_BINDINGS_BASENAME);
+}
+function loadReactCodegenConfig(configPath) {
+  if (!fs2.existsSync(configPath)) {
+    return {};
+  }
+  let raw;
+  try {
+    raw = JSON.parse(fs2.readFileSync(configPath, "utf8"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `[i18n-react Codegen Error] Failed to parse react config JSON (${configPath}): ${message}`
+    );
+  }
+  const result = reactCodegenConfigSchema.safeParse(raw);
+  if (!result.success) {
+    const issueLines = result.error.issues.map((issue) => {
+      const issuePath = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+      return `  - ${issuePath}: ${issue.message}`;
+    });
+    throw new Error(
+      ["[i18n-react Codegen Error] Invalid i18n-react.codegen.json:", ...issueLines].join("\n")
+    );
+  }
+  return result.data;
+}
+function resolveReactBindingsOutputPath(options) {
+  if (options.cliOut !== void 0) {
+    return options.cliOut;
+  }
+  if (options.reactConfig?.output !== void 0) {
+    return options.reactConfig.output;
+  }
+  return defaultReactBindingsOutput(options.instanceOutput);
+}
+function defaultReactConfigPath(i18nConfigPath) {
+  const dir = path2.dirname(i18nConfigPath);
+  const base = path2.basename(i18nConfigPath, path2.extname(i18nConfigPath));
+  if (base === "i18n.codegen") {
+    return path2.join(dir, "i18n-react.codegen.json");
+  }
+  return path2.join(dir, `${base}.react.codegen.json`);
+}
+function writeFileIfChanged(absolutePath, content) {
+  if (fs2.existsSync(absolutePath)) {
+    const currentContent = fs2.readFileSync(absolutePath, "utf8");
+    if (currentContent === content) {
+      return false;
+    }
+  }
+  fs2.mkdirSync(path2.dirname(absolutePath), { recursive: true });
+  fs2.writeFileSync(absolutePath, content);
+  return true;
+}
+
+// src/codegen/generate-react-bindings.ts
+function readCliFlag(flag) {
+  const index = process.argv.indexOf(flag);
+  if (index < 0) {
+    return void 0;
+  }
+  const value = process.argv[index + 1];
+  if (value === void 0 || value.startsWith("-")) {
+    throw new Error(`[i18n-react Codegen Error] Missing value for ${flag}`);
+  }
+  return value;
+}
+function main() {
+  const configPath = path2.resolve(
+    process.cwd(),
+    readCliFlag("--config") ?? "i18n/i18n.codegen.json"
+  );
+  const projectRoot = path2.dirname(configPath);
+  if (!fs2.existsSync(configPath)) {
+    throw new Error(`[i18n-react Codegen Error] Config file not found: ${configPath}`);
+  }
+  const config = loadConfig(configPath);
+  const paths = resolveCodegenPaths(config);
+  const instanceImport = toRelativeModuleImport(toModuleBasename(paths.instanceOutput), "none");
+  const typesImport = toRelativeModuleImport(toModuleBasename(paths.typesOutput), "none");
+  const reactConfigPath = path2.resolve(
+    projectRoot,
+    readCliFlag("--react-config") ?? defaultReactConfigPath(configPath)
+  );
+  const reactConfig = loadReactCodegenConfig(reactConfigPath);
+  const cliOut = readCliFlag("--out");
+  const reactOutputRelative = resolveReactBindingsOutputPath({
+    instanceOutput: paths.instanceOutput,
+    ...cliOut ? { cliOut } : {},
+    reactConfig
+  });
+  const reactOutputPath = path2.resolve(projectRoot, reactOutputRelative);
+  const content = formatReactBindingsFile({
+    factoryName: paths.factoryName,
+    paramsTypeName: paths.paramsTypeName,
+    schemaTypeName: paths.schemaTypeName,
+    localeTypeName: paths.localeTypeName,
+    instanceImport,
+    typesImport,
+    loaderStrategy: config.loaderStrategy ?? "import"
+  });
+  const written = writeFileIfChanged(reactOutputPath, content);
+  const displayPath = path2.relative(projectRoot, reactOutputPath);
+  if (written) {
+    console.log(`[i18n-react Codegen] Wrote ${displayPath}`);
+  } else {
+    console.log(`[i18n-react Codegen] Unchanged ${displayPath}`);
+  }
+}
+main();
+//# sourceMappingURL=codegen.js.map
+//# sourceMappingURL=codegen.js.map

package/dist/cli/codegen.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/codegen/emit/react-bindings-file.ts","../../src/codegen/react-codegen-config.ts","../../src/codegen/write-file-if-changed.ts","../../src/codegen/generate-react-bindings.ts"],"names":["path","fs"],"mappings":"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","file":"codegen.js","sourcesContent":["import path from \"node:path\";\n\nexport const GENERATED_FILE_BANNER = \"// Automatically generated code. Do not edit manually.\\n\";\n\nexport type ImportExtension = \"none\" | \".ts\" | \".js\";\n\nexport function importExtensionSuffix(importExtension: ImportExtension): string {\n  return importExtension === \"none\" ? \"\" : importExtension;\n}\n\nexport function toModuleBasename(filePath: string): string {\n  return path.basename(filePath).replace(/\\.tsx?$/, \"\");\n}\n\nexport function toRelativeModuleImport(\n  moduleBasename: string,\n  importExtension: ImportExtension\n): string {\n  return `./${moduleBasename}${importExtensionSuffix(importExtension)}`;\n}\n\nexport interface ReactBindingsFileOptions {\n  factoryName: string;\n  paramsTypeName: string;\n  schemaTypeName: string;\n  localeTypeName: string;\n  instanceImport: string;\n  typesImport: string;\n  /** When `\"fetch\"`, {@link I18nRoot} requires `fetchImpl`. */\n  loaderStrategy?: \"import\" | \"fetch\";\n}\n\n/** When `Ns` is `[]`, reject every `t(...)` call so refactoring can clear namespaces and re-add only what is used. */\nfunction formatMultiScopedTType(\n  schemaTypeName: string,\n  paramsTypeName: string,\n  localeTypeName: string\n): string {\n  const emptyBranch = `(namespace: never, key: never, ...args: never[]) => string`;\n  return (\n    `type ScopedT<Ns extends readonly AppNamespace[]> = Ns extends readonly []\\n` +\n    `  ? ${emptyBranch}\\n` +\n    `  : I18nScopeMultiForLocale<\\n` +\n    `  SchemaForNamespaces<${schemaTypeName}, Ns>,\\n` +\n    `  ParamsForNamespaces<${schemaTypeName}, ${paramsTypeName}, Ns>,\\n` +\n    `  ${localeTypeName},\\n` +\n    `  ${localeTypeName}\\n` +\n    `>[\"t\"];\\n\\n`\n  );\n}\n\nfunction formatI18nRoot(options: {\n  factoryName: string;\n  localeTypeName: string;\n  loaderStrategy: \"import\" | \"fetch\";\n}): string {\n  const { factoryName, localeTypeName, loaderStrategy } = options;\n\n  if (loaderStrategy === \"fetch\") {\n    return (\n      `export function I18nRoot({\\n` +\n      `  locale,\\n` +\n      `  children,\\n` +\n      `  state,\\n` +\n      `  dictionary,\\n` +\n      `  fetchImpl,\\n` +\n      `}: {\\n` +\n      `  locale: ${localeTypeName};\\n` +\n      `  children: ReactNode;\\n` +\n      `  state?: I18nCreateInput | undefined;\\n` +\n      `  dictionary?: Record<string, unknown> | undefined;\\n` +\n      `  fetchImpl: FetchArtifact;\\n` +\n      `}) {\\n` +\n      `  return (\\n` +\n      `    <I18nRootProvider\\n` +\n      `      createI18n={${factoryName}}\\n` +\n      `      locale={locale}\\n` +\n      `      fetchImpl={fetchImpl}\\n` +\n      `      {...(state !== undefined ? { state } : {})}\\n` +\n      `      {...(dictionary !== undefined ? { dictionary } : {})}\\n` +\n      `    >\\n` +\n      `      {children}\\n` +\n      `    </I18nRootProvider>\\n` +\n      `  );\\n` +\n      `}\\n`\n    );\n  }\n\n  return (\n    `export function I18nRoot({\\n` +\n    `  locale,\\n` +\n    `  children,\\n` +\n    `  state,\\n` +\n    `  dictionary,\\n` +\n    `}: {\\n` +\n    `  locale: ${localeTypeName};\\n` +\n    `  children: ReactNode;\\n` +\n    `  state?: I18nCreateInput | undefined;\\n` +\n    `  dictionary?: Record<string, unknown> | undefined;\\n` +\n    `}) {\\n` +\n    `  return (\\n` +\n    `    <I18nRootProvider\\n` +\n    `      createI18n={${factoryName}}\\n` +\n    `      locale={locale}\\n` +\n    `      {...(state !== undefined ? { state } : {})}\\n` +\n    `      {...(dictionary !== undefined ? { dictionary } : {})}\\n` +\n    `    >\\n` +\n    `      {children}\\n` +\n    `    </I18nRootProvider>\\n` +\n    `  );\\n` +\n    `}\\n`\n  );\n}\n\n/**\n * Emits typed root + withI18n / I18n for split-by-locale or custom delivery.\n * Every namespace loads through the handle + namespaceLoaders.\n * Partition→area mapping for custom delivery is injected into the handle by core codegen.\n */\nexport function formatReactBindingsFile(options: ReactBindingsFileOptions): string {\n  const {\n    factoryName,\n    localeTypeName,\n    instanceImport,\n    paramsTypeName,\n    schemaTypeName,\n    typesImport,\n    loaderStrategy = \"import\",\n  } = options;\n\n  const createInputImport =\n    loaderStrategy === \"fetch\"\n      ? `import type { FetchArtifact, I18nCreateInput } from \"@xndrjs/i18n\";\\n`\n      : `import type { I18nCreateInput } from \"@xndrjs/i18n\";\\n`;\n\n  return (\n    `${GENERATED_FILE_BANNER}` +\n    `\"use client\";\\n\\n` +\n    `import {\\n` +\n    `  type ForwardedRef,\\n` +\n    `  type ForwardRefExoticComponent,\\n` +\n    `  type ReactNode,\\n` +\n    `  type RefAttributes,\\n` +\n    `} from \"react\";\\n` +\n    `import {\\n` +\n    `  createI18nLoadGate,\\n` +\n    `  I18nRootProvider,\\n` +\n    `  useI18nRootContext,\\n` +\n    `} from \"@xndrjs/i18n-react\";\\n` +\n    createInputImport +\n    `import type {\\n` +\n    `  I18nScopeMultiForLocale,\\n` +\n    `  ParamsForNamespaces,\\n` +\n    `  SchemaForNamespaces,\\n` +\n    `} from \"@xndrjs/i18n\";\\n` +\n    `import { ${factoryName} } from \"${instanceImport}\";\\n` +\n    `import type { ${paramsTypeName}, ${schemaTypeName}, ${localeTypeName} } from \"${typesImport}\";\\n` +\n    `\\n` +\n    `export function useI18nRoot(): ReturnType<typeof ${factoryName}> {\\n` +\n    `  return useI18nRootContext().handle as ReturnType<typeof ${factoryName}>;\\n` +\n    `}\\n\\n` +\n    `type AppNamespace = keyof ${schemaTypeName} & string;\\n\\n` +\n    formatMultiScopedTType(schemaTypeName, paramsTypeName, localeTypeName) +\n    `type I18nInjected<Ns extends readonly AppNamespace[]> = {\\n` +\n    `  t: ScopedT<Ns>;\\n` +\n    `  locale: ${localeTypeName};\\n` +\n    `  pendingLocale?: ${localeTypeName};\\n` +\n    `  error?: unknown;\\n` +\n    `  retry?: () => void;\\n` +\n    `};\\n` +\n    `export type I18nProps<Ns extends readonly AppNamespace[]> = I18nInjected<Ns>;\\n\\n` +\n    `export type WithI18nFallback<P extends object> = ReactNode | ((props: P) => ReactNode);\\n\\n` +\n    `const gate = createI18nLoadGate({\\n` +\n    `  useLoadArgs: () => {\\n` +\n    `    const root = useI18nRootContext();\\n` +\n    `    const { handle, coordinator, locale } = root;\\n` +\n    `    return {\\n` +\n    `      coordinator,\\n` +\n    `      engineRef: handle,\\n` +\n    `      partition: locale,\\n` +\n    `      locale,\\n` +\n    `      load: (namespaces: readonly string[]) =>\\n` +\n    `        handle.load({\\n` +\n    `          namespaces: namespaces as [AppNamespace, ...AppNamespace[]],\\n` +\n    `          locale,\\n` +\n    `        }),\\n` +\n    `      tryResolveSync: (namespaces: readonly string[]) =>\\n` +\n    `        handle.peek({\\n` +\n    `          namespaces: namespaces as [AppNamespace, ...AppNamespace[]],\\n` +\n    `          locale,\\n` +\n    `        }),\\n` +\n    `    };\\n` +\n    `  },\\n` +\n    `});\\n\\n` +\n    `export function withI18n<\\n` +\n    `  P extends object = object,\\n` +\n    `  R = never,\\n` +\n    `  const Ns extends readonly AppNamespace[] = readonly AppNamespace[],\\n` +\n    `>(\\n` +\n    `  options: {\\n` +\n    `    namespaces: Ns;\\n` +\n    `    fallback?: WithI18nFallback<P>;\\n` +\n    `    renderError?: (args: { error: unknown; retry: () => void; props: P }) => ReactNode;\\n` +\n    `  },\\n` +\n    `  render: (props: P, i18n: I18nProps<Ns>, ref?: ForwardedRef<R>) => ReactNode\\n` +\n    `): ForwardRefExoticComponent<P & RefAttributes<R>> {\\n` +\n    `  return gate.withI18n(options, render as never) as ForwardRefExoticComponent<\\n` +\n    `    P & RefAttributes<R>\\n` +\n    `  >;\\n` +\n    `}\\n\\n` +\n    `export function I18n<\\n` +\n    `  const Ns extends readonly AppNamespace[],\\n` +\n    `>(props: {\\n` +\n    `  namespaces: Ns;\\n` +\n    `  fallback?: ReactNode;\\n` +\n    `  renderError?: (args: { error: unknown; retry: () => void }) => ReactNode;\\n` +\n    `  children: (value: I18nProps<Ns>) => ReactNode;\\n` +\n    `}) {\\n` +\n    `  return gate.I18n(props as never);\\n` +\n    `}\\n\\n` +\n    formatI18nRoot({ factoryName, localeTypeName, loaderStrategy })\n  );\n}\n","import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { z } from \"zod\";\n\nexport const DEFAULT_REACT_BINDINGS_BASENAME = \"react-bindings.generated.tsx\";\n\nconst reactCodegenConfigSchema = z\n  .object({\n    output: z.string().min(1).optional(),\n  })\n  .strict();\n\nexport type ReactCodegenConfig = z.infer<typeof reactCodegenConfigSchema>;\n\nexport function defaultReactBindingsOutput(instanceOutput: string): string {\n  return path.join(path.dirname(instanceOutput), DEFAULT_REACT_BINDINGS_BASENAME);\n}\n\n/** Loads optional `i18n-react.codegen.json` when present. */\nexport function loadReactCodegenConfig(configPath: string): ReactCodegenConfig {\n  if (!fs.existsSync(configPath)) {\n    return {};\n  }\n\n  let raw: unknown;\n  try {\n    raw = JSON.parse(fs.readFileSync(configPath, \"utf8\"));\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    throw new Error(\n      `[i18n-react Codegen Error] Failed to parse react config JSON (${configPath}): ${message}`\n    );\n  }\n\n  const result = reactCodegenConfigSchema.safeParse(raw);\n  if (!result.success) {\n    const issueLines = result.error.issues.map((issue) => {\n      const issuePath = issue.path.length > 0 ? issue.path.join(\".\") : \"(root)\";\n      return `  - ${issuePath}: ${issue.message}`;\n    });\n    throw new Error(\n      [\"[i18n-react Codegen Error] Invalid i18n-react.codegen.json:\", ...issueLines].join(\"\\n\")\n    );\n  }\n\n  return result.data;\n}\n\nexport function resolveReactBindingsOutputPath(options: {\n  instanceOutput: string;\n  cliOut?: string;\n  reactConfig?: ReactCodegenConfig;\n}): string {\n  if (options.cliOut !== undefined) {\n    return options.cliOut;\n  }\n  if (options.reactConfig?.output !== undefined) {\n    return options.reactConfig.output;\n  }\n  return defaultReactBindingsOutput(options.instanceOutput);\n}\n\nexport function defaultReactConfigPath(i18nConfigPath: string): string {\n  const dir = path.dirname(i18nConfigPath);\n  const base = path.basename(i18nConfigPath, path.extname(i18nConfigPath));\n  if (base === \"i18n.codegen\") {\n    return path.join(dir, \"i18n-react.codegen.json\");\n  }\n  return path.join(dir, `${base}.react.codegen.json`);\n}\n","import fs from \"node:fs\";\nimport path from \"node:path\";\n\n/** Writes only when content changed — stable mtimes for watchers. */\nexport function writeFileIfChanged(absolutePath: string, content: string): boolean {\n  if (fs.existsSync(absolutePath)) {\n    const currentContent = fs.readFileSync(absolutePath, \"utf8\");\n    if (currentContent === content) {\n      return false;\n    }\n  }\n\n  fs.mkdirSync(path.dirname(absolutePath), { recursive: true });\n  fs.writeFileSync(absolutePath, content);\n  return true;\n}\n","import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { loadConfig } from \"@xndrjs/i18n/codegen\";\nimport type { CodegenConfig } from \"@xndrjs/i18n/codegen\";\nimport { resolveCodegenPaths } from \"@xndrjs/i18n/codegen\";\nimport {\n  formatReactBindingsFile,\n  toModuleBasename,\n  toRelativeModuleImport,\n} from \"./emit/react-bindings-file.js\";\nimport {\n  defaultReactConfigPath,\n  loadReactCodegenConfig,\n  resolveReactBindingsOutputPath,\n} from \"./react-codegen-config.js\";\nimport { writeFileIfChanged } from \"./write-file-if-changed.js\";\n\nfunction readCliFlag(flag: string): string | undefined {\n  const index = process.argv.indexOf(flag);\n  if (index < 0) {\n    return undefined;\n  }\n  const value = process.argv[index + 1];\n  if (value === undefined || value.startsWith(\"-\")) {\n    throw new Error(`[i18n-react Codegen Error] Missing value for ${flag}`);\n  }\n  return value;\n}\n\n/**\n * React bindings codegen CLI.\n *\n * Reads `i18n.codegen.json` from `@xndrjs/i18n` and optionally `i18n-react.codegen.json`.\n * Output path: `--out` > react config `output` > default next to instance under `output/`.\n */\nfunction main(): void {\n  const configPath = path.resolve(\n    process.cwd(),\n    readCliFlag(\"--config\") ?? \"i18n/i18n.codegen.json\"\n  );\n  const projectRoot = path.dirname(configPath);\n\n  if (!fs.existsSync(configPath)) {\n    throw new Error(`[i18n-react Codegen Error] Config file not found: ${configPath}`);\n  }\n\n  const config: CodegenConfig = loadConfig(configPath);\n  const paths = resolveCodegenPaths(config);\n\n  const instanceImport = toRelativeModuleImport(toModuleBasename(paths.instanceOutput), \"none\");\n  const typesImport = toRelativeModuleImport(toModuleBasename(paths.typesOutput), \"none\");\n\n  const reactConfigPath = path.resolve(\n    projectRoot,\n    readCliFlag(\"--react-config\") ?? defaultReactConfigPath(configPath)\n  );\n  const reactConfig = loadReactCodegenConfig(reactConfigPath);\n  const cliOut = readCliFlag(\"--out\");\n  const reactOutputRelative = resolveReactBindingsOutputPath({\n    instanceOutput: paths.instanceOutput,\n    ...(cliOut ? { cliOut } : {}),\n    reactConfig,\n  });\n  const reactOutputPath = path.resolve(projectRoot, reactOutputRelative);\n\n  const content = formatReactBindingsFile({\n    factoryName: paths.factoryName,\n    paramsTypeName: paths.paramsTypeName,\n    schemaTypeName: paths.schemaTypeName,\n    localeTypeName: paths.localeTypeName,\n    instanceImport,\n    typesImport,\n    loaderStrategy: config.loaderStrategy ?? \"import\",\n  });\n\n  const written = writeFileIfChanged(reactOutputPath, content);\n  const displayPath = path.relative(projectRoot, reactOutputPath);\n\n  if (written) {\n    console.log(`[i18n-react Codegen] Wrote ${displayPath}`);\n  } else {\n    console.log(`[i18n-react Codegen] Unchanged ${displayPath}`);\n  }\n}\n\nmain();\n"]}

package/dist/index.d.ts

@@ -71,8 +71,13 @@ interface LoadCoordinator<Scope> {
     readonly revision: number;
     /** @deprecated Prefer {@link ensure}. */
     request(input: LoadCoordinatorRequest<Scope>): void;
-    /** Idempotent: start load if missing. Safe from getSnapshot. */
+    /** Idempotent: start load if missing. Safe from client getSnapshot. */
     ensure(input: LoadCoordinatorRequest<Scope>): void;
+    /**
+     * Idempotent: resolve from {@link LoadCoordinatorRequest.tryResolveSync} only.
+     * Never starts `load()` — use from SSR `getServerSnapshot`.
+     */
+    ensureSync(input: LoadCoordinatorRequest<Scope>): void;
     getEntry(key: LoadCoordinatorKey): LoadCoordinatorEntry<Scope>;
     getDisplayEntry(key: LoadCoordinatorKey, options: GetDisplayEntryOptions): LoadDisplayEntry<Scope>;
     /** Evict entry so the next ensure() re-fetches. */
@@ -108,6 +113,14 @@ interface I18nHandleLike {
         dictionary: unknown;
         resources: readonly (readonly [string, string])[];
     };
+    getLoadState: () => {
+        resources: readonly {
+            namespace: string;
+            partition: string;
+            status: "pending" | "loaded" | "error";
+            error?: unknown;
+        }[];
+    };
 }
 /** Single React context value for the lazy i18n tree. */
 interface I18nRootContextValue {
@@ -141,7 +154,7 @@ declare function createLoadCoordinator<Scope = ScopedScopeLike>(): LoadCoordinat
 
 /**
  * Manual (non-Suspense) i18n load gate: ensure + subscribe via the load
- * coordinator, then render fallback / keep-previous / error UI.
+ * coordinator, then render fallback / keep-previous / error UI / throw.
  */
 
 /** Inputs for {@link useNamespaceLoad}. */
@@ -157,7 +170,8 @@ interface UseNamespaceLoadInput<Scope> {
 }
 /**
  * Starts (or reuses) a coordinator load and re-renders when that entry settles.
- * Kick-off is idempotent inside the snapshot getter (safe with useSyncExternalStore).
+ * Client getSnapshot may kick `load()`; SSR getServerSnapshot only peeks sync
+ * (hydrated `state`) and never starts a client fetch during prerender.
  */
 declare function useNamespaceLoad<Scope>(input: UseNamespaceLoadInput<Scope>): LoadDisplayEntry<Scope>;
 /** Scoped `{ t, locale }` injected into gate children / HOC when ready (or kept). */
@@ -189,8 +203,12 @@ interface CreateI18nLoadGateOptions {
 }
 interface I18nGateProps {
     namespaces: readonly string[];
+    /** Shown only while the load is pending (not on error). */
     fallback?: ReactNode;
-    /** When set, called for error with no keep-previous display. */
+    /**
+     * When set, called for error with no keep-previous display.
+     * Otherwise the load error is thrown for a React error boundary.
+     */
     renderError?: (args: {
         error: unknown;
         retry: () => void;

package/dist/index.js

@@ -69,6 +69,34 @@ function createLoadCoordinator() {
     }
     notify();
   }
+  function markResolvedSync(key, syncScope) {
+    const entrySnapshot = {
+      status: "resolved",
+      scope: syncScope
+    };
+    entries.set(key, {
+      status: "resolved",
+      promise: Promise.resolve(syncScope),
+      resolvedScope: syncScope,
+      error: null,
+      requestId: ++nextRequestId,
+      entrySnapshot
+    });
+  }
+  function ensureSync(input) {
+    const key = cacheKey(input.engineRef, input.partition, input.namespaces);
+    lastKey = key;
+    if (entries.has(key)) {
+      return;
+    }
+    if (input.tryResolveSync === void 0) {
+      return;
+    }
+    const syncScope = input.tryResolveSync();
+    if (syncScope !== null) {
+      markResolvedSync(key, syncScope);
+    }
+  }
   function ensure(input) {
     const key = cacheKey(input.engineRef, input.partition, input.namespaces);
     lastKey = key;
@@ -79,18 +107,7 @@ function createLoadCoordinator() {
     if (input.tryResolveSync !== void 0) {
       const syncScope = input.tryResolveSync();
       if (syncScope !== null) {
-        const entrySnapshot = {
-          status: "resolved",
-          scope: syncScope
-        };
-        entries.set(key, {
-          status: "resolved",
-          promise: Promise.resolve(syncScope),
-          resolvedScope: syncScope,
-          error: null,
-          requestId: ++nextRequestId,
-          entrySnapshot
-        });
+        markResolvedSync(key, syncScope);
         return;
       }
     }
@@ -120,7 +137,9 @@ function createLoadCoordinator() {
         throw error;
       }
     );
-    void promise.catch(() => void 0);
+    void promise.catch((error) => {
+      console.error("[i18n-react] namespace load failed:", error);
+    });
     entries.set(key, {
       status: "pending",
       promise,
@@ -245,6 +264,7 @@ function createLoadCoordinator() {
     },
     request: ensure,
     ensure,
+    ensureSync,
     getEntry,
     getDisplayEntry,
     retry: retryKey,
@@ -271,29 +291,20 @@ function useNamespaceLoad(input) {
     load,
     ...tryResolveSync !== void 0 ? { tryResolveSync } : {}
   };
+  const displayOptions = {
+    locale,
+    namespaces,
+    ...keepPrevious !== void 0 ? { keepPrevious } : {}
+  };
   return useSyncExternalStore(
     coordinator.subscribe,
     () => {
       coordinator.ensure(request);
-      return coordinator.getDisplayEntry(
-        { engineRef, partition, namespaces },
-        {
-          locale,
-          namespaces,
-          ...keepPrevious !== void 0 ? { keepPrevious } : {}
-        }
-      );
+      return coordinator.getDisplayEntry({ engineRef, partition, namespaces }, displayOptions);
     },
     () => {
-      coordinator.ensure(request);
-      return coordinator.getDisplayEntry(
-        { engineRef, partition, namespaces },
-        {
-          locale,
-          namespaces,
-          ...keepPrevious !== void 0 ? { keepPrevious } : {}
-        }
-      );
+      coordinator.ensureSync(request);
+      return coordinator.getDisplayEntry({ engineRef, partition, namespaces }, displayOptions);
     }
   );
 }
@@ -303,6 +314,15 @@ function resolveNamespaces(namespaces) {
   }
   return namespaces;
 }
+function toThrownError(error) {
+  if (error instanceof Error) {
+    return error;
+  }
+  if (typeof error === "string") {
+    return new Error(error);
+  }
+  return new Error("i18n namespace load failed");
+}
 function renderDisplayEntry(entry, options) {
   if (entry.status === "ready") {
     return options.children({ t: entry.t, locale: entry.locale });
@@ -311,7 +331,7 @@ function renderDisplayEntry(entry, options) {
     if (options.renderError) {
       return options.renderError({ error: entry.error, retry: entry.retry });
     }
-    return options.fallback ?? null;
+    throw toThrownError(entry.error);
   }
   if (entry.t !== null && entry.display) {
     const value = {
@@ -358,7 +378,7 @@ function createI18nLoadGate(options) {
     const { fallback, renderError } = hocOptions;
     const Outer = forwardRef(function I18nHocOuter(props, ref) {
       const entry = useGateEntry(hocOptions.namespaces);
-      const needsFallback = entry.status !== "ready" && entry.t === null;
+      const needsFallback = entry.status === "pending" && entry.t === null;
       const resolvedFallback = !needsFallback || fallback === void 0 ? void 0 : typeof fallback === "function" ? fallback(props) : fallback;
       return renderDisplayEntry(entry, {
         ...resolvedFallback !== void 0 ? { fallback: resolvedFallback } : {},