@xndrjs/i18n 0.3.3 → 0.5.0-alpha.0

package/dist/codegen/index.js

@@ -0,0 +1,181 @@
+import { z } from 'zod';
+import path from 'path';
+import fs from 'fs';
+
+// src/codegen/codegen-config-schema.ts
+
+// src/codegen/constants.ts
+var SUPPORTED_IMPORT_EXTENSIONS = ["none", ".ts", ".js"];
+var IDENTIFIER_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var IDENTIFIER_NAME_REQUIREMENT = "allowed: letters, digits, underscore; must not start with a digit";
+
+// src/codegen/delivery-artifacts.ts
+var DELIVERY_AREA_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+function getDeliveryArtifactsStructureIssues(deliveryArtifacts) {
+  const issues = [];
+  for (const [area, locales] of Object.entries(deliveryArtifacts)) {
+    if (!DELIVERY_AREA_NAME_PATTERN.test(area)) {
+      issues.push({
+        path: ["deliveryArtifacts", area],
+        message: `Invalid delivery area name "${area}": must match ${DELIVERY_AREA_NAME_PATTERN.source}`
+      });
+    }
+    if (locales.length === 0) {
+      issues.push({
+        path: ["deliveryArtifacts", area],
+        message: `Delivery area "${area}" must include at least one locale.`
+      });
+    }
+  }
+  const localeToArea = /* @__PURE__ */ new Map();
+  for (const [area, locales] of Object.entries(deliveryArtifacts)) {
+    for (const locale of locales) {
+      const previousArea = localeToArea.get(locale);
+      if (previousArea) {
+        issues.push({
+          path: ["deliveryArtifacts", area],
+          message: `Locale "${locale}" appears in both "${previousArea}" and "${area}".`
+        });
+      } else {
+        localeToArea.set(locale, area);
+      }
+    }
+  }
+  return issues;
+}
+
+// src/codegen/codegen-config-schema.ts
+var localeFallbackSchema = z.record(z.string(), z.union([z.string(), z.null()]));
+var deliveryArtifactsSchema = z.record(z.string(), z.array(z.string().min(1)));
+var DELIVERY_MODES = ["canonical", "split-by-locale", "custom"];
+var codegenConfigShape = {
+  dictionary: z.string().min(1).optional(),
+  namespaces: z.record(z.string(), z.string().min(1)).optional(),
+  defaultNamespace: z.string().min(1).optional(),
+  typesOutput: z.string().min(1),
+  dictionaryOutput: z.string().min(1),
+  instanceOutput: z.string().min(1),
+  dictionarySchemaOutput: z.string().min(1).optional(),
+  loadOnInit: z.array(z.string().min(1)).optional(),
+  namespaceLoadersOutput: z.string().min(1).optional(),
+  importExtension: z.enum(SUPPORTED_IMPORT_EXTENSIONS).optional(),
+  paramsTypeName: z.string().min(1),
+  schemaTypeName: z.string().min(1),
+  localeTypeName: z.string().min(1).optional(),
+  localeFallbackConstName: z.string().min(1).optional(),
+  localeFallback: localeFallbackSchema.optional(),
+  factoryName: z.string().min(1).optional(),
+  delivery: z.enum(DELIVERY_MODES).optional().default("canonical"),
+  deliveryArtifacts: deliveryArtifactsSchema.optional(),
+  deliveryOutput: z.string().min(1).optional()
+};
+var codegenConfigKeys = Object.keys(
+  codegenConfigShape
+);
+z.object(codegenConfigShape).strict().superRefine((config, ctx) => {
+  const hasDictionary = config.dictionary !== void 0;
+  const hasNamespaces = config.namespaces !== void 0;
+  if (hasDictionary === hasNamespaces) {
+    ctx.addIssue({
+      code: "custom",
+      message: 'Specify exactly one of "dictionary" or "namespaces".'
+    });
+  }
+  if (config.namespaces) {
+    for (const namespace of Object.keys(config.namespaces)) {
+      if (!IDENTIFIER_NAME_PATTERN.test(namespace)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["namespaces", namespace],
+          message: `Invalid namespace name "${namespace}" (${IDENTIFIER_NAME_REQUIREMENT}).`
+        });
+      }
+    }
+  }
+  if (config.defaultNamespace !== void 0 && !IDENTIFIER_NAME_PATTERN.test(config.defaultNamespace)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["defaultNamespace"],
+      message: `Invalid namespace name "${config.defaultNamespace}" (${IDENTIFIER_NAME_REQUIREMENT}).`
+    });
+  }
+  if (config.delivery === "custom") {
+    if (!config.deliveryArtifacts) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["deliveryArtifacts"],
+        message: 'deliveryArtifacts is required when delivery is "custom".'
+      });
+    } else {
+      for (const issue of getDeliveryArtifactsStructureIssues(config.deliveryArtifacts)) {
+        ctx.addIssue({
+          code: "custom",
+          path: issue.path,
+          message: issue.message
+        });
+      }
+    }
+  } else if (config.deliveryArtifacts !== void 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["deliveryArtifacts"],
+      message: 'deliveryArtifacts is only allowed when delivery is "custom".'
+    });
+  }
+});
+function resolveDeliveryOutputDir(config) {
+  return config.deliveryOutput ?? path.dirname(config.typesOutput);
+}
+
+// src/codegen-config/type-names.ts
+function inferProjectName(dirName) {
+  const parts = dirName.split(/[-_]+/).filter(Boolean);
+  if (parts.length === 0) {
+    return "App";
+  }
+  return parts.map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function typeNamesForProject(project) {
+  return {
+    paramsTypeName: `${project}Params`,
+    schemaTypeName: `${project}Schema`,
+    localeTypeName: `${project}Locale`
+  };
+}
+
+// src/codegen-config/build-config.ts
+var GENERATED_DIR = "generated";
+var TRANSLATIONS_DIR = "translations";
+function buildCodegenConfig(mode, project) {
+  const typeNames = typeNamesForProject(project);
+  const base = {
+    typesOutput: `${GENERATED_DIR}/i18n-types.generated.ts`,
+    dictionaryOutput: `${GENERATED_DIR}/dictionary.generated.ts`,
+    instanceOutput: `${GENERATED_DIR}/instance.generated.ts`,
+    paramsTypeName: typeNames.paramsTypeName,
+    schemaTypeName: typeNames.schemaTypeName,
+    localeTypeName: typeNames.localeTypeName,
+    factoryName: "createI18n"
+  };
+  if (mode === "single") {
+    return {
+      dictionary: `${TRANSLATIONS_DIR}/translations.json`,
+      ...base
+    };
+  }
+  return {
+    namespaces: {
+      default: `${TRANSLATIONS_DIR}/default.json`
+    },
+    ...base
+  };
+}
+function writeCodegenConfig(configPath, config) {
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}
+`);
+}
+
+export { DELIVERY_MODES, SUPPORTED_IMPORT_EXTENSIONS, buildCodegenConfig, codegenConfigKeys, inferProjectName, resolveDeliveryOutputDir, typeNamesForProject, writeCodegenConfig };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/codegen/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/codegen/constants.ts","../../src/codegen/delivery-artifacts.ts","../../src/codegen/codegen-config-schema.ts","../../src/codegen-config/type-names.ts","../../src/codegen-config/build-config.ts","../../src/codegen-config/write-config.ts"],"names":["path"],"mappings":"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","file":"index.js","sourcesContent":["export const SUPPORTED_IMPORT_EXTENSIONS = [\"none\", \".ts\", \".js\"] as const;\nexport type SupportedImportExtension = (typeof SUPPORTED_IMPORT_EXTENSIONS)[number];\n\n// Translation keys and namespace names become TypeScript identifiers and\n// template-literal type segments in the generated code, so they must be valid\n// identifiers (e.g. \"app.title\" would emit the broken type `\"app.title:...\"`).\nexport const IDENTIFIER_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;\nexport const IDENTIFIER_NAME_REQUIREMENT =\n  \"allowed: letters, digits, underscore; must not start with a digit\";\n","/** Valid TypeScript identifier / filename segment for a delivery area id. */\nexport const DELIVERY_AREA_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;\n\nexport type DeliveryArtifactsMap = Record<string, readonly string[]>;\n\nexport type DeliveryArtifactsIssue = {\n  path: (string | number)[];\n  message: string;\n};\n\nexport function getDeliveryArtifactsStructureIssues(\n  deliveryArtifacts: DeliveryArtifactsMap\n): DeliveryArtifactsIssue[] {\n  const issues: DeliveryArtifactsIssue[] = [];\n\n  for (const [area, locales] of Object.entries(deliveryArtifacts)) {\n    if (!DELIVERY_AREA_NAME_PATTERN.test(area)) {\n      issues.push({\n        path: [\"deliveryArtifacts\", area],\n        message: `Invalid delivery area name \"${area}\": must match ${DELIVERY_AREA_NAME_PATTERN.source}`,\n      });\n    }\n\n    if (locales.length === 0) {\n      issues.push({\n        path: [\"deliveryArtifacts\", area],\n        message: `Delivery area \"${area}\" must include at least one locale.`,\n      });\n    }\n  }\n\n  const localeToArea = new Map<string, string>();\n  for (const [area, locales] of Object.entries(deliveryArtifacts)) {\n    for (const locale of locales) {\n      const previousArea = localeToArea.get(locale);\n      if (previousArea) {\n        issues.push({\n          path: [\"deliveryArtifacts\", area],\n          message: `Locale \"${locale}\" appears in both \"${previousArea}\" and \"${area}\".`,\n        });\n      } else {\n        localeToArea.set(locale, area);\n      }\n    }\n  }\n\n  return issues;\n}\n\nexport function getDeliveryArtifactsPartitionIssues(\n  deliveryArtifacts: DeliveryArtifactsMap,\n  requestLocales: ReadonlySet<string>\n): DeliveryArtifactsIssue[] {\n  const issues: DeliveryArtifactsIssue[] = [];\n  const artifactLocales = new Set<string>();\n\n  for (const locales of Object.values(deliveryArtifacts)) {\n    for (const locale of locales) {\n      artifactLocales.add(locale);\n    }\n  }\n\n  const missing = [...requestLocales].filter((locale) => !artifactLocales.has(locale)).sort();\n  if (missing.length > 0) {\n    issues.push({\n      path: [\"deliveryArtifacts\"],\n      message: `deliveryArtifacts is missing locales required by dictionaries and localeFallback: ${missing.join(\", \")}`,\n    });\n  }\n\n  const excess = [...artifactLocales].filter((locale) => !requestLocales.has(locale)).sort();\n  if (excess.length > 0) {\n    issues.push({\n      path: [\"deliveryArtifacts\"],\n      message: `deliveryArtifacts includes locales not required by dictionaries and localeFallback: ${excess.join(\", \")}`,\n    });\n  }\n\n  return issues;\n}\n\n/** Pre-emit validation gate for `deliveryArtifacts` in custom delivery mode. */\nexport function getDeliveryArtifactsIssues(\n  deliveryArtifacts: DeliveryArtifactsMap,\n  requestLocales: ReadonlySet<string>\n): DeliveryArtifactsIssue[] {\n  return [\n    ...getDeliveryArtifactsStructureIssues(deliveryArtifacts),\n    ...getDeliveryArtifactsPartitionIssues(deliveryArtifacts, requestLocales),\n  ];\n}\n\nexport function getDeliveryAreaNames(deliveryArtifacts: DeliveryArtifactsMap): string[] {\n  return Object.keys(deliveryArtifacts).sort();\n}\n\nexport function getLocaleDeliveryAreaMap(\n  deliveryArtifacts: DeliveryArtifactsMap\n): Record<string, string> {\n  const localeToArea: Record<string, string> = {};\n\n  for (const [area, locales] of Object.entries(deliveryArtifacts)) {\n    for (const locale of locales) {\n      localeToArea[locale] = area;\n    }\n  }\n\n  return localeToArea;\n}\n\nexport function formatLocaleDeliveryAreaBlock(\n  deliveryArtifacts: DeliveryArtifactsMap,\n  constName: string,\n  localeTypeName: string,\n  deliveryAreaTypeName: string\n): string {\n  const localeToArea = getLocaleDeliveryAreaMap(deliveryArtifacts);\n  const lines = Object.keys(localeToArea)\n    .sort()\n    .map((locale) => `  ${JSON.stringify(locale)}: ${JSON.stringify(localeToArea[locale])},`)\n    .join(\"\\n\");\n\n  return `export const ${constName} = {\\n${lines}\\n} as const satisfies Record<${localeTypeName}, ${deliveryAreaTypeName}>;\\n\\n`;\n}\n","import { z } from \"zod\";\nimport path from \"node:path\";\nimport {\n  IDENTIFIER_NAME_PATTERN,\n  IDENTIFIER_NAME_REQUIREMENT,\n  SUPPORTED_IMPORT_EXTENSIONS,\n} from \"./constants.js\";\nimport { getDeliveryArtifactsStructureIssues } from \"./delivery-artifacts.js\";\n\nconst localeFallbackSchema = z.record(z.string(), z.union([z.string(), z.null()]));\nconst deliveryArtifactsSchema = z.record(z.string(), z.array(z.string().min(1)));\n\nexport const DELIVERY_MODES = [\"canonical\", \"split-by-locale\", \"custom\"] as const;\nexport type DeliveryMode = (typeof DELIVERY_MODES)[number];\n\nconst codegenConfigShape = {\n  dictionary: z.string().min(1).optional(),\n  namespaces: z.record(z.string(), z.string().min(1)).optional(),\n  defaultNamespace: z.string().min(1).optional(),\n  typesOutput: z.string().min(1),\n  dictionaryOutput: z.string().min(1),\n  instanceOutput: z.string().min(1),\n  dictionarySchemaOutput: z.string().min(1).optional(),\n  loadOnInit: z.array(z.string().min(1)).optional(),\n  namespaceLoadersOutput: z.string().min(1).optional(),\n  importExtension: z.enum(SUPPORTED_IMPORT_EXTENSIONS).optional(),\n  paramsTypeName: z.string().min(1),\n  schemaTypeName: z.string().min(1),\n  localeTypeName: z.string().min(1).optional(),\n  localeFallbackConstName: z.string().min(1).optional(),\n  localeFallback: localeFallbackSchema.optional(),\n  factoryName: z.string().min(1).optional(),\n  delivery: z.enum(DELIVERY_MODES).optional().default(\"canonical\"),\n  deliveryArtifacts: deliveryArtifactsSchema.optional(),\n  deliveryOutput: z.string().min(1).optional(),\n};\n\nexport const codegenConfigKeys = Object.keys(\n  codegenConfigShape\n) as (keyof typeof codegenConfigShape)[];\n\nexport const codegenConfigSchema = z\n  .object(codegenConfigShape)\n  .strict()\n  .superRefine((config, ctx) => {\n    const hasDictionary = config.dictionary !== undefined;\n    const hasNamespaces = config.namespaces !== undefined;\n\n    if (hasDictionary === hasNamespaces) {\n      ctx.addIssue({\n        code: \"custom\",\n        message: 'Specify exactly one of \"dictionary\" or \"namespaces\".',\n      });\n    }\n\n    if (config.namespaces) {\n      for (const namespace of Object.keys(config.namespaces)) {\n        if (!IDENTIFIER_NAME_PATTERN.test(namespace)) {\n          ctx.addIssue({\n            code: \"custom\",\n            path: [\"namespaces\", namespace],\n            message: `Invalid namespace name \"${namespace}\" (${IDENTIFIER_NAME_REQUIREMENT}).`,\n          });\n        }\n      }\n    }\n\n    if (\n      config.defaultNamespace !== undefined &&\n      !IDENTIFIER_NAME_PATTERN.test(config.defaultNamespace)\n    ) {\n      ctx.addIssue({\n        code: \"custom\",\n        path: [\"defaultNamespace\"],\n        message: `Invalid namespace name \"${config.defaultNamespace}\" (${IDENTIFIER_NAME_REQUIREMENT}).`,\n      });\n    }\n\n    if (config.delivery === \"custom\") {\n      if (!config.deliveryArtifacts) {\n        ctx.addIssue({\n          code: \"custom\",\n          path: [\"deliveryArtifacts\"],\n          message: 'deliveryArtifacts is required when delivery is \"custom\".',\n        });\n      } else {\n        for (const issue of getDeliveryArtifactsStructureIssues(config.deliveryArtifacts)) {\n          ctx.addIssue({\n            code: \"custom\",\n            path: issue.path,\n            message: issue.message,\n          });\n        }\n      }\n    } else if (config.deliveryArtifacts !== undefined) {\n      ctx.addIssue({\n        code: \"custom\",\n        path: [\"deliveryArtifacts\"],\n        message: 'deliveryArtifacts is only allowed when delivery is \"custom\".',\n      });\n    }\n  });\n\nexport type CodegenConfigInput = z.input<typeof codegenConfigSchema>;\nexport type CodegenConfig = z.infer<typeof codegenConfigSchema>;\n\nexport function resolveDeliveryOutputDir(\n  config: Pick<CodegenConfig, \"typesOutput\" | \"deliveryOutput\">\n): string {\n  return config.deliveryOutput ?? path.dirname(config.typesOutput);\n}\n\nexport function formatCodegenConfigIssues(error: z.ZodError): string {\n  const issueLines = error.issues.map((issue) => {\n    const path = issue.path.length > 0 ? issue.path.join(\".\") : \"(root)\";\n    return `  - ${path}: ${issue.message}`;\n  });\n\n  return [\n    \"[Codegen Error] Invalid i18n.codegen.json:\",\n    ...issueLines,\n    \"\",\n    `Allowed keys: ${codegenConfigKeys.join(\", \")}`,\n  ].join(\"\\n\");\n}\n","export function inferProjectName(dirName: string): string {\n  const parts = dirName.split(/[-_]+/).filter(Boolean);\n  if (parts.length === 0) {\n    return \"App\";\n  }\n\n  return parts.map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(\"\");\n}\n\nexport function typeNamesForProject(project: string): {\n  paramsTypeName: string;\n  schemaTypeName: string;\n  localeTypeName: string;\n} {\n  return {\n    paramsTypeName: `${project}Params`,\n    schemaTypeName: `${project}Schema`,\n    localeTypeName: `${project}Locale`,\n  };\n}\n","import type { CodegenConfigInput } from \"../codegen/codegen-config-schema.js\";\nimport { typeNamesForProject } from \"./type-names.js\";\n\nexport type SetupMode = \"single\" | \"multi\";\n\nconst GENERATED_DIR = \"generated\";\nconst TRANSLATIONS_DIR = \"translations\";\n\nexport function buildCodegenConfig(mode: SetupMode, project: string): CodegenConfigInput {\n  const typeNames = typeNamesForProject(project);\n  const base = {\n    typesOutput: `${GENERATED_DIR}/i18n-types.generated.ts`,\n    dictionaryOutput: `${GENERATED_DIR}/dictionary.generated.ts`,\n    instanceOutput: `${GENERATED_DIR}/instance.generated.ts`,\n    paramsTypeName: typeNames.paramsTypeName,\n    schemaTypeName: typeNames.schemaTypeName,\n    localeTypeName: typeNames.localeTypeName,\n    factoryName: \"createI18n\",\n  } satisfies CodegenConfigInput;\n\n  if (mode === \"single\") {\n    return {\n      dictionary: `${TRANSLATIONS_DIR}/translations.json`,\n      ...base,\n    };\n  }\n\n  return {\n    namespaces: {\n      default: `${TRANSLATIONS_DIR}/default.json`,\n    },\n    ...base,\n  };\n}\n","import fs from \"node:fs\";\nimport path from \"node:path\";\nimport type { CodegenConfigInput } from \"../codegen/codegen-config-schema.js\";\n\nexport function writeCodegenConfig(configPath: string, config: CodegenConfigInput): void {\n  fs.mkdirSync(path.dirname(configPath), { recursive: true });\n  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\\n`);\n}\n"]}

