@xndrjs/i18n 0.3.3 → 0.5.0-alpha.0

package/README.md

@@ -10,7 +10,7 @@ The core idea: your ICU strings live in local JSON files that act as **type-safe
 - **ICU MessageFormat** — full support for interpolation, plurals, and select.
 - **Runtime override** — hydrate translations from an external source via `setAll()` / `setNamespace()` without rebuilding.
 - **Single-file or multi-namespace** — one flat dictionary, or multiple JSON files each bound to a namespace.
-- **Lazy namespace loading** — optional code-splitting via `loadOnInit` and `ensureNamespacesLoaded()` (multi mode).
+- **Lazy namespace loading** — optional code-splitting via `loadOnInit` and generated `namespaceLoaders` (multi mode).
 - **Hot compilation cache** — compiled `IntlMessageFormat` instances are cached and invalidated on override.
 - **Explicit runtime errors** — malformed ICU (e.g. a corrupt remote payload) or missing parameters throw descriptive errors.
 - **Translation audit** — `xndrjs-i18n-audit` reports missing locales per key (direct vs effective after fallback); optional CI gate via `--fail-on`.
@@ -75,11 +75,13 @@ npm run i18n:audit
 ```ts
 // i18n/index.ts
 import { createI18n } from "./generated/instance.generated.js";
+import { defaultDictionary } from "./generated/dictionary.generated.js";
 
 export * from "./generated/instance.generated.js";
+export * from "./generated/dictionary.generated.js";
 export * from "./generated/i18n-types.generated.js";
 
-export const i18n = createI18n();
+export const i18n = createI18n(defaultDictionary);
 ```
 
 ```ts
@@ -104,7 +106,7 @@ This creates `i18n/i18n.codegen.json`, starter translation JSON, and `i18n/index
 
 Use `namespaces` instead of `dictionary` in `i18n/i18n.codegen.json`. See [Configuration](#configuration-i18ncodegenjson) and the [multi-namespace example](#multi-namespace-example) below.
 
-For lazy loading, add `loadOnInit`, `dictionarySchemaOutput`, and `namespaceLoadersOutput` — see [Lazy namespace loading](#lazy-namespace-loading-multi-mode). Lazy mode requires `zod` (validation runs before a namespace is registered).
+For lazy loading, add `loadOnInit` and `namespaceLoadersOutput` — see [Lazy namespace loading](#lazy-namespace-loading-multi-mode). Add `dictionarySchemaOutput` only when you validate external CMS/API payloads.
 
 ## Repository layout
 
@@ -194,8 +196,8 @@ Variables found across **all locales** of the same key are merged. If parsing fa
 ### 3. Generated files
 
 - **`i18n-types.generated.ts`** — `I18N_MODE`, `MyProjectParams`, `MyProjectSchema`.
-- **`dictionary.generated.ts`** — imports the JSON files and assembles the initial dictionary.
-- **`instance.generated.ts`** — exports `createI18n()`, typed `projectLocales()` (full schema), and in multi mode `projectNamespaceLocales()` (single namespace); `LOCALE_FALLBACK` wired in when configured.
+- **`dictionary.generated.ts`** — imports the JSON files and exports `defaultDictionary` (canonical delivery) or `defaultDictionaryFor(locale)` (split-by-locale delivery).
+- **`instance.generated.ts`** — exports `createI18n(dictionary)` (required argument; no default import of the fallback dictionary), typed `projectDictionaryLocales()` (full schema), and in multi mode `projectNamespaceLocales()` (single namespace); with `delivery: "custom"`, also `projectDictionaryForDeliveryArea()` and `projectNamespaceForDeliveryArea()`; `LOCALE_FALLBACK` wired in when configured.
 - **`i18n.ts`** (optional, hand-written) — app-owned singleton if desired.
 
 Example generated types (multi-namespace):
@@ -219,20 +221,30 @@ export type MyProjectParams = {
 };
 
 export type MyProjectSchema = {
-  default: typeof import("./translations/default.json");
-  user: typeof import("./translations/user.json");
-  billing: typeof import("./translations/billing.json");
+  default: {
+    login_button: Partial<Record<MyProjectLocale, string>>;
+    welcome: Partial<Record<MyProjectLocale, string>>;
+    dashboard_status: Partial<Record<MyProjectLocale, string>>;
+  };
+  user: {
+    profile_title: Partial<Record<MyProjectLocale, string>>;
+    greeting: Partial<Record<MyProjectLocale, string>>;
+  };
+  billing: {
+    invoice_summary: Partial<Record<MyProjectLocale, string>>;
+  };
 };
 ```
 
 ### 4. Runtime provider
 
-Create a provider with the generated factory (no side effects at import time):
+Create a provider with the generated factory (no side effects at import time). Pass the dictionary explicitly — from codegen’s `dictionary.generated.ts`, from lazy loaders, or from an external source — so the factory module does not pull fallback JSON into your bundle:
 
 ```ts
 import { createI18n } from "./i18n";
+import { defaultDictionary } from "./i18n/generated/dictionary.generated.js";
 
-const i18n = createI18n();
+const i18n = createI18n(defaultDictionary);
 // or with an external dictionary at init:
 const i18n = createI18n(externalDictionary);
 ```
@@ -241,7 +253,8 @@ Optionally, wrap it in an app-owned singleton (`i18n.ts`):
 
 ```ts
 import { createI18n } from "./instance.generated.js";
-export const i18n = createI18n();
+import { defaultDictionary } from "./dictionary.generated.js";
+export const i18n = createI18n(defaultDictionary);
 ```
 
 ### Locale-bound provider (`forLocale`)
@@ -249,7 +262,7 @@ export const i18n = createI18n();
 Bind a locale once and omit it on every `.get()`:
 
 ```ts
-const i18n = createI18n();
+const i18n = createI18n(defaultDictionary);
 const i18nEn = i18n.forLocale("en");
 
 i18nEn.get("login_button"); // single-file
@@ -302,24 +315,25 @@ const localeFallback = {
 const i18n = new IcuTranslationProviderMulti(schema, { localeFallback });
 ```
 
-#### `projectLocales` / `projectNamespaceLocales`
+#### `projectDictionaryLocales` / `projectNamespaceLocales`
 
 Namespaces split the dictionary by domain; locale projection splits it by **locale**. Use before `setAll()` / `setNamespace()` when you only need one locale (or a small regional group) in memory.
 
 ```ts
 import {
   createI18n,
-  projectLocales,
+  projectDictionaryLocales,
   projectNamespaceLocales,
 } from "./i18n/generated/instance.generated.js";
+import { defaultDictionary } from "./i18n/generated/dictionary.generated.js";
 import billingDictionary from "./i18n/translations/billing.json";
 
-const i18n = createI18n();
+const i18n = createI18n(defaultDictionary);
 i18n.setNamespace("billing", projectNamespaceLocales(billingDictionary, [activeLocale]));
-i18n.setAll(projectLocales(fullDictionary, [activeLocale])); // multi: all namespaces
+i18n.setAll(projectDictionaryLocales(fullDictionary, [activeLocale])); // multi: all namespaces
 ```
 
-Codegen emits typed wrappers in `instance.generated.ts` (`projectLocales` for the full schema; `projectNamespaceLocales` in multi mode for one namespace). The low-level `@xndrjs/i18n` exports remain for tooling without codegen.
+Codegen emits typed wrappers in `instance.generated.ts` (`projectDictionaryLocales` for the full schema; `projectNamespaceLocales` in multi mode for one namespace). With `delivery: "custom"`, it also emits `projectDictionaryForDeliveryArea` and `projectNamespaceForDeliveryArea`. The low-level `@xndrjs/i18n` exports are `*Core` helpers for tooling without codegen.
 
 ### 6. Translation audit (`xndrjs-i18n-audit`)
 
@@ -393,29 +407,31 @@ Specify **exactly one** of `dictionary` (single-file) or `namespaces` (multi-fil
 }
 ```
 
-| Field                               | Description                                                                                                                                                                         |
-| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
-| `dictionary`                        | Path to a single dictionary file (`.json`, `.yaml`, or `.yml`) for the flat API. Mutually exclusive with `namespaces`.                                                              |
-| `namespaces`                        | Map of `namespace -> dictionary path` (`.json`, `.yaml`, or `.yml`) for the namespaced API. Mutually exclusive with `dictionary`.                                                   |
-| `defaultNamespace`                  | Optional. Namespace label used internally in single-file mode (default `"default"`). Not exposed in the flat API.                                                                   |
-| `typesOutput`                       | Output path for the generated types.                                                                                                                                                |
-| `dictionaryOutput`                  | Output path for the generated dictionary manifest.                                                                                                                                  |
-| `instanceOutput`                    | Output path for the generated factory (`createI18n`).                                                                                                                               |
-| `importExtension`                   | Optional. Relative import suffix between generated `.ts` modules: `"none"` (default, extensionless), `".ts"`, or `".js"`.                                                           |
-| `factoryName`                       | Name of the exported factory function (default `createI18n`).                                                                                                                       |
-| `paramsTypeName` / `schemaTypeName` | Names of the exported types (customizable per project).                                                                                                                             |
-| `localeTypeName`                    | Name of the exported locale union type (default `MyProjectLocale`).                                                                                                                 |
-| `localeFallback`                    | Optional map of `locale -> next locale                                                                                                                                              | null` for runtime fallback resolution. |
-| `localeFallbackConstName`           | Name of the generated fallback constant (default `LOCALE_FALLBACK`).                                                                                                                |
-| `dictionarySchemaOutput`            | Optional path for generated external dictionary validation (`dictionary-schema.generated.ts`). Requires `zod` in the consumer app.                                                  |
-| `loadOnInit`                        | Multi mode only. Namespaces to include in the initial bundle via static imports. When omitted, all namespaces are eager (default).                                                  |
-| `namespaceLoadersOutput`            | Output path for generated lazy loaders and `ensureNamespacesLoaded()`. Defaults to `{dirname(instanceOutput)}/namespace-loaders.generated.ts`. Required when lazy namespaces exist. |
+| Field                               | Description                                                                                                                                                                                                                                                             |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| `dictionary`                        | Path to a single dictionary file (`.json`, `.yaml`, or `.yml`) for the flat API. Mutually exclusive with `namespaces`.                                                                                                                                                  |
+| `namespaces`                        | Map of `namespace -> dictionary path` (`.json`, `.yaml`, or `.yml`) for the namespaced API. Mutually exclusive with `dictionary`.                                                                                                                                       |
+| `defaultNamespace`                  | Optional. Namespace label used internally in single-file mode (default `"default"`). Not exposed in the flat API.                                                                                                                                                       |
+| `typesOutput`                       | Output path for the generated types.                                                                                                                                                                                                                                    |
+| `dictionaryOutput`                  | Output path for the generated dictionary manifest.                                                                                                                                                                                                                      |
+| `instanceOutput`                    | Output path for the generated factory (`createI18n`).                                                                                                                                                                                                                   |
+| `importExtension`                   | Optional. Relative import suffix between generated `.ts` modules: `"none"` (default, extensionless), `".ts"`, or `".js"`.                                                                                                                                               |
+| `factoryName`                       | Name of the exported factory function (default `createI18n`).                                                                                                                                                                                                           |
+| `paramsTypeName` / `schemaTypeName` | Names of the exported types (customizable per project).                                                                                                                                                                                                                 |
+| `localeTypeName`                    | Name of the exported locale union type (default `MyProjectLocale`).                                                                                                                                                                                                     |
+| `localeFallback`                    | Optional map of `locale -> next locale                                                                                                                                                                                                                                  | null` for runtime fallback resolution. |
+| `localeFallbackConstName`           | Name of the generated fallback constant (default `LOCALE_FALLBACK`).                                                                                                                                                                                                    |
+| `dictionarySchemaOutput`            | Optional path for generated external dictionary validation (`dictionary-schema.generated.ts`). Requires `zod` in the consumer app.                                                                                                                                      |
+| `loadOnInit`                        | Multi mode only. Namespaces to include in the initial bundle via static imports. When omitted, all namespaces are eager (default).                                                                                                                                      |
+| `namespaceLoadersOutput`            | Output path for generated `namespaceLoaders` (dynamic `import()` per lazy namespace). Defaults to `{dirname(instanceOutput)}/namespace-loaders.generated.ts`. Required when lazy namespaces exist.                                                                      |
+| `delivery`                          | Optional. `"canonical"` (default) — one multilocale JSON per namespace. `"split-by-locale"` — emits `{basename}.{locale}.json` under `{deliveryOutput}/translations/` and per-locale loaders. See [Split-by-locale delivery](#split-by-locale-delivery).                |
+| `deliveryOutput`                    | Optional. Directory for compiled and split delivery JSON (files land in `{deliveryOutput}/translations/`). Defaults to `dirname(typesOutput)`. Use e.g. `public/i18n` to ship per-locale JSON from a static host while keeping generated TypeScript under `generated/`. |
 
 > Paths are resolved relative to the directory containing `i18n.codegen.json` (e.g. `i18n/` when using `xndrjs-i18n-setup .`).
 
 ### YAML authoring
 
-Dictionary paths may use `.yaml` or `.yml` instead of `.json`. **YAML is an authoring format, not a runtime format** — codegen compiles YAML to JSON under the generated output directory (for example `translations/billing.yaml` → `{dirname(typesOutput)}/translations/billing.json`); generated TypeScript imports the compiled JSON at runtime. Edit only the YAML source — the compiled JSON is overwritten on each codegen run.
+Dictionary paths may use `.yaml` or `.yml` instead of `.json`. **YAML is an authoring format, not a runtime format** — codegen compiles YAML to JSON under the delivery output directory (for example `translations/billing.yaml` → `{deliveryOutput}/translations/billing.json`; default `{deliveryOutput}` is `dirname(typesOutput)`); generated TypeScript imports the compiled JSON at runtime. Edit only the YAML source — the compiled JSON is overwritten on each codegen run.
 
 Use YAML when ICU is hard to read on one line: multiple parameters, or plural/select branches. It is not aimed at long legal copy or styled pages — those usually belong in a separate content template with localized fragments inside.
 
@@ -438,6 +454,82 @@ Workflow:
 
 Mixed namespaces are supported: some namespaces can stay `.json` while others use YAML.
 
+### Split-by-locale delivery
+
+By default (`delivery: "canonical"`), codegen keeps one multilocale JSON per namespace — either your source file in place (`.json`) or a compiled YAML → JSON under `{deliveryOutput}/translations/` (default: `generated/translations/`).
+
+Set `"delivery": "split-by-locale"` to emit **one JSON file per locale** instead:
+
+```json
+{
+  "delivery": "split-by-locale",
+  "namespaces": {
+    "default": "translations/default.json",
+    "billing": "translations/billing.yaml"
+  },
+  "loadOnInit": ["default"]
+}
+```
+
+Codegen writes `{deliveryOutput}/translations/{basename}.{locale}.json` (for example `user.it.json`, `billing.en.json`). Each file contains the same shape as `projectNamespaceLocalesCore(dict, [locale])` — keys map to a single locale entry. With `localeFallback`, locales such as `de-CH` are resolved at codegen time (for example from `de-DE`).
+
+**Authoring is unchanged** — edit the canonical source JSON/YAML. Types (`MyProjectSchema`) are generated explicitly from ICU analysis (keys + `Partial<Record<MyProjectLocale, string>>` per key), not from `typeof import` of JSON files. Audit still reads the config paths.
+
+**Generated API changes (opt-in):**
+
+| Canonical                        | Split-by-locale                                |
+| -------------------------------- | ---------------------------------------------- |
+| `export const defaultDictionary` | `export function defaultDictionaryFor(locale)` |
+| `namespaceLoaders.billing()`     | `namespaceLoaders.billing(locale)`             |
+
+Example `dictionary.generated.ts` (multi, `loadOnInit: ["default"]`):
+
+```ts
+import defaultEn from "./translations/default.en.json";
+import defaultIt from "./translations/default.it.json";
+
+const defaultByLocale = {
+  en: defaultEn,
+  it: defaultIt,
+} as const satisfies Record<MyProjectLocale, MyProjectSchema["default"]>;
+
+export function defaultDictionaryFor(locale: MyProjectLocale): InitialSchema {
+  return { default: defaultByLocale[locale] };
+}
+```
+
+Example `namespace-loaders.generated.ts`:
+
+```ts
+export const namespaceLoaders = {
+  billing: (locale: MyProjectLocale) => {
+    switch (locale) {
+      case "en":
+        return import("./translations/billing.en.json").then((m) => m.default);
+      case "it":
+        return import("./translations/billing.it.json").then((m) => m.default);
+      case "de-CH":
+        return import("./translations/billing.de-CH.json").then((m) => m.default);
+    }
+  },
+};
+```
+
+Init with the active locale:
+
+```ts
+import { createI18n } from "./generated/instance.generated.js";
+import { defaultDictionaryFor } from "./generated/dictionary.generated.js";
+
+const i18n = createI18n(defaultDictionaryFor(activeLocale));
+
+if (!i18n.hasNamespace("billing")) {
+  i18n.setNamespace("billing", await namespaceLoaders.billing(activeLocale));
+}
+```
+
+Use split delivery when you want smaller lazy chunks (one locale per dynamic import) or when serving per-locale JSON from `public/` without runtime `projectNamespaceLocales`. Runtime `projectDictionaryLocales` / `projectNamespaceLocales` remain available for external CMS/API payloads.
+
 ## Usage
 
 ### Single vs. multi-namespace API
@@ -453,7 +545,7 @@ Mixed namespaces are supported: some namespaces can stay `.json` while others us
 
 ```ts
 import { i18n } from "./i18n"; // app singleton from i18n.ts
-// or: import { createI18n } from './i18n'; const i18n = createI18n();
+// or: import { createI18n, defaultDictionary } from './i18n'; const i18n = createI18n(defaultDictionary);
 
 i18n.get("default", "login_button", "it"); // "Accedi"
 i18n.get("default", "welcome", "en", { name: "Ada" }); // "Welcome Ada!"
@@ -469,7 +561,7 @@ i18n.get("billing", "login_button", "it"); // ✗ key not in namespace
 
 ```ts
 import { i18n } from "./i18n"; // app singleton from i18n.ts
-// or: import { createI18n } from './i18n'; const i18n = createI18n();
+// or: import { createI18n, defaultDictionary } from './i18n'; const i18n = createI18n(defaultDictionary);
 
 i18n.get("login_button", "it");
 i18n.get("welcome", "en", { name: "Ada" });
@@ -487,7 +579,7 @@ i18n.setNamespace("billing", externalBillingPayload);
 
 ### Lazy namespace loading (multi mode)
 
-Split namespaces across chunks by listing only the namespaces you need at startup in `loadOnInit`. Codegen emits dynamic `import()` loaders and a generated `ensureNamespacesLoaded(i18n, namespaces)` helper. `.get()` stays synchronous — preload lazy namespaces before rendering.
+Split namespaces across chunks by listing only the namespaces you need at startup in `loadOnInit`. Codegen emits typed `namespaceLoaders` — one dynamic `import()` per lazy namespace (or per lazy namespace **and locale** when `delivery: "split-by-locale"`). `.get()` stays synchronous — register lazy namespaces with `setNamespace()` before rendering.
 
 ```json
 {
@@ -496,7 +588,6 @@ Split namespaces across chunks by listing only the namespaces you need at startu
     "billing": "translations/billing.yaml"
   },
   "loadOnInit": ["default"],
-  "dictionarySchemaOutput": "generated/dictionary-schema.generated.ts",
   "namespaceLoadersOutput": "generated/namespace-loaders.generated.ts"
 }
 ```
@@ -504,23 +595,51 @@ Split namespaces across chunks by listing only the namespaces you need at startu
 Codegen also emits `LoadOnInitNamespace`, `LazyNamespace`, and `InitialSchema` types. The generated factory accepts a partial `InitialSchema` at init time.
 
 ```ts
-import { i18n, ensureNamespacesLoaded } from "./i18n";
+import { i18n, namespaceLoaders, type LazyNamespace } from "./i18n";
 
 i18n.get("default", "login_button", "en"); // available immediately
 
-await ensureNamespacesLoaded(i18n, ["billing"]);
+if (!i18n.hasNamespace("billing")) {
+  i18n.setNamespace("billing", await namespaceLoaders.billing());
+}
 i18n.get("billing", "invoice_summary", "en", { count: 12 });
 
 // batch preload
-await ensureNamespacesLoaded(i18n, ["user", "billing"]);
+await Promise.all(
+  (["user", "billing"] as const satisfies readonly LazyNamespace[]).map(async (namespace) => {
+    if (i18n.hasNamespace(namespace)) return;
+    i18n.setNamespace(namespace, await namespaceLoaders[namespace]());
+  })
+);
+```
+
+With `delivery: "split-by-locale"`, pick the locale on each loader:
+
+```ts
+const locale = "it" as const;
+
+if (!i18n.hasNamespace("billing")) {
+  i18n.setNamespace("billing", await namespaceLoaders.billing(locale));
+}
+```
+
+Optional locale projection before register:
+
+```ts
+import { projectNamespaceLocales } from "./i18n/generated/instance.generated.js";
+
+const billing = await namespaceLoaders.billing();
+i18n.setNamespace("billing", projectNamespaceLocales(billing, [userLocale]));
 ```
 
 Calling `.get()` on a namespace that is not loaded throws:
 
-`[i18n] Namespace not loaded: "billing". Call ensureNamespacesLoaded(i18n, ["billing"]) first.`
+`[i18n] Namespace not loaded: "billing". Register it with setNamespace() before calling .get().`
 
 When `loadOnInit` is omitted, behavior is unchanged: all namespaces are statically imported.
 
+Fetch/CMS hydration is app-owned: fetch → `validateExternalNamespace()` (requires `dictionarySchemaOutput` + `zod`) → `setNamespace()`.
+
 ### External dictionary validation
 
 When translations arrive from an external source (i.e. a CMS), validate the `unknown` input before calling `setAll()` or `setNamespace()`.
@@ -578,10 +697,40 @@ Both providers share this behavior:
 - **`hasNamespace(ns)`** — (multi only) returns whether a namespace has been loaded (eager init, lazy load, or `setNamespace`).
 - **`setAll(values)`** — replaces the dictionary and clears the entire cache.
 - **`setNamespace(ns, values)`** — (multi only) replaces one namespace and invalidates only its cache entries.
-- **Missing key/locale** — throws an error if the template is `undefined`. An empty string (`""`) is treated as a valid template.
+- **Missing key/locale** — by default throws an error if the template is `undefined` (configurable via `onMissing`, see below). An empty string (`""`) is treated as a valid template.
 - **ICU syntax error** — throws `[i18n ICU Syntax Error] ...`.
 - **Formatting error** (missing/invalid params) — throws `[i18n Formatting Error] ...`.
 
+### Missing-translation strategy (`onMissing`)
+
+Both providers accept an `onMissing` option controlling what happens when no template resolves for a key/locale (after walking the full fallback chain):
+
+```ts
+onMissing?: "throw" | "key" | ((context: MissingTranslationContext) => string);
+// MissingTranslationContext = { namespace?: string; key: string; locale: string; fallbackChain: string }
+```
+
+- **`"throw"`** (default) — throws `[i18n] Missing key or locale: ...` including the fallback chain.
+- **`"key"`** — returns the key itself: `key` in single mode, `namespace.key` in multi mode.
+- **Function** — receives the missing-translation context (`namespace` is only set in multi mode) and returns the string to display.
+
+```ts
+const i18n = new IcuTranslationProviderMulti(schema, {
+  localeFallback,
+  onMissing: ({ namespace, key }) => `[missing: ${namespace}.${key}]`,
+});
+```
+
+`onMissing` only applies to missing-template resolution. ICU syntax errors, formatting errors, and (in multi mode) unloaded namespaces still throw.
+
+The generated factory accepts `onMissing` as a pass-through option, merged with the codegen-wired `localeFallback`:
+
+```ts
+import { createI18n } from "./i18n/generated/instance.generated.js";
+
+const i18n = createI18n(dictionary, { onMissing: "key" });
+```
+
 ## Commands
 
 Run from the repo root:

package/dist/codegen/index.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+
+declare const DELIVERY_MODES: readonly ["canonical", "split-by-locale", "custom"];
+type DeliveryMode = (typeof DELIVERY_MODES)[number];
+declare const codegenConfigShape: {
+    dictionary: z.ZodOptional<z.ZodString>;
+    namespaces: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    defaultNamespace: z.ZodOptional<z.ZodString>;
+    typesOutput: z.ZodString;
+    dictionaryOutput: z.ZodString;
+    instanceOutput: z.ZodString;
+    dictionarySchemaOutput: z.ZodOptional<z.ZodString>;
+    loadOnInit: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    namespaceLoadersOutput: z.ZodOptional<z.ZodString>;
+    importExtension: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        ".ts": ".ts";
+        ".js": ".js";
+    }>>;
+    paramsTypeName: z.ZodString;
+    schemaTypeName: z.ZodString;
+    localeTypeName: z.ZodOptional<z.ZodString>;
+    localeFallbackConstName: z.ZodOptional<z.ZodString>;
+    localeFallback: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>>;
+    factoryName: z.ZodOptional<z.ZodString>;
+    delivery: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        custom: "custom";
+        canonical: "canonical";
+        "split-by-locale": "split-by-locale";
+    }>>>;
+    deliveryArtifacts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    deliveryOutput: z.ZodOptional<z.ZodString>;
+};
+declare const codegenConfigKeys: (keyof typeof codegenConfigShape)[];
+declare const codegenConfigSchema: z.ZodObject<{
+    dictionary: z.ZodOptional<z.ZodString>;
+    namespaces: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    defaultNamespace: z.ZodOptional<z.ZodString>;
+    typesOutput: z.ZodString;
+    dictionaryOutput: z.ZodString;
+    instanceOutput: z.ZodString;
+    dictionarySchemaOutput: z.ZodOptional<z.ZodString>;
+    loadOnInit: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    namespaceLoadersOutput: z.ZodOptional<z.ZodString>;
+    importExtension: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        ".ts": ".ts";
+        ".js": ".js";
+    }>>;
+    paramsTypeName: z.ZodString;
+    schemaTypeName: z.ZodString;
+    localeTypeName: z.ZodOptional<z.ZodString>;
+    localeFallbackConstName: z.ZodOptional<z.ZodString>;
+    localeFallback: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>>;
+    factoryName: z.ZodOptional<z.ZodString>;
+    delivery: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        custom: "custom";
+        canonical: "canonical";
+        "split-by-locale": "split-by-locale";
+    }>>>;
+    deliveryArtifacts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    deliveryOutput: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type CodegenConfigInput = z.input<typeof codegenConfigSchema>;
+type CodegenConfig = z.infer<typeof codegenConfigSchema>;
+declare function resolveDeliveryOutputDir(config: Pick<CodegenConfig, "typesOutput" | "deliveryOutput">): string;
+
+type DeliveryArtifactsMap = Record<string, readonly string[]>;
+
+declare const SUPPORTED_IMPORT_EXTENSIONS: readonly ["none", ".ts", ".js"];
+type SupportedImportExtension = (typeof SUPPORTED_IMPORT_EXTENSIONS)[number];
+
+type SetupMode = "single" | "multi";
+declare function buildCodegenConfig(mode: SetupMode, project: string): CodegenConfigInput;
+
+declare function inferProjectName(dirName: string): string;
+declare function typeNamesForProject(project: string): {
+    paramsTypeName: string;
+    schemaTypeName: string;
+    localeTypeName: string;
+};
+
+declare function writeCodegenConfig(configPath: string, config: CodegenConfigInput): void;
+
+export { type CodegenConfig, type CodegenConfigInput, DELIVERY_MODES, type DeliveryArtifactsMap, type DeliveryMode, SUPPORTED_IMPORT_EXTENSIONS, type SetupMode, type SupportedImportExtension, buildCodegenConfig, codegenConfigKeys, inferProjectName, resolveDeliveryOutputDir, typeNamesForProject, writeCodegenConfig };