@xndrjs/i18n 0.8.0 → 0.8.2-alpha.0

package/src/index.ts

@@ -1,58 +0,0 @@
-export type {
-  DeliveryArtifactsMap,
-  LocalesForDeliveryArea,
-  LocalesForDeliveryAreaOrAll,
-} from "./builder-types.js";
-
-export type { I18nEngineMulti, I18nEngineMultiImpl } from "./engine.js";
-
-export type {
-  I18nHandle,
-  I18nHandleOptions,
-  LoadNamespacesInput,
-  NamespaceLoader,
-  PartitionForLocale,
-  PartitionedLoader,
-  ScopeForLocale,
-} from "./builder.js";
-export { createI18nHandle, invokeNamespaceLoader } from "./builder.js";
-
-export type { BuilderResourceEntry } from "./builder-load-registry.js";
-export type { I18nCreateInput, I18nSerializedState } from "./serialized-state.js";
-export { normalizeI18nCreateInput } from "./serialized-state.js";
-
-export { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
-
-export type { I18nScopeMulti, I18nScopeMultiForLocale } from "./scope-multi.js";
-
-export type {
-  MultiParams,
-  NamespaceBoundTranslateFn,
-  ParamsForNamespaces,
-  SchemaForNamespaces,
-} from "./scope-types.js";
-
-export type {
-  IcuTranslationProviderOptions,
-  KeyDictionary,
-  LocaleDictionary,
-  LocaleFallbackMap,
-  LocaleOfKeys,
-  LocaleOfMulti,
-  MissingTranslationContext,
-  MultiDictionary,
-  PartialKeyDictionary,
-  PartialMultiDictionary,
-  OnMissingTranslation,
-} from "./types.js";
-
-export {
-  formatLocaleFallbackChain,
-  resolveLocaleTemplate,
-  validateLocaleFallback,
-} from "./resolve-locale.js";
-export type { ResolvedLocaleTemplate } from "./resolve-locale.js";
-
-export { mergeDictionaryLocalesCore, mergeNamespaceLocalesCore } from "./project-locales.js";
-
-export type { FetchArtifact, DeliveryResourceId } from "./fetch-artifact.js";

package/src/project-locales.test.ts

@@ -1,280 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  mergeDictionaryLocalesCore,
-  mergeNamespaceLocalesCore,
-  projectDictionaryForDeliveryAreaCore,
-  projectDictionaryLocalesCore,
-  projectNamespaceForDeliveryAreaCore,
-  projectNamespaceLocalesCore,
-} from "./project-locales.js";
-
-describe("projectNamespaceLocalesCore", () => {
-  const dictionary = {
-    login_button: { en: "Login", it: "Accedi" },
-    welcome: { en: "Welcome {name}!", it: "Benvenuto {name}!" },
-    empty_label: { en: "" },
-  };
-
-  const fallback = {
-    en: null,
-    "de-DE": "en",
-    "de-CH": "de-DE",
-    it: "en",
-  } as const;
-
-  it("keeps only the requested locales with direct templates", () => {
-    expect(projectNamespaceLocalesCore(dictionary, ["en", "it"])).toEqual({
-      login_button: { en: "Login", it: "Accedi" },
-      welcome: { en: "Welcome {name}!", it: "Benvenuto {name}!" },
-      empty_label: { en: "" },
-    });
-  });
-
-  it("drops locales not listed in the projection", () => {
-    expect(projectNamespaceLocalesCore(dictionary, ["en"])).toEqual({
-      login_button: { en: "Login" },
-      welcome: { en: "Welcome {name}!" },
-      empty_label: { en: "" },
-    });
-  });
-
-  it("resolves fallback templates for missing direct locale entries", () => {
-    expect(projectNamespaceLocalesCore(dictionary, ["de-CH"], fallback)).toEqual({
-      login_button: { "de-CH": "Login" },
-      welcome: { "de-CH": "Welcome {name}!" },
-      empty_label: { "de-CH": "" },
-    });
-  });
-
-  it("projects multiple locales with mixed direct and fallback resolution", () => {
-    expect(projectNamespaceLocalesCore(dictionary, ["it", "de-CH"], fallback)).toEqual({
-      login_button: { it: "Accedi", "de-CH": "Login" },
-      welcome: { it: "Benvenuto {name}!", "de-CH": "Welcome {name}!" },
-      empty_label: { it: "", "de-CH": "" },
-    });
-  });
-
-  it("omits a target locale when fallback cannot resolve a template", () => {
-    const partial = {
-      login_button: { it: "Accedi" },
-    };
-
-    expect(projectNamespaceLocalesCore(partial, ["en", "it"], fallback)).toEqual({
-      login_button: { it: "Accedi" },
-    });
-  });
-
-  it("deduplicates locales in the projection list", () => {
-    expect(projectNamespaceLocalesCore(dictionary, ["en", "en"])).toEqual({
-      login_button: { en: "Login" },
-      welcome: { en: "Welcome {name}!" },
-      empty_label: { en: "" },
-    });
-  });
-});
-
-describe("projectNamespaceForDeliveryAreaCore", () => {
-  const namespace = {
-    some_key: { it: "Ciao", "it-CH": "Ciao CH", fr: "Hallo", "en-US": "Hello" },
-    some_other_key: { "en-US": "Computer", fr: "Ordinateur" },
-  };
-
-  const localeFallback = {
-    "en-US": null,
-    it: "en-US",
-    "it-CH": "it",
-    fr: null,
-  } as const;
-
-  it("projects eu area with fallback resolution for full locales", () => {
-    expect(
-      projectNamespaceForDeliveryAreaCore(namespace, ["it", "fr", "it-CH"], localeFallback)
-    ).toEqual({
-      some_key: { it: "Ciao", fr: "Hallo", "it-CH": "Ciao CH" },
-      // it-CH is preserve (fallback it is in the area): copied only when present in the
-      // canonical dict; "it" is full (fallback en-US is outside the area) and resolves here.
-      some_other_key: { it: "Computer", fr: "Ordinateur" },
-    });
-  });
-
-  it("projects us area with single full locale", () => {
-    expect(projectNamespaceForDeliveryAreaCore(namespace, ["en-US"], localeFallback)).toEqual({
-      some_key: { "en-US": "Hello" },
-      some_other_key: { "en-US": "Computer" },
-    });
-  });
-
-  it("preserves canonical entries for in-area fallback locales without resolving", () => {
-    const withInAreaFallback = {
-      some_key: { it: "Ciao", "it-CH": "Ciao CH", fr: "Hallo", "en-US": "Hello" },
-      some_other_key: {
-        it: "Italiano",
-        "it-CH": "Svizzero",
-        "en-US": "Computer",
-        fr: "Ordinateur",
-      },
-    };
-
-    expect(
-      projectNamespaceForDeliveryAreaCore(
-        withInAreaFallback,
-        ["it", "it-CH", "en-US", "fr"],
-        localeFallback
-      )
-    ).toEqual({
-      some_key: { it: "Ciao", "it-CH": "Ciao CH", "en-US": "Hello", fr: "Hallo" },
-      some_other_key: {
-        it: "Italiano",
-        "it-CH": "Svizzero",
-        "en-US": "Computer",
-        fr: "Ordinateur",
-      },
-    });
-  });
-});
-
-describe("projectDictionaryForDeliveryAreaCore", () => {
-  const localeFallback = {
-    "en-US": null,
-    it: "en-US",
-    "it-CH": "it",
-    fr: null,
-  } as const;
-
-  it("projects each namespace independently for a multi-namespace dictionary", () => {
-    const dictionary = {
-      default: {
-        some_key: { it: "Ciao", "it-CH": "Ciao CH", fr: "Hallo", "en-US": "Hello" },
-        some_other_key: { "en-US": "Computer", fr: "Ordinateur" },
-      },
-      billing: {
-        invoice_summary: {
-          it: "{count} fatture",
-          "en-US": "{count} invoices",
-          fr: "{count} factures",
-        },
-      },
-    };
-
-    expect(
-      projectDictionaryForDeliveryAreaCore(dictionary, ["it", "fr", "it-CH"], localeFallback)
-    ).toEqual({
-      default: {
-        some_key: { it: "Ciao", fr: "Hallo", "it-CH": "Ciao CH" },
-        some_other_key: { it: "Computer", fr: "Ordinateur" },
-      },
-      billing: {
-        invoice_summary: { it: "{count} fatture", fr: "{count} factures" },
-      },
-    });
-  });
-
-  it("matches projectNamespaceForDeliveryAreaCore applied per namespace", () => {
-    const dictionary = {
-      default: {
-        some_key: { it: "Ciao", "en-US": "Hello" },
-      },
-      billing: {
-        invoice_summary: { it: "{count} fatture", "en-US": "{count} invoices" },
-      },
-    };
-    const areaLocales = ["en-US"] as const;
-
-    expect(projectDictionaryForDeliveryAreaCore(dictionary, areaLocales, localeFallback)).toEqual({
-      default: projectNamespaceForDeliveryAreaCore(dictionary.default, areaLocales, localeFallback),
-      billing: projectNamespaceForDeliveryAreaCore(dictionary.billing, areaLocales, localeFallback),
-    });
-  });
-});
-
-describe("projectDictionaryLocalesCore", () => {
-  it("projects each namespace independently", () => {
-    const dictionary = {
-      default: {
-        login_button: { en: "Login", it: "Accedi" },
-      },
-      billing: {
-        invoice_summary: { en: "{count} invoices", it: "{count} fatture" },
-      },
-    };
-
-    expect(projectDictionaryLocalesCore(dictionary, ["en"])).toEqual({
-      default: { login_button: { en: "Login" } },
-      billing: { invoice_summary: { en: "{count} invoices" } },
-    });
-  });
-});
-
-describe("mergeNamespaceLocalesCore", () => {
-  type TestDictionary = {
-    welcome: Partial<Record<"en" | "it", string>>;
-    login_button: Partial<Record<"en" | "it", string>>;
-  };
-
-  it("merges locale maps per key without dropping existing locales", () => {
-    const existing: TestDictionary = {
-      welcome: { en: "Welcome {name}!" },
-      login_button: { en: "Login", it: "Accedi" },
-    };
-    const incoming = {
-      welcome: { it: "Benvenuto {name}!" },
-    };
-
-    expect(mergeNamespaceLocalesCore(existing, incoming)).toEqual({
-      welcome: { en: "Welcome {name}!", it: "Benvenuto {name}!" },
-      login_button: { en: "Login", it: "Accedi" },
-    });
-  });
-
-  it("overwrites the same locale when incoming provides a new template", () => {
-    const existing = {
-      welcome: { en: "Welcome {name}!" },
-    };
-    const incoming = {
-      welcome: { en: "Hello {name}!" },
-    };
-
-    expect(mergeNamespaceLocalesCore(existing, incoming)).toEqual({
-      welcome: { en: "Hello {name}!" },
-    });
-  });
-});
-
-describe("mergeDictionaryLocalesCore", () => {
-  type TestMultiDictionary = {
-    default: {
-      welcome: Partial<Record<"en" | "it", string>>;
-    };
-    billing: {
-      invoice_summary: Partial<Record<"en" | "it", string>>;
-    };
-  };
-
-  it("merges each namespace without dropping existing locales", () => {
-    const existing: TestMultiDictionary = {
-      default: {
-        welcome: { en: "Welcome {name}!" },
-      },
-      billing: {
-        invoice_summary: { en: "{count} invoices" },
-      },
-    };
-    const incoming = {
-      default: {
-        welcome: { it: "Benvenuto {name}!" },
-      },
-      billing: {
-        invoice_summary: { it: "{count} fatture" },
-      },
-    };
-
-    expect(mergeDictionaryLocalesCore(existing, incoming)).toEqual({
-      default: {
-        welcome: { en: "Welcome {name}!", it: "Benvenuto {name}!" },
-      },
-      billing: {
-        invoice_summary: { en: "{count} invoices", it: "{count} fatture" },
-      },
-    });
-  });
-});

