@xndrjs/i18n 0.2.0-alpha.0

package/src/resolve-locale.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+import {
+  formatLocaleFallbackChain,
+  resolveLocaleTemplate,
+  validateLocaleFallback,
+} from "./resolve-locale.js";
+
+const fallbackMap = {
+  en: null,
+  "de-DE": "en",
+  "de-CH": "de-DE",
+  it: "en",
+} as const;
+
+const localeByKey = {
+  en: "Hello",
+  it: "Ciao",
+};
+
+describe("resolveLocaleTemplate", () => {
+  it("returns the template for the requested locale when present", () => {
+    expect(resolveLocaleTemplate(localeByKey, "en")).toEqual({
+      template: "Hello",
+      resolvedLocale: "en",
+      fallbackChain: ["en"],
+    });
+  });
+
+  it("follows the fallback chain until a template is found", () => {
+    expect(resolveLocaleTemplate(localeByKey, "de-CH", fallbackMap)).toEqual({
+      template: "Hello",
+      resolvedLocale: "en",
+      fallbackChain: ["de-CH", "de-DE", "en"],
+    });
+  });
+
+  it("uses an intermediate locale when it has a template", () => {
+    const withGerman = { ...localeByKey, "de-DE": "Hallo" };
+    expect(resolveLocaleTemplate(withGerman, "de-CH", fallbackMap)).toEqual({
+      template: "Hallo",
+      resolvedLocale: "de-DE",
+      fallbackChain: ["de-CH", "de-DE"],
+    });
+  });
+
+  it("treats an empty string template as present", () => {
+    expect(resolveLocaleTemplate({ en: "" }, "en")).toEqual({
+      template: "",
+      resolvedLocale: "en",
+      fallbackChain: ["en"],
+    });
+  });
+
+  it("returns undefined when the chain ends with null fallback", () => {
+    expect(resolveLocaleTemplate(localeByKey, "de-CH", { "de-CH": null })).toBeUndefined();
+  });
+
+  it("returns undefined when the locale is unknown and has no fallback map entry", () => {
+    expect(resolveLocaleTemplate(localeByKey, "fr", fallbackMap)).toBeUndefined();
+  });
+
+  it("throws on circular fallback chains", () => {
+    expect(() =>
+      resolveLocaleTemplate(localeByKey, "de-CH", {
+        "de-CH": "de-DE",
+        "de-DE": "de-CH",
+      })
+    ).toThrow("[i18n] Circular locale fallback detected");
+  });
+});
+
+describe("validateLocaleFallback", () => {
+  it("accepts acyclic fallback maps", () => {
+    expect(() => validateLocaleFallback(fallbackMap)).not.toThrow();
+  });
+
+  it("rejects circular fallback maps at construction time", () => {
+    expect(() =>
+      validateLocaleFallback({
+        a: "b",
+        b: "a",
+      })
+    ).toThrow("[i18n] Circular locale fallback detected");
+  });
+});
+
+describe("formatLocaleFallbackChain", () => {
+  it("formats the fallback chain for error messages", () => {
+    expect(formatLocaleFallbackChain("de-CH", fallbackMap)).toBe("de-CH → de-DE → en");
+  });
+});

package/src/resolve-locale.ts

