@xndrjs/i18n 0.3.3 → 0.5.0-alpha.0

package/src/codegen/read-dictionary.ts

@@ -1,8 +1,21 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
+import { IDENTIFIER_NAME_PATTERN, IDENTIFIER_NAME_REQUIREMENT } from "./constants.js";
+import type { DeliveryMode } from "./codegen-config-schema.js";
+import type { DeliveryArtifactsMap } from "./delivery-artifacts.js";
+import {
+  projectNamespaceForDeliveryAreaCore,
+  projectNamespaceLocalesCore,
+} from "../project-locales.js";
+import type { LocaleFallbackMap } from "../types.js";
 import type { DictionaryJson, NamespaceEntry } from "./types.js";
+import { writeFileIfChanged } from "./write-file-if-changed.js";
 
+/**
+ * Dictionary I/O for codegen and audit: read/validate source files (`readDictionaryFile`)
+ * and write compiled or split JSON artifacts (`prepareDictionaryEntries`).
+ */
 export const SUPPORTED_DICTIONARY_EXTENSIONS = [".json", ".yaml", ".yml"] as const;
 export type DictionaryFormat = "json" | "yaml";
 
@@ -22,12 +35,70 @@ export function resolveCompiledJsonPath(sourcePath: string, generatedDirRelative
   return path.join(generatedDirRelative, "translations", baseName).replace(/\\/g, "/");
 }
 
+export function resolveSplitJsonPath(
+  sourcePath: string,
+  locale: string,
+  generatedDirRelative: string
+): string {
+  const baseName = path.basename(sourcePath, path.extname(sourcePath));
+  return path
+    .join(generatedDirRelative, "translations", `${baseName}.${locale}.json`)
+    .replace(/\\/g, "/");
+}
+
+export function resolveAreaJsonPath(
+  sourcePath: string,
+  area: string,
+  generatedDirRelative: string
+): string {
+  const baseName = path.basename(sourcePath, path.extname(sourcePath));
+  return path
+    .join(generatedDirRelative, "translations", `${baseName}.${area}.json`)
+    .replace(/\\/g, "/");
+}
+
+/** Projects a canonical dictionary into per-locale slices for split-by-locale delivery. */
+export function splitDictionaryByLocale(
+  dictionary: DictionaryJson,
+  locales: readonly string[],
+  localeFallback?: LocaleFallbackMap
+): Record<string, DictionaryJson> {
+  const byLocale: Record<string, DictionaryJson> = {};
+
+  for (const locale of locales) {
+    byLocale[locale] = projectNamespaceLocalesCore(dictionary, [locale], localeFallback);
+  }
+
+  return byLocale;
+}
+
+/** Projects a canonical dictionary into per-area slices for custom delivery. */
+export function splitDictionaryByDeliveryArea(
+  dictionary: DictionaryJson,
+  deliveryArtifacts: DeliveryArtifactsMap,
+  localeFallback?: LocaleFallbackMap
+): Record<string, DictionaryJson> {
+  const byArea: Record<string, DictionaryJson> = {};
+
+  for (const [area, areaLocales] of Object.entries(deliveryArtifacts)) {
+    byArea[area] = projectNamespaceForDeliveryAreaCore(dictionary, areaLocales, localeFallback);
+  }
+
+  return byArea;
+}
+
 function assertDictionaryShape(value: unknown, context: string): asserts value is DictionaryJson {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     throw new Error(`[Codegen Error] ${context} must be a plain object.`);
   }
 
   for (const [key, localesByKey] of Object.entries(value)) {
+    if (!IDENTIFIER_NAME_PATTERN.test(key)) {
+      throw new Error(
+        `[Codegen Error] ${context}: invalid key "${key}" (${IDENTIFIER_NAME_REQUIREMENT}).`
+      );
+    }
+
     if (localesByKey === null || typeof localesByKey !== "object" || Array.isArray(localesByKey)) {
       throw new Error(`[Codegen Error] ${context}: key "${key}" must map locales to strings.`);
     }
@@ -42,6 +113,7 @@ function assertDictionaryShape(value: unknown, context: string): asserts value i
   }
 }
 
