@xndrjs/i18n 0.2.0-alpha.0

package/src/IcuTranslationProviderSingle.test.ts

@@ -0,0 +1,314 @@
+import { describe, expect, it } from "vitest";
+import { IcuTranslationProviderSingle } from "./IcuTranslationProviderSingle.js";
+import type { LocaleOfSingle } from "./types.js";
+
+type TestSchema = {
+  login_button: { en: string; it: string };
+  welcome: { en: string; it: string };
+  empty_label: { en: string };
+  broken: { en: string };
+  invoice_count: { en: string; it: string };
+  dashboard_status: { en: string; it: string };
+  inbox_owner: { en: string; it: string };
+  ranking_position: { en: string; it: string };
+  account_balance: { en: string; it: string };
+  appointment_summary: { en: string; it: string };
+};
+
+type TestParams = {
+  login_button: never;
+  welcome: { name: string };
+  empty_label: never;
+  broken: { name: string };
+  invoice_count: { count: number };
+  dashboard_status: { msgCount: number; chatCount: number };
+  inbox_owner: { gender: string; name: string };
+  ranking_position: { position: number };
+  account_balance: { amount: number };
+  appointment_summary: { dueDate: Date | number; startTime: Date | number };
+};
+
+const dictionary: TestSchema = {
+  login_button: { en: "Login", it: "Accedi" },
+  welcome: { en: "Welcome {name}!", it: "Benvenuto {name}!" },
+  empty_label: { en: "" },
+  broken: { en: "Hi {name" },
+  invoice_count: {
+    en: "You have {count, plural, one {1 invoice} other {{count} invoices}}",
+    it: "Hai {count, plural, one {1 fattura} other {{count} fatture}}",
+  },
+  dashboard_status: {
+    en: "You have {msgCount, plural, one {1 message} other {{msgCount} messages}} in {chatCount, plural, one {one chat} other {{chatCount} chats}}",
+    it: "Hai {msgCount, plural, one {1 messaggio} other {{msgCount} messaggi}} in {chatCount, plural, one {una chat} other {{chatCount} chat}}",
+  },
+  inbox_owner: {
+    en: "{gender, select, female {{name} owns her inbox} male {{name} owns his inbox} other {{name} owns their inbox}}",
+    it: "{gender, select, other {{name} gestisce la propria casella}}",
+  },
+  ranking_position: {
+    en: "You finished {position, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}",
+    it: "Hai concluso al {position, selectordinal, one {#°} other {#°}} posto",
+  },
+  account_balance: {
+    en: "Balance: {amount, number, ::currency/EUR}",
+    it: "Saldo: {amount, number, ::currency/EUR}",
+  },
+  appointment_summary: {
+    en: "Due {dueDate, date, short} at {startTime, time, short}",
+    it: "Scade il {dueDate, date, short} alle {startTime, time, short}",
+  },
+};
+
+describe("IcuTranslationProviderSingle", () => {
+  const provider = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary);
+
+  it("returns a static translation without params", () => {
+    expect(provider.get("login_button", "it")).toBe("Accedi");
+  });
+
+  it("interpolates ICU arguments", () => {
+    expect(provider.get("welcome", "en", { name: "Ada" })).toBe("Welcome Ada!");
+  });
+
+  describe("ICU plural interpolation", () => {
+    it("formats a single numeric plural in English and Italian", () => {
+      expect(provider.get("invoice_count", "en", { count: 1 })).toBe("You have 1 invoice");
+      expect(provider.get("invoice_count", "en", { count: 5 })).toBe("You have 5 invoices");
+      expect(provider.get("invoice_count", "it", { count: 1 })).toBe("Hai 1 fattura");
+      expect(provider.get("invoice_count", "it", { count: 5 })).toBe("Hai 5 fatture");
+    });
+
+    it("formats nested numeric plurals with double-brace references", () => {
+      expect(provider.get("dashboard_status", "en", { msgCount: 1, chatCount: 1 })).toBe(
+        "You have 1 message in one chat"
+      );
+      expect(provider.get("dashboard_status", "en", { msgCount: 3, chatCount: 2 })).toBe(
+        "You have 3 messages in 2 chats"
+      );
+      expect(provider.get("dashboard_status", "it", { msgCount: 1, chatCount: 1 })).toBe(
+        "Hai 1 messaggio in una chat"
+      );
+      expect(provider.get("dashboard_status", "it", { msgCount: 3, chatCount: 2 })).toBe(
+        "Hai 3 messaggi in 2 chat"
+      );
+    });
+
+    it("throws when a required numeric plural parameter is missing", () => {
+      expect(() => provider.get("dashboard_status", "en", { msgCount: 1 } as never)).toThrow(
+        "[i18n Formatting Error]"
+      );
+    });
+  });
+
+  describe("additional ICU variants", () => {
+    it("formats select arguments as strings", () => {
+      expect(provider.get("inbox_owner", "en", { gender: "female", name: "Ada" })).toBe(
+        "Ada owns her inbox"
+      );
+      expect(provider.get("inbox_owner", "en", { gender: "unknown", name: "Sam" })).toBe(
+        "Sam owns their inbox"
+      );
+    });
+
+    it("formats Italian select with a single other branch and the same params", () => {
+      expect(provider.get("inbox_owner", "it", { gender: "female", name: "Ada" })).toBe(
+        "Ada gestisce la propria casella"
+      );
+      expect(provider.get("inbox_owner", "it", { gender: "male", name: "Luca" })).toBe(
+        "Luca gestisce la propria casella"
+      );
+    });
+
+    it("formats selectordinal arguments as numbers", () => {
+      expect(provider.get("ranking_position", "en", { position: 1 })).toBe("You finished 1st");
+      expect(provider.get("ranking_position", "en", { position: 2 })).toBe("You finished 2nd");
+      expect(provider.get("ranking_position", "en", { position: 3 })).toBe("You finished 3rd");
+      expect(provider.get("ranking_position", "en", { position: 4 })).toBe("You finished 4th");
+    });
+
+    it("formats number, date, and time arguments", () => {
+      const amount = 1234.5;
+      const when = new Date("2026-07-01T13:30:00Z");
+
+      const expectedAmount = new Intl.NumberFormat("en", {
+        style: "currency",
+        currency: "EUR",
+      }).format(amount);
+      const expectedDate = new Intl.DateTimeFormat("en", {
+        dateStyle: "short",
+      }).format(when);
+      const expectedTime = new Intl.DateTimeFormat("en", {
+        timeStyle: "short",
+      }).format(when);
+
+      expect(provider.get("account_balance", "en", { amount })).toBe(`Balance: ${expectedAmount}`);
+      expect(
+        provider.get("appointment_summary", "en", {
+          dueDate: when,
+          startTime: when,
+        })
+      ).toBe(`Due ${expectedDate} at ${expectedTime}`);
+    });
+  });
+
+  it("treats an empty string template as valid", () => {
+    expect(provider.get("empty_label", "en")).toBe("");
+  });
+
+  it("throws when the key or locale is missing", () => {
+    expect(() =>
+      provider.get("login_button", "fr" as unknown as LocaleOfSingle<TestSchema>)
+    ).toThrow('[i18n] Missing key or locale: "login_button" [fr] (fallback chain: fr)');
+    expect(() => provider.get("missing_key" as "login_button", "en")).toThrow(
+      '[i18n] Missing key or locale: "missing_key" [en] (fallback chain: en)'
+    );
+  });
+
+  it("throws on malformed ICU syntax", () => {
+    expect(() => provider.get("broken", "en", { name: "Ada" })).toThrow("[i18n ICU Syntax Error]");
+  });
+
+  it("throws when required parameters are missing", () => {
+    // @ts-expect-error
+    expect(() => provider.get("welcome", "en")).toThrow("[i18n Formatting Error]");
+  });
+
+  it("replaces the dictionary and invalidates cache on setAll", () => {
+    const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary);
+    expect(local.get("login_button", "en")).toBe("Login");
+
+    local.setAll({
+      ...dictionary,
+      login_button: { en: "Sign in", it: "Entra" },
+    });
+
+    expect(local.get("login_button", "en")).toBe("Sign in");
+  });
+
+  it("returns a deep-frozen snapshot from getAll", () => {
+    expect(provider.getAll()).toEqual(dictionary);
+    expect(provider.getAll()).not.toBe(dictionary);
+    expect(Object.isFrozen(provider.getAll())).toBe(true);
+  });
+
+  it("does not mutate the provider when getAll snapshot is modified", () => {
+    const snapshot = provider.getAll();
+    expect(() => {
+      snapshot.welcome.en = "Hacked";
+    }).toThrow(TypeError);
+    expect(provider.get("welcome", "en", { name: "Ada" })).toBe("Welcome Ada!");
+  });
+
+  it("does not reflect external dictionary mutations after construction", () => {
+    const external = {
+      login_button: { en: "Login", it: "Accedi" },
+      welcome: { en: "Welcome {name}!", it: "Benvenuto {name}!" },
+      empty_label: { en: "" },
+      broken: { en: "Hi {name" },
+      invoice_count: {
+        en: "You have {count, plural, one {1 invoice} other {{count} invoices}}",
+        it: "Hai {count, plural, one {1 fattura} other {{count} fatture}}",
+      },
+      dashboard_status: dictionary.dashboard_status,
+      inbox_owner: dictionary.inbox_owner,
+      ranking_position: dictionary.ranking_position,
+      account_balance: dictionary.account_balance,
+      appointment_summary: dictionary.appointment_summary,
+    };
+    const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(external);
+    external.login_button.en = "Sign in";
+    expect(local.get("login_button", "en")).toBe("Login");
+  });
+
+  describe("forLocale", () => {
+    it("binds a locale so get() no longer requires it", () => {
+      const en = provider.forLocale("en");
+
+      expect(en.locale).toBe("en");
+      expect(en.get("login_button")).toBe("Login");
+      expect(en.get("welcome", { name: "Ada" })).toBe("Welcome Ada!");
+    });
+
+    it("uses the parent provider cache and fallback rules", () => {
+      const fallbackMap = {
+        en: null,
+        "de-CH": "en",
+      } as const;
+      const fallbackProvider = new IcuTranslationProviderSingle<
+        TestSchema,
+        TestParams,
+        keyof typeof fallbackMap | LocaleOfSingle<TestSchema>,
+        typeof fallbackMap
+      >(dictionary, { localeFallback: fallbackMap });
+      const deCh = fallbackProvider.forLocale("de-CH");
+
+      expect(deCh.get("login_button")).toBe("Login");
+    });
+  });
+
+  describe("locale fallback", () => {
+    const fallbackMap = {
+      en: null,
+      "de-DE": "en",
+      "de-CH": "de-DE",
+      it: "en",
+    } as const;
+
+    const fallbackProvider = new IcuTranslationProviderSingle<
+      TestSchema,
+      TestParams,
+      keyof typeof fallbackMap | LocaleOfSingle<TestSchema>,
+      typeof fallbackMap
+    >(dictionary, { localeFallback: fallbackMap });
+
+    it("resolves a locale through the fallback chain", () => {
+      expect(fallbackProvider.get("login_button", "de-CH")).toBe("Login");
+    });
+
+    it("uses an intermediate locale template when available", () => {
+      const withGerman = new IcuTranslationProviderSingle<
+        TestSchema & {
+          login_button: { en: string; it: string; "de-DE": string };
+        },
+        TestParams,
+        keyof typeof fallbackMap | LocaleOfSingle<TestSchema>,
+        typeof fallbackMap
+      >(
+        {
+          ...dictionary,
+          login_button: { en: "Login", it: "Accedi", "de-DE": "Anmelden" },
+        },
+        { localeFallback: fallbackMap }
+      );
+
+      expect(withGerman.get("login_button", "de-CH")).toBe("Anmelden");
+    });
+
+    it("throws when the fallback chain cannot resolve a template", () => {
+      const unresolvedFallback = {
+        en: null,
+        "de-CH": "fr",
+        fr: null,
+      } as const;
+      const unresolvedProvider = new IcuTranslationProviderSingle<
+        TestSchema,
+        TestParams,
+        keyof typeof unresolvedFallback | LocaleOfSingle<TestSchema>,
+        typeof unresolvedFallback
+      >(dictionary, { localeFallback: unresolvedFallback });
+
+      expect(() => unresolvedProvider.get("login_button", "de-CH")).toThrow(
+        '[i18n] Missing key or locale: "login_button" [de-CH] (fallback chain: de-CH → fr)'
+      );
+    });
+
+    it("rejects circular fallback maps at construction", () => {
+      expect(
+        () =>
+          new IcuTranslationProviderSingle(dictionary, {
+            localeFallback: { a: "b", b: "a" },
+          })
+      ).toThrow("[i18n] Circular locale fallback detected");
+    });
+  });
+});