@@ -0,0 +1,88 @@
+export type LocaleFallbackMap = Record<string, string | null>;
+
+export interface ResolvedLocaleTemplate {
+  template: string;
+  resolvedLocale: string;
+  fallbackChain: readonly string[];
+}
+
+export function validateLocaleFallback(map: LocaleFallbackMap): void {
+  for (const startLocale of Object.keys(map)) {
+    const visited = new Set<string>();
+    let current: string | undefined = startLocale;
+
+    while (current !== undefined) {
+      if (visited.has(current)) {
+        throw new Error(`[i18n] Circular locale fallback detected involving "${current}"`);
+      }
+      visited.add(current);
+
+      const next: string | null | undefined = map[current];
+      if (next === undefined || next === null) {
+        break;
+      }
+      current = next;
+    }
+  }
+}
+
+export function resolveLocaleTemplate(
+  localeByKey: Record<string, string | undefined> | undefined,
+  requestedLocale: string,
+  fallbackMap?: LocaleFallbackMap
+): ResolvedLocaleTemplate | undefined {
+  const chain: string[] = [requestedLocale];
+  let currentLocale = requestedLocale;
+
+  while (true) {
+    const template = localeByKey?.[currentLocale];
+    if (template !== undefined) {
+      return { template, resolvedLocale: currentLocale, fallbackChain: chain };
+    }
+
+    if (!fallbackMap) {
+      return undefined;
+    }
+
+    const fallback = fallbackMap[currentLocale];
+    if (fallback === undefined || fallback === null) {
+      return undefined;
+    }
+
+    if (chain.includes(fallback)) {
+      throw new Error(
+        `[i18n] Circular locale fallback detected: ${[...chain, fallback].join(" → ")}`
+      );
+    }
+
+    chain.push(fallback);
+    currentLocale = fallback;
+  }
+}
+
+export function formatLocaleFallbackChain(
+  requestedLocale: string,
+  fallbackMap?: LocaleFallbackMap
+): string {
+  if (!fallbackMap) {
+    return requestedLocale;
+  }
+
+  const chain: string[] = [requestedLocale];
+  let current = requestedLocale;
+
+  while (true) {
+    const fallback = fallbackMap[current];
+    if (fallback === undefined || fallback === null) {
+      break;
+    }
+    if (chain.includes(fallback)) {
+      chain.push(fallback);
+      break;
+    }
+    chain.push(fallback);
+    current = fallback;
+  }
+
+  return chain.join(" → ");
+}

package/src/setup/setup-i18n.test.ts

@@ -0,0 +1,86 @@
+import { mkdtempSync, readFileSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it, afterEach } from "vitest";
+import { buildCodegenConfig, parseSetupArgs, runSetup } from "./setup-i18n.js";
+import { inferProjectName, typeNamesForProject } from "./type-names.js";
+
+describe("type-names", () => {
+  it("derives PascalCase project names from directory names", () => {
+    expect(inferProjectName("myapp")).toBe("Myapp");
+    expect(inferProjectName("my-app")).toBe("MyApp");
+    expect(inferProjectName("apps")).toBe("Apps");
+  });
+
+  it("builds type names from project prefix", () => {
+    expect(typeNamesForProject("MyApp")).toEqual({
+      paramsTypeName: "MyAppParams",
+      schemaTypeName: "MyAppSchema",
+      localeTypeName: "MyAppLocale",
+    });
+  });
+});
+
+describe("setup-i18n", () => {
+  let tempDir: string;
+
+  afterEach(() => {
+    if (tempDir) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("parses single and multi CLI args", () => {
+    expect(parseSetupArgs(["single", ".", "--project", "MyApp"])).toEqual({
+      mode: "single",
+      targetDir: ".",
+      project: "MyApp",
+      force: false,
+    });
+    expect(parseSetupArgs(["multi", "apps/myapp", "--project", "MyApp", "--force"])).toEqual({
+      mode: "multi",
+      targetDir: "apps/myapp",
+      project: "MyApp",
+      force: true,
+    });
+  });
+
+  it("scaffolds single mode with MyApp type names", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-setup-"));
+    const result = runSetup({ mode: "single", targetDir: tempDir, project: "MyApp" });
+
+    const config = JSON.parse(readFileSync(join(tempDir, "i18n.codegen.json"), "utf8"));
+    expect(config.dictionary).toBe("src/i18n/translations/translations.json");
+    expect(config.paramsTypeName).toBe("MyAppParams");
+    expect(config.schemaTypeName).toBe("MyAppSchema");
+    expect(config.localeTypeName).toBe("MyAppLocale");
+    expect(existsSync(join(tempDir, "src/i18n/translations/translations.json"))).toBe(true);
+    expect(existsSync(join(tempDir, "src/i18n/index.ts"))).toBe(true);
+    expect(result.created).toContain("i18n.codegen.json");
+  });
+
+  it("scaffolds multi mode with default namespace only", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-setup-"));
+    runSetup({ mode: "multi", targetDir: tempDir, project: "MyApp" });
+
+    const config = JSON.parse(readFileSync(join(tempDir, "i18n.codegen.json"), "utf8"));
+    expect(config.namespaces).toEqual({
+      default: "src/i18n/translations/default.json",
+    });
+    expect(existsSync(join(tempDir, "src/i18n/translations/default.json"))).toBe(true);
+  });
+
+  it("refuses to overwrite an existing config without --force", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-setup-"));
+    runSetup({ mode: "single", targetDir: tempDir, project: "MyApp" });
+
+    expect(() => runSetup({ mode: "single", targetDir: tempDir, project: "MyApp" })).toThrow(
+      "already exists"
+    );
+  });
+
+  it("buildCodegenConfig omits lazy and validation keys by default", () => {
+    expect(buildCodegenConfig("multi", "MyApp")).not.toHaveProperty("loadOnInit");
+    expect(buildCodegenConfig("multi", "MyApp")).not.toHaveProperty("dictionarySchemaOutput");
+  });
+});