+/** Reads and shape-validates a dictionary file from disk (JSON or YAML). */
 export function readDictionaryFile(absolutePath: string): DictionaryJson {
   const format = getDictionaryFormat(absolutePath);
   if (!format) {
@@ -65,32 +137,52 @@ export function readDictionaryFile(absolutePath: string): DictionaryJson {
 }
 
 function writeCompiledJson(absoluteJsonPath: string, dictionary: DictionaryJson): boolean {
-  const nextContent = `${JSON.stringify(dictionary, null, 2)}\n`;
-  if (fs.existsSync(absoluteJsonPath)) {
-    const currentContent = fs.readFileSync(absoluteJsonPath, "utf8");
-    if (currentContent === nextContent) {
-      return false;
-    }
-  }
+  return writeFileIfChanged(absoluteJsonPath, `${JSON.stringify(dictionary, null, 2)}\n`);
+}
 
-  fs.mkdirSync(path.dirname(absoluteJsonPath), { recursive: true });
-  fs.writeFileSync(absoluteJsonPath, nextContent);
-  return true;
+export interface PrepareDictionaryEntriesOptions {
+  dictionariesByNamespace: Record<string, DictionaryJson>;
+  delivery?: DeliveryMode;
+  localeFallback?: LocaleFallbackMap | undefined;
+  requestLocales?: readonly string[] | undefined;
+  deliveryArtifacts?: DeliveryArtifactsMap | undefined;
 }
 
 export interface PrepareDictionariesResult {
   resolvedEntries: NamespaceEntry[];
+  splitPathsByNamespace: Record<string, Record<string, string>>;
   compiledFiles: string[];
 }
 
+/**
+ * Phase 2 of codegen: materialize JSON artifacts on disk (YAML compile, locale/area split).
+ * Returns `splitPathsByNamespace` consumed by dictionary and namespace-loader emitters.
+ */
 export function prepareDictionaryEntries(
   projectRoot: string,
   entries: NamespaceEntry[],
-  generatedDirRelative: string
+  generatedDirRelative: string,
+  options: PrepareDictionaryEntriesOptions
 ): PrepareDictionariesResult {
+  const delivery = options.delivery ?? "canonical";
+  const { dictionariesByNamespace, localeFallback, requestLocales, deliveryArtifacts } = options;
   const resolvedEntries: NamespaceEntry[] = [];
+  const splitPathsByNamespace: Record<string, Record<string, string>> = {};
   const compiledFiles: string[] = [];
 
+  if (delivery === "split-by-locale" && (!requestLocales || requestLocales.length === 0)) {
+    throw new Error(
+      "[Codegen Error] split-by-locale delivery requires at least one request locale."
+    );
+  }
+
+  if (
+    delivery === "custom" &&
+    (!deliveryArtifacts || Object.keys(deliveryArtifacts).length === 0)
+  ) {
+    throw new Error("[Codegen Error] custom delivery requires deliveryArtifacts.");
+  }
+
   for (const entry of entries) {
     const sourceAbsolutePath = path.resolve(projectRoot, entry.filePath);
     const format = getDictionaryFormat(entry.filePath);
@@ -101,13 +193,70 @@ export function prepareDictionaryEntries(
       );
     }
 
-    if (!fs.existsSync(sourceAbsolutePath)) {
+    const dictionary = dictionariesByNamespace[entry.namespace];
+    if (!dictionary) {
       throw new Error(
-        `[Codegen Error] Dictionary file not found for namespace "${entry.namespace}": ${sourceAbsolutePath}`
+        `[Codegen Error] Missing parsed dictionary for namespace "${entry.namespace}".`
       );
     }
 
-    const dictionary = readDictionaryFile(sourceAbsolutePath);
+    if (delivery === "split-by-locale") {
+      const splitPaths: Record<string, string> = {};
+      const dictionariesByLocale = splitDictionaryByLocale(
+        dictionary,
+        requestLocales!,
+        localeFallback
+      );
+
+      for (const locale of requestLocales!) {
+        const splitRelativePath = resolveSplitJsonPath(
+          entry.filePath,
+          locale,
+          generatedDirRelative
+        );
+        const splitAbsolutePath = path.resolve(projectRoot, splitRelativePath);
+        const wroteFile = writeCompiledJson(splitAbsolutePath, dictionariesByLocale[locale]!);
+
+        if (wroteFile) {
+          compiledFiles.push(
+            `${path.relative(projectRoot, sourceAbsolutePath)} → ${splitRelativePath}`
+          );
+        }
+
+        splitPaths[locale] = splitRelativePath;
+      }
+
+      splitPathsByNamespace[entry.namespace] = splitPaths;
+      resolvedEntries.push(entry);
+      continue;
+    }
+
+    if (delivery === "custom") {
+      const splitPaths: Record<string, string> = {};
+      const dictionariesByArea = splitDictionaryByDeliveryArea(
+        dictionary,
+        deliveryArtifacts!,
+        localeFallback
+      );
+
+      for (const area of Object.keys(deliveryArtifacts!).sort()) {
+        const areaRelativePath = resolveAreaJsonPath(entry.filePath, area, generatedDirRelative);
+        const areaAbsolutePath = path.resolve(projectRoot, areaRelativePath);
+        const wroteFile = writeCompiledJson(areaAbsolutePath, dictionariesByArea[area]!);
+
+        if (wroteFile) {
+          compiledFiles.push(
+            `${path.relative(projectRoot, sourceAbsolutePath)} → ${areaRelativePath}`
+          );
+        }
+
+        splitPaths[area] = areaRelativePath;
+      }
+
+      splitPathsByNamespace[entry.namespace] = splitPaths;
+      resolvedEntries.push(entry);
+      continue;
+    }
 
     if (format === "yaml") {
       const compiledRelativePath = resolveCompiledJsonPath(entry.filePath, generatedDirRelative);
@@ -129,5 +278,5 @@ export function prepareDictionaryEntries(
     resolvedEntries.push(entry);
   }
 
-  return { resolvedEntries, compiledFiles };
+  return { resolvedEntries, splitPathsByNamespace, compiledFiles };
 }

package/src/codegen/write-file-if-changed.test.ts

@@ -0,0 +1,42 @@
+import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { writeFileIfChanged } from "./write-file-if-changed.js";
+
+describe("writeFileIfChanged", () => {
+  let tempDir: string;
+
+  afterEach(() => {
+    if (tempDir) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("creates missing files together with their parent directories", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-write-"));
+    const filePath = join(tempDir, "nested/dir/output.ts");
+
+    expect(writeFileIfChanged(filePath, "export {};\n")).toBe(true);
+    expect(readFileSync(filePath, "utf8")).toBe("export {};\n");
+  });
+
+  it("skips the write when content is unchanged", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-write-"));
+    const filePath = join(tempDir, "output.ts");
+    writeFileSync(filePath, "export {};\n");
+    const mtimeBefore = statSync(filePath).mtimeMs;
+
+    expect(writeFileIfChanged(filePath, "export {};\n")).toBe(false);
+    expect(statSync(filePath).mtimeMs).toBe(mtimeBefore);
+  });
+
+  it("overwrites the file when content differs", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-write-"));
+    const filePath = join(tempDir, "output.ts");
+    writeFileSync(filePath, "export const a = 1;\n");
+
+    expect(writeFileIfChanged(filePath, "export const a = 2;\n")).toBe(true);
+    expect(readFileSync(filePath, "utf8")).toBe("export const a = 2;\n");
+  });
+});

package/src/codegen/write-file-if-changed.ts

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Writes `content` to `absolutePath` only when it differs from the current
+ * file content, keeping mtimes stable for downstream watchers/bundlers.
+ * Returns true when the file was actually written.
+ */
+export function writeFileIfChanged(absolutePath: string, content: string): boolean {
+  if (fs.existsSync(absolutePath)) {
+    const currentContent = fs.readFileSync(absolutePath, "utf8");
+    if (currentContent === content) {
+      return false;
+    }
+  }
+
+  fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+  fs.writeFileSync(absolutePath, content);
+  return true;
+}

package/src/codegen-config/build-config.ts

@@ -0,0 +1,34 @@
+import type { CodegenConfigInput } from "../codegen/codegen-config-schema.js";
+import { typeNamesForProject } from "./type-names.js";
+
+export type SetupMode = "single" | "multi";
+
+const GENERATED_DIR = "generated";
+const TRANSLATIONS_DIR = "translations";
+
+export function buildCodegenConfig(mode: SetupMode, project: string): CodegenConfigInput {
+  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",
+  } satisfies CodegenConfigInput;
+
+  if (mode === "single") {
+    return {
+      dictionary: `${TRANSLATIONS_DIR}/translations.json`,
+      ...base,
+    };
+  }
+
+  return {
+    namespaces: {
+      default: `${TRANSLATIONS_DIR}/default.json`,
+    },
+    ...base,
+  };
+}

package/src/codegen-config/codegen-config.test.ts

@@ -0,0 +1,32 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it, afterEach } from "vitest";
+import { buildCodegenConfig, type CodegenConfigInput, writeCodegenConfig } from "./index.js";
+
+describe("codegen-config", () => {
+  let tempDir: string;
+
+  afterEach(() => {
+    if (tempDir) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("buildCodegenConfig returns a valid single-mode input shape", () => {
+    const config = buildCodegenConfig("single", "MyApp");
+    expect(config.dictionary).toBe("translations/translations.json");
+    expect(config.paramsTypeName).toBe("MyAppParams");
+    expect(config).not.toHaveProperty("namespaces");
+  });
+
+  it("writeCodegenConfig writes formatted JSON", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-codegen-config-"));
+    const configPath = join(tempDir, "i18n/i18n.codegen.json");
+    const config: CodegenConfigInput = buildCodegenConfig("multi", "Demo");
+
+    writeCodegenConfig(configPath, config);
+
+    expect(readFileSync(configPath, "utf8")).toBe(`${JSON.stringify(config, null, 2)}\n`);
+  });
+});

package/src/codegen-config/index.ts

@@ -0,0 +1,21 @@
+export type {
+  CodegenConfig,
+  CodegenConfigInput,
+  DeliveryMode,
+} from "../codegen/codegen-config-schema.js";
+export {
+  codegenConfigKeys,
+  DELIVERY_MODES,
+  resolveDeliveryOutputDir,
+} from "../codegen/codegen-config-schema.js";
+
+export type { DeliveryArtifactsMap } from "../codegen/delivery-artifacts.js";
+
+export {
+  SUPPORTED_IMPORT_EXTENSIONS,
+  type SupportedImportExtension,
+} from "../codegen/constants.js";
+
+export { buildCodegenConfig, type SetupMode } from "./build-config.js";
+export { inferProjectName, typeNamesForProject } from "./type-names.js";
+export { writeCodegenConfig } from "./write-config.js";

package/src/codegen-config/write-config.ts

@@ -0,0 +1,8 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { CodegenConfigInput } from "../codegen/codegen-config-schema.js";
+
+export function writeCodegenConfig(configPath: string, config: CodegenConfigInput): void {
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+}

package/src/deep-freeze.test.ts

@@ -12,6 +12,19 @@ describe("deepFreeze", () => {
       value.welcome.en = "Hacked";
     }).toThrow(TypeError);
   });