package/dist/index.d.ts

@@ -1,6 +1,3 @@
-import { V as ValidationResult } from './types-C1CpXVOJ.js';
-import '@formatjs/icu-messageformat-parser';
-
 type LocaleDictionary = Record<string, string>;
 type KeyDictionary = Record<string, LocaleDictionary>;
 type MultiDictionary = Record<string, KeyDictionary>;
@@ -13,9 +10,23 @@ type LocaleOfMulti<Schema extends MultiDictionary> = {
     }[keyof Schema[NS]];
 }[keyof Schema] & string;
 type LocaleFallbackMap$1 = Record<string, string | null>;
-type RequestLocale<DictionaryLocale extends string, Fallback extends LocaleFallbackMap$1 | undefined = undefined> = DictionaryLocale | (Fallback extends LocaleFallbackMap$1 ? keyof Fallback & string : never);
+type MissingTranslationContext = {
+    /** Only set by the multi-namespace provider. */
+    namespace?: string;
+    key: string;
+    locale: string;
+    fallbackChain: string;
+};
+type OnMissingTranslation = "throw" | "key" | ((context: MissingTranslationContext) => string);
 type IcuTranslationProviderOptions<Fallback extends LocaleFallbackMap$1 | undefined = undefined> = {
     localeFallback?: Fallback;
+    /**
+     * Strategy when no template resolves for a key/locale (after walking the
+     * fallback chain). "throw" (default) raises an error, "key" returns the
+     * translation key itself, a function receives the context and returns the
+     * string to display. ICU syntax and formatting errors always throw.
+     */
+    onMissing?: OnMissingTranslation;
 };
 
 interface TranslationProviderSingleForLocale<Schema extends KeyDictionary, Params extends {
@@ -46,8 +57,10 @@ declare class IcuTranslationProviderSingle<Schema extends KeyDictionary, Params
     private dictionary;
     private compiledCache;
     private readonly localeFallback?;
+    private readonly onMissing;
     constructor(dictionary: Schema, options?: IcuTranslationProviderOptions<Fallback>);
     get<K extends keyof Schema & string>(key: K, locale: RequestLocales, ...args: Params[K] extends never ? [] : [params: Params[K]]): string;
+    getWithLocale(key: string, locale: string, params?: Record<string, unknown>): string;
     forLocale<Locale extends RequestLocales>(locale: Locale): IcuTranslationProviderSingleForLocale<Schema, Params, RequestLocales, Locale, Fallback>;
     getAll(): Schema;
     setAll(values: Schema): void;
@@ -91,9 +104,11 @@ declare class IcuTranslationProviderMulti<Schema extends MultiDictionary, Params
     private dictionary;
     private compiledCache;
     private readonly localeFallback?;
+    private readonly onMissing;
     private loadedNamespaces;
     constructor(dictionary: Partial<Schema>, options?: IcuTranslationProviderOptions<Fallback>);
     get<NS extends keyof Schema, K extends keyof Schema[NS] & keyof Params[NS] & string>(namespace: NS, key: K, locale: RequestLocales, ...args: Params[NS][K] extends never ? [] : [params: Params[NS][K]]): string;
+    getWithLocale(namespace: string, key: string, locale: string, params?: Record<string, unknown>): string;
     forLocale<Locale extends RequestLocales>(locale: Locale): IcuTranslationProviderMultiForLocale<Schema, Params, RequestLocales, Locale, Fallback>;
     getAll(): Schema;
     hasNamespace<NS extends keyof Schema & string>(namespace: NS): boolean;
@@ -112,24 +127,25 @@ declare function resolveLocaleTemplate(localeByKey: Record<string, string | unde
 declare function formatLocaleFallbackChain(requestedLocale: string, fallbackMap?: LocaleFallbackMap): string;
 
 /**
- * Builds a dictionary that contains only the requested locales.
+ * Builds a namespace dictionary that contains only the requested locales.
  * For each key and target locale, copies the direct template when present;
  * otherwise resolves through `localeFallback` (same rules as `.get()` at runtime).
  */
-declare function projectLocales<T extends KeyDictionary>(dictionary: T, locales: readonly string[], localeFallback?: LocaleFallbackMap$1): T;
+declare function projectNamespaceLocalesCore<T extends KeyDictionary>(dictionary: T, locales: readonly string[], localeFallback?: LocaleFallbackMap$1): T;
+/**
+ * Projects a single namespace for a custom delivery area.
+ * Full locales resolve through `localeFallback` (e.g. external chains like `it → en-US`);
+ * preserve locales copy only their direct canonical entry when present.
+ */
+declare function projectNamespaceForDeliveryAreaCore<T extends KeyDictionary>(dictionary: T, areaLocales: readonly string[], localeFallback?: LocaleFallbackMap$1): T;
+/**
+ * Projects a multi-namespace dictionary for a custom delivery area.
+ * Each namespace uses the same delivery-area rules as `projectNamespaceForDeliveryAreaCore`.
+ */
+declare function projectDictionaryForDeliveryAreaCore<T extends MultiDictionary>(dictionary: T, areaLocales: readonly string[], localeFallback?: LocaleFallbackMap$1): T;
 /**
  * Projects every namespace in a multi-namespace dictionary.
  */
-declare function projectNamespacesLocales<T extends MultiDictionary>(dictionary: T, locales: readonly string[], localeFallback?: LocaleFallbackMap$1): T;
-
-interface EnsureNamespacesLoadedOptions<Schema extends MultiDictionary, NS extends keyof Schema & string> {
-    provider: Pick<{
-        hasNamespace(namespace: NS): boolean;
-        setNamespace(namespace: NS, values: Schema[NS]): void;
-    }, "hasNamespace" | "setNamespace">;
-    resolveLoader: (namespace: NS) => () => Promise<unknown>;
-    validate: (namespace: NS, raw: unknown) => ValidationResult<Schema[NS]>;
-}
-declare function ensureNamespacesLoadedImpl<Schema extends MultiDictionary, NS extends keyof Schema & string>(options: EnsureNamespacesLoadedOptions<Schema, NS>, namespaces: NS[]): Promise<void>;
+declare function projectDictionaryLocalesCore<T extends MultiDictionary>(dictionary: T, locales: readonly string[], localeFallback?: LocaleFallbackMap$1): T;
 
-export { type EnsureNamespacesLoadedOptions, IcuTranslationProviderMulti, type IcuTranslationProviderOptions, IcuTranslationProviderSingle, type KeyDictionary, type LocaleDictionary, type LocaleFallbackMap$1 as LocaleFallbackMap, type LocaleOfMulti, type LocaleOfSingle, type MultiDictionary, type RequestLocale, type ResolvedLocaleTemplate, type TranslationProviderMulti, type TranslationProviderMultiForLocale, type TranslationProviderSingle, type TranslationProviderSingleForLocale, ensureNamespacesLoadedImpl, formatLocaleFallbackChain, projectLocales, projectNamespacesLocales, resolveLocaleTemplate, validateLocaleFallback };
+export { IcuTranslationProviderMulti, type IcuTranslationProviderOptions, IcuTranslationProviderSingle, type KeyDictionary, type LocaleDictionary, type LocaleFallbackMap$1 as LocaleFallbackMap, type LocaleOfMulti, type LocaleOfSingle, type MissingTranslationContext, type MultiDictionary, type OnMissingTranslation, type ResolvedLocaleTemplate, type TranslationProviderMulti, type TranslationProviderMultiForLocale, type TranslationProviderSingle, type TranslationProviderSingleForLocale, formatLocaleFallbackChain, projectDictionaryForDeliveryAreaCore, projectDictionaryLocalesCore, projectNamespaceForDeliveryAreaCore, projectNamespaceLocalesCore, resolveLocaleTemplate, validateLocaleFallback };