package/src/setup/setup-i18n.ts

@@ -0,0 +1,179 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { inferProjectName, typeNamesForProject } from "./type-names.js";
+
+export type SetupMode = "single" | "multi";
+
+export interface SetupOptions {
+  mode: SetupMode;
+  targetDir: string;
+  project?: string | undefined;
+  force?: boolean | undefined;
+}
+
+export interface SetupResult {
+  targetDir: string;
+  project: string;
+  created: string[];
+}
+
+const I18N_ROOT = "src/i18n";
+const GENERATED_DIR = `${I18N_ROOT}/generated`;
+const TRANSLATIONS_DIR = `${I18N_ROOT}/translations`;
+
+const DEFAULT_STARTER = {
+  welcome: { en: "Welcome {name}!" },
+};
+
+const INDEX_TS =
+  `import { createI18n } from "./generated/instance.generated.js";\n\n` +
+  `export * from "./generated/instance.generated.js";\n` +
+  `export * from "./generated/dictionary.generated.js";\n` +
+  `export * from "./generated/i18n-types.generated.js";\n\n` +
+  `export const i18n = createI18n();\n`;
+
+function writeJson(filePath: string, value: unknown): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function writeText(filePath: string, content: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+}
+
+function relative(fromRoot: string, filePath: string): string {
+  return path.relative(fromRoot, filePath).replace(/\\/g, "/");
+}
+
+export function buildCodegenConfig(mode: SetupMode, project: string): Record<string, unknown> {
+  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,
+  };
+}
+
+export function runSetup(options: SetupOptions): SetupResult {
+  const targetDir = path.resolve(options.targetDir);
+  const project =
+    options.project ?? inferProjectName(path.basename(targetDir.replace(/[/\\]$/, "") || "app"));
+
+  if (!/^[A-Z][a-zA-Z0-9]*$/.test(project)) {
+    throw new Error(
+      `[Setup Error] Invalid project name "${project}". Use PascalCase (e.g. MyApp) via --project.`
+    );
+  }
+
+  const configPath = path.join(targetDir, "i18n.codegen.json");
+  if (fs.existsSync(configPath) && !options.force) {
+    throw new Error(
+      `[Setup Error] ${relative(process.cwd(), configPath)} already exists. Use --force to overwrite.`
+    );
+  }
+
+  const created: string[] = [];
+
+  writeJson(configPath, buildCodegenConfig(options.mode, project));
+  created.push(relative(targetDir, configPath));
+
+  if (options.mode === "single") {
+    const translationsPath = path.join(targetDir, TRANSLATIONS_DIR, "translations.json");
+    writeJson(translationsPath, DEFAULT_STARTER);
+    created.push(relative(targetDir, translationsPath));
+  } else {
+    const defaultPath = path.join(targetDir, TRANSLATIONS_DIR, "default.json");
+    writeJson(defaultPath, DEFAULT_STARTER);
+    created.push(relative(targetDir, defaultPath));
+  }
+
+  const indexPath = path.join(targetDir, I18N_ROOT, "index.ts");
+  writeText(indexPath, INDEX_TS);
+  created.push(relative(targetDir, indexPath));
+
+  fs.mkdirSync(path.join(targetDir, GENERATED_DIR), { recursive: true });
+
+  return { targetDir, project, created };
+}
+
+export function parseSetupArgs(argv: string[]): SetupOptions {
+  const mode = argv[0];
+  if (mode !== "single" && mode !== "multi") {
+    throw new Error(
+      `[Setup Error] Usage: xndrjs-i18n-setup <single|multi> [targetDir] [--project MyApp] [--force]`
+    );
+  }
+
+  let targetDir = ".";
+  let project: string | undefined;
+  let force = false;
+
+  for (let index = 1; index < argv.length; index++) {
+    const arg = argv[index]!;
+    if (arg === "--project") {
+      project = argv[++index];
+      if (!project) {
+        throw new Error("[Setup Error] --project requires a value.");
+      }
+      continue;
+    }
+    if (arg === "--force") {
+      force = true;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`[Setup Error] Unknown flag: ${arg}`);
+    }
+    targetDir = arg;
+  }
+
+  return { mode, targetDir, project, force };
+}
+
+function main() {
+  try {
+    const options = parseSetupArgs(process.argv.slice(2));
+    const result = runSetup(options);
+
+    console.log(`✅ Setup ${options.mode} i18n in ${result.targetDir}`);
+    console.log(
+      `   Project types: ${result.project}Params, ${result.project}Schema, ${result.project}Locale`
+    );
+    console.log(`   Created: ${result.created.join(", ")}`);
+    console.log("");
+    console.log("Next:");
+    console.log(`  cd ${path.relative(process.cwd(), result.targetDir) || "."}`);
+    console.log(
+      '  npm pkg set scripts.i18n:codegen="xndrjs-i18n-codegen --config i18n.codegen.json"'
+    );
+    console.log("  npm run i18n:codegen");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exit(1);
+  }
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  main();
+}

