@xndrjs/i18n 0.7.0 → 0.8.0

package/src/types.ts

@@ -4,7 +4,8 @@ export type LocaleDictionary = Record<string, string>;
 export type KeyDictionary = Record<string, LocaleDictionary>;
 export type MultiDictionary = Record<string, KeyDictionary>;
 
-export type LocaleOfSingle<Schema extends KeyDictionary> = {
+/** Locales present on any key of a flat (per-namespace) key dictionary. */
+export type LocaleOfKeys<Schema extends KeyDictionary> = {
   [K in keyof Schema]: keyof Schema[K];
 }[keyof Schema] &
   string;
@@ -19,7 +20,7 @@ export type LocaleOfMulti<Schema extends MultiDictionary> = {
 /** Subset of schema keys with any subset of project locales per key — valid input for merge operations. */
 export type PartialKeyDictionary<
   T extends KeyDictionary,
-  Locales extends string = LocaleOfSingle<T>,
+  Locales extends string = LocaleOfKeys<T>,
 > = {
   [K in keyof T]?: Partial<Record<Locales, string>>;
 };
@@ -61,5 +62,4 @@ export type IcuTranslationProviderOptions<
 };
 
 export type LocaleCache = Record<string, IntlMessageFormat>;
-export type SingleCompiledCache = Record<string, LocaleCache>;
 export type MultiCompiledCache = Record<string, Record<string, LocaleCache>>;

package/src/validation/index.ts

@@ -1,3 +1,7 @@
+/**
+ * External payload validation for server-side codegen/ingest (CMS → authoring files).
+ * Not a runtime patch API — validate before writing authoring, then `regenerateNamespaces` / `load()`.
+ */
 import { normalizeDictionaryPartial, normalizeKeyDictionaryPartial } from "./normalize.js";
 import { toDictionary, toNamespaceDictionary } from "./to-dictionary.js";
 import type {

package/src/IcuTranslationProviderSingle.test.ts

@@ -1,177 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { IcuTranslationProviderSingle } from "./IcuTranslationProviderSingle.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 };
-  item_count_zero: { en: string };
-  item_count_exact: { en: 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 };
-  invoice_due_long: { en: string; it: string };
-  discount_rate: { en: string; it: string };
-};
-
-type TestParams = {
-  login_button: never;
-  welcome: { name: string };
-  empty_label: never;
-  broken: { name: string };
-  invoice_count: { count: number };
-  item_count_zero: { count: number };
-  item_count_exact: { 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 };
-  invoice_due_long: { dueDate: Date | number };
-  discount_rate: { rate: 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}}",
-  },
-  item_count_zero: {
-    en: "{count, plural, zero {no items} one {1 item} other {{count} items}}",
-  },
-  item_count_exact: {
-    en: "{count, plural, =5 {five items} one {1 item} other {{count} items}}",
-  },
-  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}",
-  },
-  invoice_due_long: {
-    en: "Payment due on {dueDate, date, ::yMMMMd}",
-    it: "Pagamento entro il {dueDate, date, ::yMMMMd}",
-  },
-  discount_rate: {
-    en: "Save {rate, number, ::percent} today",
-    it: "Risparmia il {rate, number, ::percent} oggi",
-  },
-};
-
-describe("IcuTranslationProviderSingle", () => {
-  const engine = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary);
-
-  it("patches a preloaded key and invalidates cache", () => {
-    const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary);
-    expect(local.toScope().t("login_button", "en")).toBe("Login");
-
-    local.patchKey("login_button", "en", "Sign in");
-
-    expect(local.toScope().t("login_button", "en")).toBe("Sign in");
-    expect(local.toScope().t("login_button", "it")).toBe("Accedi");
-  });
-
-  it("merges locales per key with applyLoadMergeSingle without dropping existing locales", () => {
-    const local = new IcuTranslationProviderSingle<TestSchema, TestParams>({
-      ...dictionary,
-      // @ts-expect-error missing locale
-      welcome: {
-        en: "Welcome {name}!",
-      },
-    });
-
-    local.applyLoadMergeSingle({
-      welcome: {
-        // @ts-expect-error adding locale via merge
-        it: "Benvenuto {name}!",
-      },
-    });
-
-    const view = local.toScope();
-    expect(view.t("welcome", "en", { name: "Ada" })).toBe("Welcome Ada!");
-    expect(view.t("welcome", "it", { name: "Ada" })).toBe("Benvenuto Ada!");
-    expect(view.t("login_button", "en")).toBe("Login");
-  });
-
-  it("throws when patching a key that was not preloaded", () => {
-    const local = new IcuTranslationProviderSingle<TestSchema, TestParams>({
-      login_button: { en: "Login" },
-    } as TestSchema);
-
-    expect(() => local.patchKey("login_button", "it", "Accedi")).toThrow(
-      "[i18n] Key not preloaded: login_button (it)"
-    );
-  });
-
-  it("returns a deep-frozen snapshot from getAll", () => {
-    expect(engine.getAll()).toEqual(dictionary);
-    expect(engine.getAll()).not.toBe(dictionary);
-    expect(Object.isFrozen(engine.getAll())).toBe(true);
-  });
-
-  it("does not mutate the engine when getAll snapshot is modified", () => {
-    const snapshot = engine.getAll();
-    expect(() => {
-      snapshot.welcome.en = "Hacked";
-    }).toThrow(TypeError);
-    expect(engine.toScope().t("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}}",
-      },
-      item_count_zero: dictionary.item_count_zero,
-      item_count_exact: dictionary.item_count_exact,
-      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,
-      invoice_due_long: dictionary.invoice_due_long,
-      discount_rate: dictionary.discount_rate,
-    };
-    const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(external);
-    external.login_button.en = "Sign in";
-    expect(local.toScope().t("login_button", "en")).toBe("Login");
-  });
-
-  describe("locale fallback", () => {
-    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

@@ -1,114 +0,0 @@
-import { cloneAndFreeze } from "./deep-freeze.js";
-import { BuilderLoadRegistry, SINGLE_BUILDER_RESOURCE } from "./builder-load-registry.js";
-import type { I18nEngineSingle } from "./engine.js";
-import { resolveAndFormat } from "./format-core.js";
-import {
-  assertPatchKeySingle,
-  recordPreloadedKeysSingle,
-  seedPreloadedKeysSingle,
-} from "./patch-key.js";
-import { mergeNamespaceLocalesCore } from "./project-locales.js";
-import { validateLocaleFallback } from "./resolve-locale.js";
-import type {
-  IcuTranslationProviderOptions,
-  KeyDictionary,
-  LocaleFallbackMap,
-  LocaleOfSingle,
-  OnMissingTranslation,
-  SingleCompiledCache,
-  PartialKeyDictionary,
-} from "./types.js";
-import { I18nScopeSingleForLocaleImpl, I18nScopeSingleImpl } from "./scope-single.js";
-
-export class IcuTranslationProviderSingle<
-  Schema extends KeyDictionary,
-  Params extends { [K in keyof Schema]: unknown },
-  RequestLocales extends string = LocaleOfSingle<Schema>,
-  Fallback extends LocaleFallbackMap | undefined = undefined,
-> implements I18nEngineSingle<Schema, Params, RequestLocales> {
-  readonly __i18nEngineMode = "single" as const;
-
-  private dictionary: Schema;
-  private compiledCache: SingleCompiledCache = {};
-  private readonly preloadedKeys = new Set<string>();
-  private readonly builderLoadRegistry = new BuilderLoadRegistry();
-  private readonly localeFallback?: Fallback;
-  private readonly onMissing: OnMissingTranslation;
-
-  constructor(dictionary: Schema, options?: IcuTranslationProviderOptions<Fallback>) {
-    this.dictionary = structuredClone(dictionary);
-    seedPreloadedKeysSingle(this.dictionary, this.preloadedKeys);
-    if (options?.localeFallback) {
-      validateLocaleFallback(options.localeFallback);
-      this.localeFallback = options.localeFallback;
-    }
-    this.onMissing = options?.onMissing ?? "throw";
-  }
-
-  getWithLocale(key: string, locale: string, params?: Record<string, unknown>): string {
-    return resolveAndFormat({
-      localeByKey: this.dictionary[key],
-      locale,
-      params,
-      getCache: (resolvedLocale) => {
-        if (!this.compiledCache[resolvedLocale]) {
-          this.compiledCache[resolvedLocale] = {};
-        }
-        return this.compiledCache[resolvedLocale]!;
-      },
-      context: {
-        key,
-        locale,
-        localeFallback: this.localeFallback,
-        onMissing: this.onMissing,
-      },
-    });
-  }
-
-  toScope(): I18nScopeSingleImpl<Schema, Params, RequestLocales, Fallback>;
-  toScope<Locale extends RequestLocales>(options: {
-    locale: Locale;
-  }): I18nScopeSingleForLocaleImpl<Schema, Params, RequestLocales, Locale, Fallback>;
-  toScope<Locale extends RequestLocales>(options?: { locale?: Locale }) {
-    if (options?.locale !== undefined) {
-      return new I18nScopeSingleForLocaleImpl(this, options.locale);
-    }
-    return new I18nScopeSingleImpl(this);
-  }
-
-  getAll(): Schema {
-    return cloneAndFreeze(this.dictionary);
-  }
-
-  hasBuilderResourceLoaded(partition: string | undefined): boolean {
-    return this.builderLoadRegistry.has(SINGLE_BUILDER_RESOURCE, partition);
-  }
-
-  markBuilderResourceLoaded(partition: string | undefined): void {
-    this.builderLoadRegistry.mark(SINGLE_BUILDER_RESOURCE, partition);
-  }
-
-  applyLoadMergeSingle(values: PartialKeyDictionary<Schema, RequestLocales>): void {
-    this.dictionary = mergeNamespaceLocalesCore(this.dictionary, values);
-    recordPreloadedKeysSingle(values, this.preloadedKeys);
-
-    for (const [key, incomingLocales] of Object.entries(values)) {
-      if (incomingLocales === undefined || typeof incomingLocales !== "object") {
-        continue;
-      }
-
-      for (const locale of Object.keys(incomingLocales)) {
-        delete this.compiledCache[locale]?.[key];
-      }
-    }
-  }
-
-  patchKey(key: string, locale: string, template: string): void {
-    assertPatchKeySingle(key, locale, template, this.preloadedKeys, this.dictionary[key]);
-
-    this.dictionary = mergeNamespaceLocalesCore(this.dictionary, {
-      [key]: { [locale]: template },
-    } as PartialKeyDictionary<Schema, RequestLocales>);
-    delete this.compiledCache[locale]?.[key];
-  }
-}