package/src/IcuTranslationProviderSingle.ts

@@ -0,0 +1,155 @@
+import { IntlMessageFormat } from "intl-messageformat";
+import { cloneAndFreeze } from "./deep-freeze.js";
+import {
+  formatLocaleFallbackChain,
+  resolveLocaleTemplate,
+  validateLocaleFallback,
+} from "./resolve-locale.js";
+import type {
+  IcuTranslationProviderOptions,
+  KeyDictionary,
+  LocaleFallbackMap,
+  LocaleOfSingle,
+  SingleCompiledCache,
+} from "./types.js";
+
+export interface TranslationProviderSingleForLocale<
+  Schema extends KeyDictionary,
+  Params extends { [K in keyof Schema]: unknown },
+  Locale extends string,
+> {
+  readonly locale: Locale;
+  get<K extends keyof Schema & string>(
+    key: K,
+    ...params: Params[K] extends never ? [] : [params: Params[K]]
+  ): string;
+}
+
+export interface TranslationProviderSingle<
+  Schema extends KeyDictionary,
+  Params extends { [K in keyof Schema]: unknown },
+  RequestLocales extends string = LocaleOfSingle<Schema>,
+> {
+  get<K extends keyof Schema & string>(
+    key: K,
+    locale: RequestLocales,
+    ...params: Params[K] extends never ? [] : [params: Params[K]]
+  ): string;
+  forLocale<Locale extends RequestLocales>(
+    locale: Locale
+  ): TranslationProviderSingleForLocale<Schema, Params, Locale>;
+  getAll(): Schema;
+  setAll(values: Schema): void;
+}
+
+export class IcuTranslationProviderSingleForLocale<
+  Schema extends KeyDictionary,
+  Params extends { [K in keyof Schema]: unknown },
+  RequestLocales extends string,
+  Locale extends RequestLocales,
+  Fallback extends LocaleFallbackMap | undefined,
+> implements TranslationProviderSingleForLocale<Schema, Params, Locale> {
+  constructor(
+    private readonly provider: IcuTranslationProviderSingle<
+      Schema,
+      Params,
+      RequestLocales,
+      Fallback
+    >,
+    readonly locale: Locale
+  ) {}
+
+  get<K extends keyof Schema & string>(
+    key: K,
+    ...args: Params[K] extends never ? [] : [params: Params[K]]
+  ): string {
+    return (
+      this.provider.get as (
+        key: K,
+        locale: Locale,
+        ...params: Params[K] extends never ? [] : [params: Params[K]]
+      ) => string
+    )(key, this.locale, ...args);
+  }
+}
+
+export class IcuTranslationProviderSingle<
+  Schema extends KeyDictionary,
+  Params extends { [K in keyof Schema]: unknown },
+  RequestLocales extends string = LocaleOfSingle<Schema>,
+  Fallback extends LocaleFallbackMap | undefined = undefined,
+> implements TranslationProviderSingle<Schema, Params, RequestLocales> {
+  private dictionary: Schema;
+  private compiledCache: SingleCompiledCache = {};
+  private readonly localeFallback?: Fallback;
+
+  constructor(dictionary: Schema, options?: IcuTranslationProviderOptions<Fallback>) {
+    this.dictionary = structuredClone(dictionary);
+    if (options?.localeFallback) {
+      validateLocaleFallback(options.localeFallback);
+      this.localeFallback = options.localeFallback;
+    }
+  }
+
+  get<K extends keyof Schema & string>(
+    key: K,
+    locale: RequestLocales,
+    ...args: Params[K] extends never ? [] : [params: Params[K]]
+  ): string {
+    const params = args[0] as Record<string, unknown> | undefined;
+    const resolved = resolveLocaleTemplate(this.dictionary[key], locale, this.localeFallback);
+
+    if (!resolved) {
+      const chain = formatLocaleFallbackChain(locale, this.localeFallback);
+      throw new Error(
+        `[i18n] Missing key or locale: "${String(key)}" [${locale}] (fallback chain: ${chain})`
+      );
+    }
+
+    const { template, resolvedLocale } = resolved;
+
+    if (!this.compiledCache[resolvedLocale]) {
+      this.compiledCache[resolvedLocale] = {};
+    }
+
+    const cacheKey = String(key);
+
+    if (!this.compiledCache[resolvedLocale][cacheKey]) {
+      try {
+        this.compiledCache[resolvedLocale][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 key "${String(key)}" [${resolvedLocale}]: ${message}`
+        );
+      }
+    }
+
+    try {
+      return this.compiledCache[resolvedLocale][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 key "${String(key)}" [${resolvedLocale}]: ${message}`
+      );
+    }
+  }
+
+  forLocale<Locale extends RequestLocales>(
+    locale: Locale
+  ): IcuTranslationProviderSingleForLocale<Schema, Params, RequestLocales, Locale, Fallback> {
+    return new IcuTranslationProviderSingleForLocale(this, locale);
+  }
+
+  getAll(): Schema {
+    return cloneAndFreeze(this.dictionary);
+  }
+
+  setAll(values: Schema): void {
+    this.dictionary = structuredClone(values);
+    this.compiledCache = {};
+  }
+}

package/src/codegen/config.ts

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import type { CodegenConfig, LoadOnInitResolution, NamespaceEntry } from "./types.js";
+import { fail } from "./paths.js";
+
+export function loadConfig(configPath: string): CodegenConfig {
+  const raw = fs.readFileSync(configPath, "utf8");
+  return JSON.parse(raw) as CodegenConfig;
+}
+
+export function resolveNamespaces(config: CodegenConfig): NamespaceEntry[] {
+  const hasDictionary = Boolean(config.dictionary);
+  const hasNamespaces = Boolean(config.namespaces);
+
+  if (hasDictionary === hasNamespaces) {
+    throw new Error(
+      '[Codegen Error] Config must specify exactly one of "dictionary" or "namespaces".'
+    );
+  }
+
+  if (hasDictionary) {
+    return [
+      {
+        namespace: config.defaultNamespace ?? "default",
+        filePath: config.dictionary!,
+      },
+    ];
+  }
+
+  return Object.entries(config.namespaces!).map(([namespace, filePath]) => ({
+    namespace,
+    filePath,
+  }));
+}
+
+export function resolveLoadOnInit(
+  config: CodegenConfig,
+  entries: NamespaceEntry[],
+  isSingle: boolean
+): LoadOnInitResolution {
+  if (isSingle) {
+    if (config.loadOnInit) {
+      fail('[Codegen Error] "loadOnInit" is only supported in multi mode (namespaces config).');
+    }
+    const all = new Set(entries.map((entry) => entry.namespace));
+    return { loadOnInitSet: all, lazyEntries: [], hasLazy: false };
+  }
+
+  const allNamespaces = new Set(entries.map((entry) => entry.namespace));
+  const loadOnInitSet = config.loadOnInit
+    ? new Set(config.loadOnInit)
+    : new Set(entries.map((entry) => entry.namespace));
+
+  for (const namespace of loadOnInitSet) {
+    if (!allNamespaces.has(namespace)) {
+      fail(
+        `[Codegen Error] loadOnInit: namespace "${namespace}" is not defined in namespaces config.`
+      );
+    }
+  }
+
+  const lazyEntries = entries.filter((entry) => !loadOnInitSet.has(entry.namespace));
+  return { loadOnInitSet, lazyEntries, hasLazy: lazyEntries.length > 0 };
+}

package/src/codegen/emit/dictionary-file.ts

@@ -0,0 +1,73 @@
+import path from "node:path";
+import {
+  GENERATED_FILE_BANNER,
+  toImportIdentifier,
+  toImportPath,
+  toModuleBasename,
+} from "../paths.js";
+import type { NamespaceEntry } from "../types.js";
+
+export interface DictionaryFileOptions {
+  isSingle: boolean;
+  hasLazy: boolean;
+  entries: NamespaceEntry[];
+  eagerEntries: NamespaceEntry[];
+  projectRoot: string;
+  dictionaryOutputPath: string;
+  typesOutputPath: string;
+  schemaTypeName: string;
+}
+
+export function formatDictionaryFile(options: DictionaryFileOptions): string {
+  const {
+    isSingle,
+    hasLazy,
+    entries,
+    eagerEntries,
+    projectRoot,
+    dictionaryOutputPath,
+    typesOutputPath,
+    schemaTypeName,
+  } = options;
+
+  const typesModule = toModuleBasename(typesOutputPath);
+
+  if (isSingle) {
+    const entry = entries[0]!;
+    const importPath = toImportPath(
+      dictionaryOutputPath,
+      path.resolve(projectRoot, entry.filePath)
+    );
+    const importId = toImportIdentifier(entry.namespace);
+
+    return (
+      `${GENERATED_FILE_BANNER}` +
+      `import ${importId} from '${importPath}.json';\n` +
+      `import type { ${schemaTypeName} } from './${typesModule}.js';\n\n` +
+      `export const dictionary: ${schemaTypeName} = ${importId};\n`
+    );
+  }
+
+  const dictionaryTypeName = hasLazy ? "InitialSchema" : schemaTypeName;
+
+  const imports = eagerEntries
+    .map((entry) => {
+      const importPath = toImportPath(
+        dictionaryOutputPath,
+        path.resolve(projectRoot, entry.filePath)
+      );
+      return `import ${toImportIdentifier(entry.namespace)} from '${importPath}.json';`;
+    })
+    .join("\n");
+
+  const objectEntries = eagerEntries
+    .map((entry) => `  ${entry.namespace}: ${toImportIdentifier(entry.namespace)},`)
+    .join("\n");
+
+  return (
+    `${GENERATED_FILE_BANNER}` +
+    `${imports}\n` +
+    `import type { ${dictionaryTypeName} } from './${typesModule}.js';\n\n` +
+    `export const dictionary: ${dictionaryTypeName} = {\n${objectEntries}\n};\n`
+  );
+}