package/src/setup/type-names.ts

@@ -0,0 +1,20 @@
+export function inferProjectName(dirName: string): string {
+  const parts = dirName.split(/[-_]+/).filter(Boolean);
+  if (parts.length === 0) {
+    return "App";
+  }
+
+  return parts.map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+
+export function typeNamesForProject(project: string): {
+  paramsTypeName: string;
+  schemaTypeName: string;
+  localeTypeName: string;
+} {
+  return {
+    paramsTypeName: `${project}Params`,
+    schemaTypeName: `${project}Schema`,
+    localeTypeName: `${project}Locale`,
+  };
+}

package/src/types.ts

@@ -0,0 +1,34 @@
+import type { IntlMessageFormat } from "intl-messageformat";
+
+export type LocaleDictionary = Record<string, string>;
+export type KeyDictionary = Record<string, LocaleDictionary>;
+export type MultiDictionary = Record<string, KeyDictionary>;
+
+export type LocaleOfSingle<Schema extends KeyDictionary> = {
+  [K in keyof Schema]: keyof Schema[K];
+}[keyof Schema] &
+  string;
+
+export type LocaleOfMulti<Schema extends MultiDictionary> = {
+  [NS in keyof Schema]: {
+    [K in keyof Schema[NS]]: keyof Schema[NS][K];
+  }[keyof Schema[NS]];
+}[keyof Schema] &
+  string;
+
+export type LocaleFallbackMap = Record<string, string | null>;
+
+export type RequestLocale<
+  DictionaryLocale extends string,
+  Fallback extends LocaleFallbackMap | undefined = undefined,
+> = DictionaryLocale | (Fallback extends LocaleFallbackMap ? keyof Fallback & string : never);
+
+export type IcuTranslationProviderOptions<
+  Fallback extends LocaleFallbackMap | undefined = undefined,
+> = {
+  localeFallback?: Fallback;
+};
+
+export type LocaleCache = Record<string, IntlMessageFormat>;
+export type SingleCompiledCache = Record<string, LocaleCache>;
+export type MultiCompiledCache = Record<string, Record<string, LocaleCache>>;

package/src/validation/create-args-schema.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import type { VariableSpec, VariableType } from "../icu/extract-variables.js";
+
+export const variableTypeSchema = z.enum(["string", "number", "date"]);
+
+function formatVariableMismatch(expected: VariableSpec, found: VariableSpec): string {
+  const expectedKeys = Object.keys(expected).sort();
+  const foundKeys = Object.keys(found).sort();
+  return `Expected variables [${expectedKeys.join(", ")}], found [${foundKeys.join(", ")}]`;
+}
+
+export function createArgsSchema(expected: VariableSpec): z.ZodType<VariableSpec> {
+  return z.record(z.string(), variableTypeSchema).superRefine((found, ctx) => {
+    const expectedKeys = Object.keys(expected).sort();
+    const foundKeys = Object.keys(found).sort();
+
+    if (expectedKeys.join() !== foundKeys.join()) {
+      ctx.addIssue({
+        code: "custom",
+        message: formatVariableMismatch(expected, found),
+      });
+      return;
+    }
+
+    for (const [name, type] of Object.entries(expected)) {
+      if (found[name] !== type) {
+        ctx.addIssue({
+          code: "custom",
+          message: `Variable "${name}": expected ${type}, found ${found[name]}`,
+        });
+      }
+    }
+  });
+}
+
+export function mapArgsSchemaError(
+  expected: VariableSpec,
+  found: VariableSpec,
+  message: string,
+  path: readonly string[]
+) {
+  const expectedKeys = Object.keys(expected).sort();
+  const foundKeys = Object.keys(found).sort();
+
+  if (expectedKeys.join() !== foundKeys.join()) {
+    return {
+      kind: "variable_mismatch" as const,
+      path,
+      expected,
+      found,
+      message,
+    };
+  }
+
+  for (const [name, type] of Object.entries(expected)) {
+    const foundType = found[name];
+    if (foundType !== undefined && foundType !== type) {
+      return {
+        kind: "variable_type_mismatch" as const,
+        path,
+        variable: name,
+        expected: type,
+        found: foundType as VariableType,
+        message,
+      };
+    }
+  }
+
+  return {
+    kind: "variable_mismatch" as const,
+    path,
+    expected,
+    found,
+    message,
+  };
+}

package/src/validation/create-normalized-schema.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import type { VariableSpec } from "../icu/extract-variables.js";
+import { createArgsSchema, variableTypeSchema } from "./create-args-schema.js";
+import type { DictionarySpec, NormalizedDictionary, ParsedKeyEntry } from "./types.js";
+
+const parsedLocaleEntrySchema = z.object({
+  template: z.string(),
+  args: z.record(z.string(), variableTypeSchema),
+});
+
+const parsedKeyEntrySchema = z.object({
+  locales: z.record(z.string(), parsedLocaleEntrySchema),
+  mergedArgs: z.record(z.string(), variableTypeSchema),
+});
+
+function createKeyDictionarySchema(
+  argsByKey: Readonly<Record<string, VariableSpec>>
+): z.ZodType<Record<string, ParsedKeyEntry>> {
+  const keySchemas = Object.fromEntries(
+    Object.entries(argsByKey).map(([key, expectedArgs]) => [
+      key,
+      parsedKeyEntrySchema.extend({
+        mergedArgs: createArgsSchema(expectedArgs),
+      }),
+    ])
+  );
+
+  return z.object(keySchemas);
+}
+
+export function createNormalizedDictionarySchema(
+  spec: DictionarySpec
+): z.ZodType<NormalizedDictionary> {
+  if (spec.mode === "single") {
+    return z.object({
+      mode: z.literal("single"),
+      keys: createKeyDictionarySchema(spec.argsByKey),
+    }) as z.ZodType<NormalizedDictionary>;
+  }
+
+  const namespaceSchemas = Object.fromEntries(
+    Object.entries(spec.argsByKey).map(([namespace, argsByKey]) => [
+      namespace,
+      createKeyDictionarySchema(argsByKey),
+    ])
+  );
+
+  return z.object({
+    mode: z.literal("multi"),
+    namespaces: z.object(namespaceSchemas),
+  }) as z.ZodType<NormalizedDictionary>;
+}

package/src/validation/errors.ts

@@ -0,0 +1,41 @@
+import type { ValidationIssue, ValidationResult } from "./types.js";
+
+function issueMessage(issue: ValidationIssue): string {
+  switch (issue.kind) {
+    case "missing_key":
+      return `Missing required key at ${issue.path.join(".")}`;
+    case "invalid_input":
+    case "invalid_locale_value":
+    case "icu_syntax_error":
+    case "locale_args_mismatch":
+    case "variable_mismatch":
+    case "variable_type_mismatch":
+      return issue.message;
+  }
+}
+
+export function formatIssues(issues: readonly ValidationIssue[]): string {
+  return issues
+    .map((issue) => {
+      if ("path" in issue && issue.path.length > 0) {
+        return `[${issue.path.join(".")}] ${issue.kind}: ${issueMessage(issue)}`;
+      }
+      return `${issue.kind}: ${issueMessage(issue)}`;
+    })
+    .join("\n");
+}
+
+export class DictionaryValidationError extends Error {
+  constructor(public readonly issues: readonly ValidationIssue[]) {
+    super(formatIssues(issues));
+    this.name = "DictionaryValidationError";
+  }
+}
+
+export function assertValidDictionary<T>(
+  result: ValidationResult<T>
+): asserts result is { ok: true; data: T } {
+  if (!result.ok) {
+    throw new DictionaryValidationError(result.issues);
+  }
+}