@xndrjs/i18n 0.2.0-alpha.0

package/src/IcuTranslationProviderMulti.test.ts

@@ -0,0 +1,290 @@
+import { describe, expect, it } from "vitest";
+import { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
+import type { LocaleOfMulti } from "./types.js";
+
+type TestSchema = {
+  default: {
+    login_button: { en: string; it: string };
+    welcome: { en: string };
+    dashboard_status: { en: string; it: string };
+    inbox_owner: { en: string; it: string };
+    ranking_position: { en: string; it: string };
+  };
+  billing: {
+    invoice_summary: { en: string; it: string };
+    account_balance: { en: string; it: string };
+    appointment_summary: { en: string; it: string };
+    empty_label: { en: string };
+  };
+};
+
+type TestParams = {
+  default: {
+    login_button: never;
+    welcome: { name: string };
+    dashboard_status: { msgCount: number; chatCount: number };
+    inbox_owner: { gender: string; name: string };
+    ranking_position: { position: number };
+  };
+  billing: {
+    invoice_summary: { count: number; name: string };
+    account_balance: { amount: number };
+    appointment_summary: { dueDate: Date | number; startTime: Date | number };
+    empty_label: never;
+  };
+};
+
+const dictionary: TestSchema = {
+  default: {
+    login_button: { en: "Login", it: "Accedi" },
+    welcome: { en: "Welcome {name}!" },
+    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, female {{name} gestisce la sua casella} male {{name} gestisce la sua casella} 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",
+    },
+  },
+  billing: {
+    invoice_summary: {
+      en: "You have {count, plural, one {1 invoice} other {{count} invoices}} for {name}",
+      it: "Hai {count, plural, one {1 fattura} other {{count} fatture}} per {name}",
+    },
+    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}",
+    },
+    empty_label: { en: "" },
+  },
+};
+
+describe("IcuTranslationProviderMulti", () => {
+  const provider = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary);
+
+  it("resolves translations by namespace and key", () => {
+    expect(provider.get("default", "login_button", "it")).toBe("Accedi");
+    expect(provider.get("default", "welcome", "en", { name: "Ada" })).toBe("Welcome Ada!");
+  });
+
+  it("formats ICU plurals with multiple parameters", () => {
+    expect(provider.get("billing", "invoice_summary", "en", { count: 1, name: "Ada" })).toBe(
+      "You have 1 invoice for Ada"
+    );
+    expect(provider.get("billing", "invoice_summary", "en", { count: 3, name: "Ada" })).toBe(
+      "You have 3 invoices for Ada"
+    );
+    expect(provider.get("billing", "invoice_summary", "it", { count: 1, name: "Ada" })).toBe(
+      "Hai 1 fattura per Ada"
+    );
+    expect(provider.get("billing", "invoice_summary", "it", { count: 3, name: "Ada" })).toBe(
+      "Hai 3 fatture per Ada"
+    );
+  });
+
+  it("formats nested numeric plurals with double-brace references", () => {
+    expect(provider.get("default", "dashboard_status", "en", { msgCount: 1, chatCount: 1 })).toBe(
+      "You have 1 message in one chat"
+    );
+    expect(provider.get("default", "dashboard_status", "en", { msgCount: 3, chatCount: 2 })).toBe(
+      "You have 3 messages in 2 chats"
+    );
+    expect(provider.get("default", "dashboard_status", "it", { msgCount: 1, chatCount: 1 })).toBe(
+      "Hai 1 messaggio in una chat"
+    );
+    expect(provider.get("default", "dashboard_status", "it", { msgCount: 3, chatCount: 2 })).toBe(
+      "Hai 3 messaggi in 2 chat"
+    );
+  });
+
+  it("formats select and selectordinal ICU variants", () => {
+    expect(provider.get("default", "inbox_owner", "en", { gender: "male", name: "Linus" })).toBe(
+      "Linus owns his inbox"
+    );
+    expect(provider.get("default", "ranking_position", "en", { position: 3 })).toBe(
+      "You finished 3rd"
+    );
+  });
+
+  it("formats number, date, and time ICU variants", () => {
+    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("billing", "account_balance", "en", { amount })).toBe(
+      `Balance: ${expectedAmount}`
+    );
+    expect(
+      provider.get("billing", "appointment_summary", "en", {
+        dueDate: when,
+        startTime: when,
+      })
+    ).toBe(`Due ${expectedDate} at ${expectedTime}`);
+  });
+
+  it("treats an empty string template as valid", () => {
+    expect(provider.get("billing", "empty_label", "en")).toBe("");
+  });
+
+  it("tracks loaded namespaces with hasNamespace", () => {
+    const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({
+      default: dictionary.default,
+    });
+
+    expect(partial.hasNamespace("default")).toBe(true);
+    expect(partial.hasNamespace("billing")).toBe(false);
+  });
+
+  it("throws when getting from an unloaded namespace", () => {
+    const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({
+      default: dictionary.default,
+    });
+
+    expect(() =>
+      partial.get("billing", "invoice_summary", "en", { count: 1, name: "Ada" })
+    ).toThrow(
+      '[i18n] Namespace not loaded: "billing". Call ensureNamespacesLoaded(i18n, ["billing"]) first.'
+    );
+  });
+
+  it("supports partial initialization", () => {
+    const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({
+      default: dictionary.default,
+    });
+
+    expect(partial.get("default", "login_button", "en")).toBe("Login");
+  });
+
+  it("throws when namespace, key, or locale is missing", () => {
+    expect(() =>
+      provider.get("default", "login_button", "fr" as unknown as LocaleOfMulti<TestSchema>)
+    ).toThrow(
+      '[i18n] Missing key or locale: namespace "default", key "login_button" [fr] (fallback chain: fr)'
+    );
+    expect(() => provider.get("billing", "login_button" as "empty_label", "en")).toThrow(
+      '[i18n] Missing key or locale: namespace "billing", key "login_button" [en] (fallback chain: en)'
+    );
+  });
+
+  it("throws when required parameters are missing", () => {
+    expect(() => provider.get("billing", "invoice_summary", "en", { count: 1 } as never)).toThrow(
+      "[i18n Formatting Error]"
+    );
+  });
+
+  it("patches a single namespace with setNamespace and invalidates its cache", () => {
+    const local = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary);
+    expect(local.get("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
+      "You have 2 invoices for Bob"
+    );
+
+    local.setNamespace("billing", {
+      ...dictionary.billing,
+      invoice_summary: {
+        en: "{count, plural, one {1 bill} other {{count} bills}}",
+        it: dictionary.billing.invoice_summary.it,
+      },
+    });
+
+    expect(local.get("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
+      "2 bills"
+    );
+    expect(local.get("default", "login_button", "en")).toBe("Login");
+  });
+
+  it("replaces the full dictionary on setAll", () => {
+    const local = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary);
+
+    local.setAll({
+      ...dictionary,
+      default: {
+        ...dictionary.default,
+        login_button: { en: "Sign in", it: "Entra" },
+      },
+    });
+
+    expect(local.get("default", "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().default)).toBe(true);
+  });
+
+  it("does not mutate the provider when getAll snapshot is modified", () => {
+    const snapshot = provider.getAll();
+    expect(() => {
+      snapshot.default.login_button.en = "Hacked";
+    }).toThrow(TypeError);
+    expect(provider.get("default", "login_button", "en")).toBe("Login");
+  });
+
+  describe("forLocale", () => {
+    it("binds a locale so get() no longer requires it", () => {
+      const it = provider.forLocale("it");
+
+      expect(it.locale).toBe("it");
+      expect(it.get("default", "login_button")).toBe("Accedi");
+      expect(it.get("billing", "invoice_summary", { count: 2, name: "Ada" })).toBe(
+        "Hai 2 fatture per Ada"
+      );
+    });
+  });
+
+  describe("locale fallback", () => {
+    const fallbackMap = {
+      en: null,
+      "de-DE": "en",
+      "de-CH": "de-DE",
+      it: "en",
+    } as const;
+
+    const fallbackProvider = new IcuTranslationProviderMulti<
+      TestSchema,
+      TestParams,
+      keyof typeof fallbackMap | LocaleOfMulti<TestSchema>,
+      typeof fallbackMap
+    >(dictionary, { localeFallback: fallbackMap });
+
+    it("resolves a locale through the fallback chain", () => {
+      expect(fallbackProvider.get("default", "login_button", "de-CH")).toBe("Login");
+    });
+
+    it("throws when the fallback chain cannot resolve a template", () => {
+      const unresolvedFallback = {
+        en: null,
+        "de-CH": "fr",
+        fr: null,
+      } as const;
+      const unresolvedProvider = new IcuTranslationProviderMulti<
+        TestSchema,
+        TestParams,
+        keyof typeof unresolvedFallback | LocaleOfMulti<TestSchema>,
+        typeof unresolvedFallback
+      >(dictionary, { localeFallback: unresolvedFallback });
+
+      expect(() => unresolvedProvider.get("default", "login_button", "de-CH")).toThrow(
+        '[i18n] Missing key or locale: namespace "default", key "login_button" [de-CH] (fallback chain: de-CH → fr)'
+      );
+    });
+  });
+});

