@xndrjs/i18n 0.2.0 → 0.3.0

package/src/codegen/generate-i18n-types.ts

@@ -11,7 +11,9 @@ import { formatNamespaceLoadersFile } from "./emit/namespace-loaders-file.js";
 import { formatTypesFile } from "./emit/types-file.js";
 import { analyzeDictionaries } from "./icu-analysis.js";
 import { collectRequestLocales, validateCodegenLocaleFallback } from "./locale-fallback.js";
-import { fail, toModuleBasename } from "./paths.js";
+import { enrichLocaleFallback } from "./locale-policy.js";
+import { fail, resolveImportExtension, toModuleBasename } from "./paths.js";
+import { prepareDictionaryEntries } from "./read-dictionary.js";
 
 function main() {
   const configArgIndex = process.argv.indexOf("--config");
@@ -26,7 +28,21 @@ function main() {
   }
 
   const config = loadConfig(configPath);
-  const entries = resolveNamespaces(config);
+  const sourceEntries = resolveNamespaces(config);
+  const generatedDirRelative = path.dirname(config.typesOutput);
+  let resolvedEntries;
+  let compiledFiles: string[];
+
+  try {
+    const prepared = prepareDictionaryEntries(projectRoot, sourceEntries, generatedDirRelative);
+    resolvedEntries = prepared.resolvedEntries;
+    compiledFiles = prepared.compiledFiles;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    fail(message);
+  }
+
+  const entries = resolvedEntries;
   const isSingle = Boolean(config.dictionary);
   const { loadOnInitSet, lazyEntries, hasLazy } = resolveLoadOnInit(config, entries, isSingle);
 
@@ -57,6 +73,7 @@ function main() {
   const localeFallbackConstName = config.localeFallbackConstName ?? "LOCALE_FALLBACK";
   const localeFallbackTypeName = `${localeTypeName}Fallback`;
   const factoryName = config.factoryName ?? "createI18n";
+  const importExtension = resolveImportExtension(config);
   const typesModule = toModuleBasename(typesOutputPath);
 
   const requestLocales = collectRequestLocales(locales, config.localeFallback);
@@ -69,6 +86,10 @@ function main() {
     ? entries.filter((entry) => loadOnInitSet.has(entry.namespace))
     : entries;
 
+  const localeFallbackForEmit = config.localeFallback
+    ? enrichLocaleFallback(locales, config.localeFallback)
+    : undefined;
+
   const typesContent = formatTypesFile({
     isSingle,
     entries,
@@ -79,7 +100,7 @@ function main() {
     localeTypeName,
     localeFallbackConstName,
     localeFallbackTypeName,
-    localeFallback: config.localeFallback,
+    localeFallback: localeFallbackForEmit,
     paramsByNamespace,
     requestLocaleUnion,
     hasLazy,
@@ -96,6 +117,7 @@ function main() {
     dictionaryOutputPath,
     typesOutputPath,
     schemaTypeName,
+    importExtension,
   });
 
   const instanceContent = formatInstanceFile({
@@ -109,6 +131,7 @@ function main() {
     localeFallbackConstName,
     factoryName,
     hasLocaleFallback: Boolean(config.localeFallback),
+    importExtension,
   });
 
   fs.mkdirSync(path.dirname(typesOutputPath), { recursive: true });
@@ -133,7 +156,8 @@ function main() {
       schemaTypeName,
       typesModule,
       isSingle,
-      dictionarySpecBlock
+      dictionarySpecBlock,
+      importExtension
     );
 
     fs.mkdirSync(path.dirname(dictionarySchemaOutputPath), { recursive: true });
@@ -159,7 +183,8 @@ function main() {
       typesModule,
       toModuleBasename(dictionarySchemaOutputPath),
       toModuleBasename(instanceOutputPath),
-      factoryName
+      factoryName,
+      importExtension
     );
 
     fs.mkdirSync(path.dirname(namespaceLoadersOutputPath), { recursive: true });
@@ -168,6 +193,9 @@ function main() {
   }
 
   console.log(`✅ Generated: ${generatedFiles.join(", ")}`);
+  if (compiledFiles.length > 0) {
+    console.log(`✅ Compiled: ${compiledFiles.join(", ")}`);
+  }
 }
 
 main();

package/src/codegen/icu-analysis.ts

@@ -2,11 +2,12 @@ import fs from "node:fs";
 import path from "node:path";
 import { parse } from "@formatjs/icu-messageformat-parser";
 import {
-  extractVariables,
-  mergeVariableSpecs,
+  extractVariableMeta,
+  mergeVariableMetaAcrossLocales,
   type VariableSpec,
 } from "../icu/extract-variables.js";
-import type { DictionaryJson, NamespaceEntry } from "./types.js";
+import type { NamespaceEntry } from "./types.js";
+import { readDictionaryFile } from "./read-dictionary.js";
 
 export function paramsTypeForVariables(variables: VariableSpec): string {
   const keys = Object.keys(variables);
@@ -47,12 +48,12 @@ export function analyzeDictionaries(
       continue;
     }
 
-    const dictionary = JSON.parse(fs.readFileSync(absolutePath, "utf8")) as DictionaryJson;
+    const dictionary = readDictionaryFile(absolutePath);
     paramsByNamespace[entry.namespace] = {};
     argsSpecByNamespace[entry.namespace] = {};
 
     for (const [key, localesByKey] of Object.entries(dictionary)) {
-      const variables: VariableSpec = {};
+      const localeMetas: ReturnType<typeof extractVariableMeta>[] = [];
 
       for (const locale of Object.keys(localesByKey)) {
         locales.add(locale);
@@ -61,8 +62,7 @@ export function analyzeDictionaries(
       for (const [locale, template] of Object.entries(localesByKey)) {
         try {
           const ast = parse(template);
-          const extracted = extractVariables(ast);
-          Object.assign(variables, mergeVariableSpecs(variables, extracted));
+          localeMetas.push(extractVariableMeta(ast));
         } catch (error) {
           hasErrors = true;
           const message = error instanceof Error ? error.message : String(error);
@@ -72,6 +72,21 @@ export function analyzeDictionaries(
         }
       }
 
+      if (localeMetas.length === 0) {
+        continue;
+      }
+
+      const mergedVariables = mergeVariableMetaAcrossLocales(localeMetas);
+      if (!mergedVariables.ok) {
+        hasErrors = true;
+        console.error(
+          `[Codegen Error] ${mergedVariables.message} — namespace "${entry.namespace}", key "${key}"`
+        );
+        continue;
+      }
+
+      const variables = mergedVariables.merged;
+
       paramsByNamespace[entry.namespace]![key] = paramsTypeForVariables(variables);
       argsSpecByNamespace[entry.namespace]![key] = variables;
     }

package/src/codegen/locale-policy.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { buildRequiredLocales, enrichLocaleFallback } from "./locale-policy.js";
+
+describe("locale-policy", () => {
+  it("buildRequiredLocales unions dictionary locales with fallback keys and targets", () => {
+    const locales = new Set(["en", "it"]);
+    const fallback = { en: null, "de-CH": "de-DE", "de-DE": "en", it: "en" };
+
+    expect(buildRequiredLocales(locales, fallback)).toEqual(["de-CH", "de-DE", "en", "it"]);
+    expect(buildRequiredLocales(locales)).toEqual(["en", "it"]);
+  });
+
+  it("enrichLocaleFallback adds null for required locales missing from config", () => {
+    const locales = new Set(["en", "fr"]);
+    const fallback = { en: null, it: "en" };
+
+    expect(enrichLocaleFallback(locales, fallback)).toEqual({
+      en: null,
+      fr: null,
+      it: "en",
+    });
+  });
+
+  it("enrichLocaleFallback is a no-op when all required locales are already configured", () => {
+    const locales = new Set(["en", "it"]);
+    const fallback = {
+      en: null,
+      "de-DE": "en",
+      "de-CH": "de-DE",
+      it: "en",
+    };
+
+    expect(enrichLocaleFallback(locales, fallback)).toEqual(fallback);
+  });
+});

package/src/codegen/locale-policy.ts

@@ -0,0 +1,26 @@
+import { collectRequestLocales } from "./locale-fallback.js";
+
+export function buildRequiredLocales(
+  dictionaryLocales: Set<string>,
+  configFallback?: Record<string, string | null>
+): string[] {
+  return [...collectRequestLocales(dictionaryLocales, configFallback)].sort();
+}
+
+export function enrichLocaleFallback(
+  dictionaryLocales: Set<string>,
+  configFallback: Record<string, string | null>
+): Record<string, string | null> {
+  const enriched: Record<string, string | null> = { ...configFallback };
+
+  for (const locale of buildRequiredLocales(dictionaryLocales, configFallback)) {
+    if (!(locale in enriched)) {
+      enriched[locale] = null;
+    }
+  }
+
+  const sortedEntries = Object.entries(enriched).sort(([left], [right]) =>
+    left.localeCompare(right)
+  );
+  return Object.fromEntries(sortedEntries);
+}

package/src/codegen/paths.ts

@@ -1,6 +1,9 @@
 import path from "node:path";
+import type { CodegenConfig, ImportExtension } from "./types.js";
+import { SUPPORTED_IMPORT_EXTENSIONS } from "./types.js";
 
 export const GENERATED_FILE_BANNER = "// Automatically generated code. Do not edit manually.\n";
+export const DEFAULT_IMPORT_EXTENSION: ImportExtension = "none";
 
 export function fail(message: string): never {
   console.error(message);
@@ -10,7 +13,7 @@ export function fail(message: string): never {
 
 export function toImportPath(fromFile: string, toFile: string): string {
   const relative = path.relative(path.dirname(fromFile), toFile).replace(/\\/g, "/");
-  const withoutExt = relative.replace(/\.json$/, "");
+  const withoutExt = relative.replace(/\.(json|ya?ml)$/i, "");
   return withoutExt.startsWith(".") ? withoutExt : `./${withoutExt}`;
 }
 
@@ -18,6 +21,29 @@ export function toModuleBasename(filePath: string): string {
   return path.basename(filePath).replace(/\.ts$/, "");
 }
 
+export function resolveImportExtension(
+  config: Pick<CodegenConfig, "importExtension">
+): ImportExtension {
+  const extension = config.importExtension ?? DEFAULT_IMPORT_EXTENSION;
+  if (!SUPPORTED_IMPORT_EXTENSIONS.includes(extension)) {
+    fail(
+      `[Codegen Error] importExtension must be "none", ".ts", or ".js", got ${JSON.stringify(extension)}.`
+    );
+  }
+  return extension;
+}
+
+export function importExtensionSuffix(importExtension: ImportExtension): string {
+  return importExtension === "none" ? "" : importExtension;
+}
+
+export function toRelativeModuleImport(
+  moduleBasename: string,
+  importExtension: ImportExtension
+): string {
+  return `./${moduleBasename}${importExtensionSuffix(importExtension)}`;
+}
+
 export function toImportIdentifier(namespace: string): string {
   const safe = namespace.replace(/[^a-zA-Z0-9_$]/g, "_");
   if (/^[0-9]/.test(safe)) {

package/src/codegen/read-dictionary.test.ts

@@ -0,0 +1,104 @@
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it, afterEach } from "vitest";
+import {
+  getDictionaryFormat,
+  prepareDictionaryEntries,
+  readDictionaryFile,
+  resolveCompiledJsonPath,
+} from "./read-dictionary.js";
+
+describe("read-dictionary", () => {
+  let tempDir: string;
+
+  afterEach(() => {
+    if (tempDir) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("detects dictionary formats from file extension", () => {
+    expect(getDictionaryFormat("translations/default.json")).toBe("json");
+    expect(getDictionaryFormat("translations/default.yaml")).toBe("yaml");
+    expect(getDictionaryFormat("translations/default.yml")).toBe("yaml");
+    expect(getDictionaryFormat("translations/default.toml")).toBeNull();
+  });
+
+  it("resolves compiled json path under the generated output directory", () => {
+    expect(
+      resolveCompiledJsonPath("src/i18n/translations/billing.yaml", "src/i18n/generated")
+    ).toBe("src/i18n/generated/translations/billing.json");
+    expect(resolveCompiledJsonPath("translations/billing.yml", "generated")).toBe(
+      "generated/translations/billing.json"
+    );
+  });
+
+  it("reads multiline yaml dictionaries", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-read-dict-"));
+    const yamlPath = join(tempDir, "welcome.yaml");
+    writeFileSync(
+      yamlPath,
+      `welcome:
+  en: |
+    Line one
+    Line two
+  it: Ciao {name}
+`
+    );
+
+    const dictionary = readDictionaryFile(yamlPath);
+    expect(dictionary.welcome?.en).toBe("Line one\nLine two\n");
+    expect(dictionary.welcome?.it).toBe("Ciao {name}");
+  });
+
+  it("compiles yaml sources to json under the generated output directory", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-read-dict-"));
+    mkdirSync(join(tempDir, "src/i18n/translations"), { recursive: true });
+    mkdirSync(join(tempDir, "src/i18n/generated"), { recursive: true });
+    writeFileSync(
+      join(tempDir, "src/i18n/translations/billing.yaml"),
+      `invoice_summary:
+  en: You have {count} invoices
+`
+    );
+
+    const result = prepareDictionaryEntries(
+      tempDir,
+      [{ namespace: "billing", filePath: "src/i18n/translations/billing.yaml" }],
+      "src/i18n/generated"
+    );
+
+    expect(result.resolvedEntries).toEqual([
+      { namespace: "billing", filePath: "src/i18n/generated/translations/billing.json" },
+    ]);
+    expect(result.compiledFiles).toEqual([
+      "src/i18n/translations/billing.yaml → src/i18n/generated/translations/billing.json",
+    ]);
+
+    const compiled = JSON.parse(
+      readFileSync(join(tempDir, "src/i18n/generated/translations/billing.json"), "utf8")
+    ) as Record<string, Record<string, string>>;
+    expect(compiled.invoice_summary?.en).toBe("You have {count} invoices");
+  });
+
+  it("keeps json sources unchanged", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-read-dict-"));
+    mkdirSync(join(tempDir, "translations"), { recursive: true });
+    writeFileSync(
+      join(tempDir, "translations/default.json"),
+      JSON.stringify({ welcome: { en: "Welcome {name}!" } })
+    );
+
+    const result = prepareDictionaryEntries(
+      tempDir,
+      [{ namespace: "default", filePath: "translations/default.json" }],
+      "generated"
+    );
+
+    expect(result.resolvedEntries).toEqual([
+      { namespace: "default", filePath: "translations/default.json" },
+    ]);
+    expect(result.compiledFiles).toEqual([]);
+  });
+});

package/src/codegen/read-dictionary.ts

@@ -0,0 +1,133 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import type { DictionaryJson, NamespaceEntry } from "./types.js";
+
+export const SUPPORTED_DICTIONARY_EXTENSIONS = [".json", ".yaml", ".yml"] as const;
+export type DictionaryFormat = "json" | "yaml";
+
+export function getDictionaryFormat(filePath: string): DictionaryFormat | null {
+  const extension = path.extname(filePath).toLowerCase();
+  if (extension === ".json") {
+    return "json";
+  }
+  if (extension === ".yaml" || extension === ".yml") {
+    return "yaml";
+  }
+  return null;
+}
+
+export function resolveCompiledJsonPath(sourcePath: string, generatedDirRelative: string): string {
+  const baseName = `${path.basename(sourcePath, path.extname(sourcePath))}.json`;
+  return path.join(generatedDirRelative, "translations", baseName).replace(/\\/g, "/");
+}
+
+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 (localesByKey === null || typeof localesByKey !== "object" || Array.isArray(localesByKey)) {
+      throw new Error(`[Codegen Error] ${context}: key "${key}" must map locales to strings.`);
+    }
+
+    for (const [locale, template] of Object.entries(localesByKey)) {
+      if (typeof template !== "string") {
+        throw new Error(
+          `[Codegen Error] ${context}: key "${key}", locale "${locale}" must be a string.`
+        );
+      }
+    }
+  }
+}
+
+export function readDictionaryFile(absolutePath: string): DictionaryJson {
+  const format = getDictionaryFormat(absolutePath);
+  if (!format) {
+    throw new Error(
+      `[Codegen Error] Unsupported dictionary format "${path.extname(absolutePath)}" for ${absolutePath}. Use .json, .yaml, or .yml.`
+    );
+  }
+
+  const source = fs.readFileSync(absolutePath, "utf8");
+  let parsed: unknown;
+
+  try {
+    parsed = format === "json" ? JSON.parse(source) : parseYaml(source);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`[Codegen Error] Failed to parse dictionary ${absolutePath}: ${message}`);
+  }
+
+  assertDictionaryShape(parsed, `Dictionary file ${absolutePath}`);
+  return parsed;
+}
+
+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;
+    }
+  }
+
+  fs.mkdirSync(path.dirname(absoluteJsonPath), { recursive: true });
+  fs.writeFileSync(absoluteJsonPath, nextContent);
+  return true;
+}
+
+export interface PrepareDictionariesResult {
+  resolvedEntries: NamespaceEntry[];
+  compiledFiles: string[];
+}
+
+export function prepareDictionaryEntries(
+  projectRoot: string,
+  entries: NamespaceEntry[],
+  generatedDirRelative: string
+): PrepareDictionariesResult {
+  const resolvedEntries: NamespaceEntry[] = [];
+  const compiledFiles: string[] = [];
+
+  for (const entry of entries) {
+    const sourceAbsolutePath = path.resolve(projectRoot, entry.filePath);
+    const format = getDictionaryFormat(entry.filePath);
+
+    if (!format) {
+      throw new Error(
+        `[Codegen Error] Namespace "${entry.namespace}" uses unsupported dictionary extension in "${entry.filePath}". Use .json, .yaml, or .yml.`
+      );
+    }
+
+    if (!fs.existsSync(sourceAbsolutePath)) {
+      throw new Error(
+        `[Codegen Error] Dictionary file not found for namespace "${entry.namespace}": ${sourceAbsolutePath}`
+      );
+    }
+
+    const dictionary = readDictionaryFile(sourceAbsolutePath);
+
+    if (format === "yaml") {
+      const compiledRelativePath = resolveCompiledJsonPath(entry.filePath, generatedDirRelative);
+      const compiledAbsolutePath = path.resolve(projectRoot, compiledRelativePath);
+      const wroteFile = writeCompiledJson(compiledAbsolutePath, dictionary);
+
+      if (wroteFile) {
+        compiledFiles.push(
+          `${path.relative(projectRoot, sourceAbsolutePath)} → ${compiledRelativePath}`
+        );
+      }
+      resolvedEntries.push({
+        namespace: entry.namespace,
+        filePath: compiledRelativePath,
+      });
+      continue;
+    }
+
+    resolvedEntries.push(entry);
+  }
+
+  return { resolvedEntries, compiledFiles };
+}

package/src/codegen/types.ts

@@ -1,3 +1,6 @@
+export const SUPPORTED_IMPORT_EXTENSIONS = ["none", ".ts", ".js"] as const;
+export type ImportExtension = (typeof SUPPORTED_IMPORT_EXTENSIONS)[number];
+
 export interface CodegenConfig {
   dictionary?: string;
   namespaces?: Record<string, string>;
@@ -8,6 +11,8 @@ export interface CodegenConfig {
   dictionarySchemaOutput?: string;
   loadOnInit?: string[];
   namespaceLoadersOutput?: string;
+  /** Extension used in relative imports between generated modules. Default: "none" */
+  importExtension?: ImportExtension;
   paramsTypeName: string;
   schemaTypeName: string;
   localeTypeName?: string;

package/src/ensure-namespace.test.ts

@@ -89,7 +89,7 @@ describe("ensureNamespacesLoadedImpl", () => {
     const options = {
       provider,
       resolveLoader: () => load,
-      validate: () => ({ ok: true, data: billingNs }),
+      validate: () => ({ ok: true, data: billingNs }) as const,
     };
 
     const first = ensureNamespacesLoadedImpl(options, ["billing"]);