package/src/project-locales.ts

@@ -1,211 +0,0 @@
-import { resolveLocaleTemplate } from "./resolve-locale.js";
-import type {
-  KeyDictionary,
-  LocaleFallbackMap,
-  LocaleOfMulti,
-  LocaleOfKeys,
-  MultiDictionary,
-  PartialKeyDictionary,
-  PartialMultiDictionary,
-} from "./types.js";
-
-function classifyAreaLocales(
-  areaLocales: readonly string[],
-  localeFallback?: LocaleFallbackMap
-): { full: string[]; preserve: string[] } {
-  const areaSet = new Set(areaLocales);
-  const full: string[] = [];
-  const preserve: string[] = [];
-
-  for (const locale of areaLocales) {
-    const fallback = localeFallback?.[locale];
-    if (fallback !== null && fallback !== undefined && areaSet.has(fallback)) {
-      preserve.push(locale);
-    } else {
-      full.push(locale);
-    }
-  }
-
-  return { full, preserve };
-}
-
-function projectKeyDictionary<T extends KeyDictionary>(
-  dictionary: T,
-  locales: readonly string[],
-  localeFallback?: LocaleFallbackMap
-): T {
-  const targetLocales = [...new Set(locales)];
-  const result = {} as T;
-
-  for (const [key, localesByKey] of Object.entries(dictionary)) {
-    const projected: Record<string, string> = {};
-
-    for (const locale of targetLocales) {
-      const resolved = resolveLocaleTemplate(localesByKey, locale, localeFallback);
-      if (resolved !== undefined) {
-        projected[locale] = resolved.template;
-      }
-    }
-
-    if (Object.keys(projected).length > 0) {
-      result[key as keyof T] = projected as T[keyof T];
-    }
-  }
-
-  return result;
-}
-
-/**
- * Builds a namespace dictionary that contains only the requested locales.
- * For each key and target locale, copies the direct template when present;
- * otherwise resolves through `localeFallback` (same rules as `.get()` at runtime).
- */
-export function projectNamespaceLocalesCore<T extends KeyDictionary>(
-  dictionary: T,
-  locales: readonly string[],
-  localeFallback?: LocaleFallbackMap
-): T {
-  return projectKeyDictionary(dictionary, locales, localeFallback);
-}
-
-/**
- * Projects a single namespace for a custom delivery area.
- * Full locales resolve through `localeFallback` (e.g. external chains like `it → en-US`);
- * preserve locales copy only their direct canonical entry when present.
- */
-export function projectNamespaceForDeliveryAreaCore<T extends KeyDictionary>(
-  dictionary: T,
-  areaLocales: readonly string[],
-  localeFallback?: LocaleFallbackMap
-): T {
-  const { full, preserve } = classifyAreaLocales(areaLocales, localeFallback);
-  const fullProjection =
-    full.length > 0 ? projectKeyDictionary(dictionary, full, localeFallback) : undefined;
-  const result = {} as T;
-
-  for (const [key, localesByKey] of Object.entries(dictionary)) {
-    const projected: Record<string, string> = {};
-
-    if (fullProjection !== undefined) {
-      const fullEntry = fullProjection[key as keyof T];
-      if (fullEntry !== undefined) {
-        Object.assign(projected, fullEntry);
-      }
-    }
-
-    for (const locale of preserve) {
-      const template = localesByKey[locale];
-      if (template !== undefined) {
-        projected[locale] = template;
-      }
-    }
-
-    if (Object.keys(projected).length > 0) {
-      result[key as keyof T] = projected as T[keyof T];
-    }
-  }
-
-  return result;
-}
-
-/**
- * Projects a multi-namespace dictionary for a custom delivery area.
- * Each namespace uses the same delivery-area rules as `projectNamespaceForDeliveryAreaCore`.
- */
-export function projectDictionaryForDeliveryAreaCore<T extends MultiDictionary>(
-  dictionary: T,
-  areaLocales: readonly string[],
-  localeFallback?: LocaleFallbackMap
-): T {
-  const result = {} as T;
-
-  for (const namespace of Object.keys(dictionary) as (keyof T & string)[]) {
-    const namespaceDictionary = dictionary[namespace];
-    if (namespaceDictionary === undefined) {
-      continue;
-    }
-
-    result[namespace] = projectNamespaceForDeliveryAreaCore(
-      namespaceDictionary,
-      areaLocales,
-      localeFallback
-    ) as T[typeof namespace];
-  }
-
-  return result;
-}
-
-/**
- * Projects every namespace in a multi-namespace dictionary.
- */
-export function projectDictionaryLocalesCore<T extends MultiDictionary>(
-  dictionary: T,
-  locales: readonly string[],
-  localeFallback?: LocaleFallbackMap
-): T {
-  const result = {} as T;
-
-  for (const namespace of Object.keys(dictionary) as (keyof T & string)[]) {
-    const namespaceDictionary = dictionary[namespace];
-    if (namespaceDictionary === undefined) {
-      continue;
-    }
-
-    result[namespace] = projectKeyDictionary(
-      namespaceDictionary,
-      locales,
-      localeFallback
-    ) as T[typeof namespace];
-  }
-
-  return result;
-}
-
-/**
- * Merges locale entries per translation key without dropping keys or locales
- * already present in `existing`. Incoming locales overwrite the same locale on conflict.
- */
-export function mergeNamespaceLocalesCore<
-  T extends KeyDictionary,
-  Locales extends string = LocaleOfKeys<T>,
->(existing: T, incoming: PartialKeyDictionary<T, Locales>): T {
-  const merged = structuredClone(existing);
-
-  for (const [key, incomingLocales] of Object.entries(incoming)) {
-    if (incomingLocales === undefined || typeof incomingLocales !== "object") {
-      continue;
-    }
-
-    merged[key as keyof T] = {
-      ...(merged[key as keyof T] ?? {}),
-      ...incomingLocales,
-    } as T[keyof T];
-  }
-
-  return merged;
-}
-
-/**
- * Merges locale entries per key in every namespace present in `incoming`.
- * Namespaces and keys not in `incoming` are preserved from `existing`.
- */
-export function mergeDictionaryLocalesCore<
-  T extends MultiDictionary,
-  Locales extends string = LocaleOfMulti<T>,
->(existing: T, incoming: PartialMultiDictionary<T, Locales>): T {
-  const merged = structuredClone(existing) as T;
-
-  for (const namespace of Object.keys(incoming) as (keyof T & string)[]) {
-    const incomingNamespace = incoming[namespace];
-    if (incomingNamespace === undefined) {
-      continue;
-    }
-
-    merged[namespace] = mergeNamespaceLocalesCore(
-      (merged[namespace] ?? {}) as T[typeof namespace],
-      incomingNamespace as T[typeof namespace]
-    ) as T[typeof namespace];
-  }
-
-  return merged;
-}

package/src/resolve-locale.test.ts

@@ -1,91 +0,0 @@
-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");
-  });
-});