package/src/IcuTranslationProviderMulti.ts

@@ -0,0 +1,195 @@
+import { IntlMessageFormat } from "intl-messageformat";
+import { cloneAndFreeze } from "./deep-freeze.js";
+import {
+  formatLocaleFallbackChain,
+  resolveLocaleTemplate,
+  validateLocaleFallback,
+} from "./resolve-locale.js";
+import type {
+  IcuTranslationProviderOptions,
+  LocaleFallbackMap,
+  LocaleOfMulti,
+  MultiCompiledCache,
+  MultiDictionary,
+} from "./types.js";
+
+export interface TranslationProviderMultiForLocale<
+  Schema extends MultiDictionary,
+  Params extends { [NS in keyof Schema]: { [K in keyof Schema[NS]]: unknown } },
+  Locale extends string,
+> {
+  readonly locale: Locale;
+  get<NS extends keyof Schema, K extends keyof Schema[NS] & keyof Params[NS] & string>(
+    namespace: NS,
+    key: K,
+    ...params: Params[NS][K] extends never ? [] : [params: Params[NS][K]]
+  ): string;
+}
+
+export interface TranslationProviderMulti<
+  Schema extends MultiDictionary,
+  Params extends { [NS in keyof Schema]: { [K in keyof Schema[NS]]: unknown } },
+  RequestLocales extends string = LocaleOfMulti<Schema>,
+> {
+  get<NS extends keyof Schema, K extends keyof Schema[NS] & keyof Params[NS] & string>(
+    namespace: NS,
+    key: K,
+    locale: RequestLocales,
+    ...params: Params[NS][K] extends never ? [] : [params: Params[NS][K]]
+  ): string;
+  forLocale<Locale extends RequestLocales>(
+    locale: Locale
+  ): TranslationProviderMultiForLocale<Schema, Params, Locale>;
+  getAll(): Schema;
+  hasNamespace<NS extends keyof Schema & string>(namespace: NS): boolean;
+  setAll(values: Schema): void;
+  setNamespace<NS extends keyof Schema>(namespace: NS, values: Schema[NS]): void;
+}
+
+export class IcuTranslationProviderMultiForLocale<
+  Schema extends MultiDictionary,
+  Params extends { [NS in keyof Schema]: { [K in keyof Schema[NS]]: unknown } },
+  RequestLocales extends string,
+  Locale extends RequestLocales,
+  Fallback extends LocaleFallbackMap | undefined,
+> implements TranslationProviderMultiForLocale<Schema, Params, Locale> {
+  constructor(
+    private readonly provider: IcuTranslationProviderMulti<
+      Schema,
+      Params,
+      RequestLocales,
+      Fallback
+    >,
+    readonly locale: Locale
+  ) {}
+
+  get<NS extends keyof Schema, K extends keyof Schema[NS] & keyof Params[NS] & string>(
+    namespace: NS,
+    key: K,
+    ...args: Params[NS][K] extends never ? [] : [params: Params[NS][K]]
+  ): string {
+    return (
+      this.provider.get as <
+        NS extends keyof Schema,
+        K extends keyof Schema[NS] & keyof Params[NS] & string,
+      >(
+        namespace: NS,
+        key: K,
+        locale: Locale,
+        ...params: Params[NS][K] extends never ? [] : [params: Params[NS][K]]
+      ) => string
+    )(namespace, key, this.locale, ...args);
+  }
+}
+
+export class IcuTranslationProviderMulti<
+  Schema extends MultiDictionary,
+  Params extends { [NS in keyof Schema]: { [K in keyof Schema[NS]]: unknown } },
+  RequestLocales extends string = LocaleOfMulti<Schema>,
+  Fallback extends LocaleFallbackMap | undefined = undefined,
+> implements TranslationProviderMulti<Schema, Params, RequestLocales> {
+  private dictionary: Schema;
+  private compiledCache: MultiCompiledCache = {};
+  private readonly localeFallback?: Fallback;
+  private loadedNamespaces: Set<string>;
+
+  constructor(dictionary: Partial<Schema>, options?: IcuTranslationProviderOptions<Fallback>) {
+    this.dictionary = structuredClone(dictionary) as Schema;
+    this.loadedNamespaces = new Set(Object.keys(dictionary));
+    if (options?.localeFallback) {
+      validateLocaleFallback(options.localeFallback);
+      this.localeFallback = options.localeFallback;
+    }
+  }
+
+  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 {
+    if (!this.loadedNamespaces.has(namespace as string)) {
+      throw new Error(
+        `[i18n] Namespace not loaded: "${String(namespace)}". Call ensureNamespacesLoaded(i18n, ["${String(namespace)}"]) first.`
+      );
+    }
+
+    const params = args[0] as Record<string, unknown> | undefined;
+    const localeByKey = (
+      this.dictionary[namespace as string] as Record<string, Record<string, string>>
+    )?.[key];
+    const resolved = resolveLocaleTemplate(localeByKey, locale, this.localeFallback);
+
+    if (!resolved) {
+      const chain = formatLocaleFallbackChain(locale, this.localeFallback);
+      throw new Error(
+        `[i18n] Missing key or locale: namespace "${String(namespace)}", key "${String(key)}" [${locale}] (fallback chain: ${chain})`
+      );
+    }
+
+    const { template, resolvedLocale } = resolved;
+
+    if (!this.compiledCache[resolvedLocale]) {
+      this.compiledCache[resolvedLocale] = {};
+    }
+
+    if (!this.compiledCache[resolvedLocale][namespace as string]) {
+      this.compiledCache[resolvedLocale][namespace as string] = {};
+    }
+
+    const namespaceCache = this.compiledCache[resolvedLocale][namespace as string]!;
+    const cacheKey = String(key);
+
+    if (!namespaceCache[cacheKey]) {
+      try {
+        namespaceCache[cacheKey] = new IntlMessageFormat(template, resolvedLocale);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(
+          `[i18n ICU Syntax Error] namespace "${String(namespace)}", key "${String(key)}" [${resolvedLocale}]: ${message}`
+        );
+      }
+    }
+
+    try {
+      return namespaceCache[cacheKey].format(params) as string;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `[i18n Formatting Error] namespace "${String(namespace)}", key "${String(key)}" [${resolvedLocale}]: ${message}`
+      );
+    }
+  }
+
+  forLocale<Locale extends RequestLocales>(
+    locale: Locale
+  ): IcuTranslationProviderMultiForLocale<Schema, Params, RequestLocales, Locale, Fallback> {
+    return new IcuTranslationProviderMultiForLocale(this, locale);
+  }
+
+  getAll(): Schema {
+    return cloneAndFreeze(this.dictionary);
+  }
+
+  hasNamespace<NS extends keyof Schema & string>(namespace: NS): boolean {
+    return this.loadedNamespaces.has(namespace);
+  }
+
+  setAll(values: Schema): void {
+    this.dictionary = structuredClone(values);
+    this.compiledCache = {};
+    this.loadedNamespaces = new Set(Object.keys(values));
+  }
+
+  setNamespace<NS extends keyof Schema>(namespace: NS, values: Schema[NS]): void {
+    this.dictionary = {
+      ...this.dictionary,
+      [namespace]: structuredClone(values),
+    };
+    this.loadedNamespaces.add(namespace as string);
+
+    for (const locale of Object.keys(this.compiledCache)) {
+      delete this.compiledCache[locale]?.[namespace as string];
+    }
+  }
+}