+
+  it("does not recurse forever on cyclic structures", () => {
+    const value: { name: string; self?: unknown; child: { parent?: unknown } } = {
+      name: "root",
+      child: {},
+    };
+    value.self = value;
+    value.child.parent = value;
+
+    expect(() => deepFreeze(value)).not.toThrow();
+    expect(Object.isFrozen(value)).toBe(true);
+    expect(Object.isFrozen(value.child)).toBe(true);
+  });
 });
 
 describe("cloneAndFreeze", () => {

package/src/deep-freeze.ts

@@ -3,6 +3,11 @@ export function deepFreeze<T>(value: T): T {
     return value;
   }
 
+  // Guards against infinite recursion on cyclic structures.
+  if (Object.isFrozen(value)) {
+    return value;
+  }
+
   Object.freeze(value);
 
   for (const child of Object.values(value)) {

package/src/format-core.ts

@@ -0,0 +1,91 @@
+import { IntlMessageFormat } from "intl-messageformat";
+import { formatLocaleFallbackChain, resolveLocaleTemplate } from "./resolve-locale.js";
+import type { LocaleCache, LocaleFallbackMap, OnMissingTranslation } from "./types.js";
+
+export type FormatCoreContext = {
+  key: string;
+  namespace?: string | undefined;
+  locale: string;
+  localeFallback?: LocaleFallbackMap | undefined;
+  onMissing: OnMissingTranslation;
+};
+
+export type ResolveAndFormatOptions = {
+  localeByKey: Record<string, string | undefined> | undefined;
+  locale: string;
+  params?: Record<string, unknown> | undefined;
+  getCache: (resolvedLocale: string) => LocaleCache;
+  context: FormatCoreContext;
+};
+
+function formatErrorLabel(context: Pick<FormatCoreContext, "key" | "namespace">): string {
+  if (context.namespace !== undefined) {
+    return `namespace "${context.namespace}", key "${context.key}"`;
+  }
+  return `key "${context.key}"`;
+}
+
+function formatMissingError(context: FormatCoreContext): string {
+  const chain = formatLocaleFallbackChain(context.locale, context.localeFallback);
+  if (context.namespace !== undefined) {
+    return `[i18n] Missing key or locale: namespace "${context.namespace}", key "${context.key}" [${context.locale}] (fallback chain: ${chain})`;
+  }
+  return `[i18n] Missing key or locale: "${context.key}" [${context.locale}] (fallback chain: ${chain})`;
+}
+
+function resolveMissing(context: FormatCoreContext): string {
+  const chain = formatLocaleFallbackChain(context.locale, context.localeFallback);
+  if (context.onMissing === "key") {
+    if (context.namespace !== undefined) {
+      return `${context.namespace}.${context.key}`;
+    }
+    return context.key;
+  }
+  if (typeof context.onMissing === "function") {
+    return context.onMissing({
+      ...(context.namespace !== undefined ? { namespace: context.namespace } : {}),
+      key: context.key,
+      locale: context.locale,
+      fallbackChain: chain,
+    });
+  }
+  throw new Error(formatMissingError(context));
+}
+
+/**
+ * Shared runtime path for both ICU providers: resolve locale (with fallback) →
+ * compile template (cached) → format with params; handles missing keys via `onMissing`.
+ */
+export function resolveAndFormat(options: ResolveAndFormatOptions): string {
+  const { localeByKey, locale, params, getCache, context } = options;
+  const resolved = resolveLocaleTemplate(localeByKey, locale, context.localeFallback);
+
+  if (!resolved) {
+    return resolveMissing(context);
+  }
+
+  const { template, resolvedLocale } = resolved;
+  const cache = getCache(resolvedLocale);
+  const cacheKey = context.key;
+  const label = formatErrorLabel(context);
+
+  if (!cache[cacheKey]) {
+    try {
+      cache[cacheKey] = new IntlMessageFormat(template, resolvedLocale);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `[i18n ICU Syntax Error] Dictionary error for ${label} [${resolvedLocale}]: ${message}`
+      );
+    }
+  }
+
+  try {
+    return cache[cacheKey].format(params) as string;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `[i18n Formatting Error] Invalid or missing parameters for ${label} [${resolvedLocale}]: ${message}`
+    );
+  }
+}

package/src/index.ts

@@ -17,8 +17,9 @@ export type {
   LocaleFallbackMap,
   LocaleOfMulti,
   LocaleOfSingle,
+  MissingTranslationContext,
   MultiDictionary,
-  RequestLocale,
+  OnMissingTranslation,
 } from "./types.js";
 
 export {
@@ -28,7 +29,9 @@ export {
 } from "./resolve-locale.js";
 export type { ResolvedLocaleTemplate } from "./resolve-locale.js";
 
-export { projectLocales, projectNamespacesLocales } from "./project-locales.js";
-
-export { ensureNamespacesLoadedImpl } from "./ensure-namespace.js";
-export type { EnsureNamespacesLoadedOptions } from "./ensure-namespace.js";
+export {
+  projectDictionaryForDeliveryAreaCore,
+  projectDictionaryLocalesCore,
+  projectNamespaceForDeliveryAreaCore,
+  projectNamespaceLocalesCore,
+} from "./project-locales.js";