@xndrjs/i18n 0.6.0 → 0.7.0-alpha.0

package/src/engine.ts

@@ -0,0 +1,71 @@
+import type { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
+import type { IcuTranslationProviderSingle } from "./IcuTranslationProviderSingle.js";
+import type {
+  KeyDictionary,
+  LocaleFallbackMap,
+  LocaleOfMulti,
+  LocaleOfSingle,
+  MultiDictionary,
+} from "./types.js";
+import type { I18nScopeMulti, I18nScopeMultiForLocale } from "./scope-multi.js";
+import type { I18nScopeSingle, I18nScopeSingleForLocale } from "./scope-single.js";
+import type { MultiParams, ParamsForNamespaces, SchemaForNamespaces } from "./scope-types.js";
+
+/** Mutable translation engine for a single-namespace dictionary. */
+export interface I18nEngineSingle<
+  Schema extends KeyDictionary,
+  Params extends { [K in keyof Schema]: unknown },
+  RequestLocales extends string = LocaleOfSingle<Schema>,
+> {
+  readonly __i18nEngineMode: "single";
+  getAll(): Schema;
+  toScope(): I18nScopeSingle<Schema, Params, RequestLocales>;
+  toScope<Locale extends RequestLocales>(options: {
+    locale: Locale;
+  }): I18nScopeSingleForLocale<Schema, Params, Locale>;
+}
+
+/** Mutable translation engine for a multi-namespace dictionary. */
+export interface I18nEngineMulti<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string = LocaleOfMulti<Schema>,
+> {
+  readonly __i18nEngineMode: "multi";
+  getAll(): Schema;
+  toScope<NsList extends readonly (keyof Schema & string)[]>(options: {
+    namespaces: NsList;
+  }): I18nScopeMulti<
+    SchemaForNamespaces<Schema, NsList>,
+    ParamsForNamespaces<Schema, Params, NsList>,
+    RequestLocales
+  >;
+  toScope<
+    NsList extends readonly (keyof Schema & string)[],
+    Locale extends RequestLocales,
+  >(options: {
+    namespaces: NsList;
+    locale: Locale;
+  }): I18nScopeMultiForLocale<
+    SchemaForNamespaces<Schema, NsList>,
+    ParamsForNamespaces<Schema, Params, NsList>,
+    RequestLocales,
+    Locale
+  >;
+}
+
+/** Alias for the default single-namespace engine implementation. */
+export type I18nEngineSingleImpl<
+  Schema extends KeyDictionary,
+  Params extends { [K in keyof Schema]: unknown },
+  RequestLocales extends string = LocaleOfSingle<Schema>,
+  Fallback extends LocaleFallbackMap | undefined = undefined,
+> = IcuTranslationProviderSingle<Schema, Params, RequestLocales, Fallback>;
+
+/** Alias for the default multi-namespace engine implementation. */
+export type I18nEngineMultiImpl<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string = LocaleOfMulti<Schema>,
+  Fallback extends LocaleFallbackMap | undefined = undefined,
+> = IcuTranslationProviderMulti<Schema, Params, RequestLocales, Fallback>;

package/src/index.ts

@@ -1,15 +1,51 @@
 export type {
-  TranslationProviderSingle,
-  TranslationProviderSingleForLocale,
-} from "./IcuTranslationProviderSingle.js";
-export { IcuTranslationProviderSingle } from "./IcuTranslationProviderSingle.js";
+  DeliveryArtifactsMap,
+  LocalesForDeliveryArea,
+  LocalesForDeliveryAreaOrAll,
+} from "./builder-types.js";
+
+export type {
+  I18nEngineMulti,
+  I18nEngineMultiImpl,
+  I18nEngineSingle,
+  I18nEngineSingleImpl,
+} from "./engine.js";
 
 export type {
-  TranslationProviderMulti,
-  TranslationProviderMultiForLocale,
-} from "./IcuTranslationProviderMulti.js";
+  CanonicalLoader,
+  I18nBuilderMulti,
+  I18nBuilderMultiForLocale,
+  I18nBuilderMultiInitial,
+  I18nBuilderMultiOptions,
+  I18nBuilderMultiPartitioned,
+  I18nBuilderMultiReady,
+  I18nBuilderSingle,
+  I18nBuilderSingleForLocale,
+  I18nBuilderSingleOptions,
+  NamespaceLoader,
+  PartitionedLoader,
+} from "./builder.js";
+export {
+  createI18nBuilder,
+  createI18nMultiBuilder,
+  createI18nSingleBuilder,
+  invokeNamespaceLoader,
+} from "./builder.js";
+
+export { IcuTranslationProviderSingle } from "./IcuTranslationProviderSingle.js";
+
 export { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
 
+export type { I18nScopeMulti, I18nScopeMultiForLocale } from "./scope-multi.js";
+export type { I18nScopeSingle, I18nScopeSingleForLocale } from "./scope-single.js";
+
+export type {
+  MultiParams,
+  ParamsForNamespaces,
+  SchemaForNamespaces,
+  SingleParams,
+} from "./scope-types.js";
+
 export type {
   IcuTranslationProviderOptions,
   KeyDictionary,
@@ -19,6 +55,8 @@ export type {
   LocaleOfSingle,
   MissingTranslationContext,
   MultiDictionary,
+  PartialKeyDictionary,
+  PartialMultiDictionary,
   OnMissingTranslation,
 } from "./types.js";
 
@@ -30,6 +68,8 @@ export {
 export type { ResolvedLocaleTemplate } from "./resolve-locale.js";
 
 export {
+  mergeDictionaryLocalesCore,
+  mergeNamespaceLocalesCore,
   projectDictionaryForDeliveryAreaCore,
   projectDictionaryLocalesCore,
   projectNamespaceForDeliveryAreaCore,

package/src/patch-key.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from "vitest";
+import {
+  assertPatchKeyMulti,
+  assertPatchKeySingle,
+  preloadKeyMulti,
+  preloadKeySingle,
+  recordPreloadedKeysMulti,
+  recordPreloadedKeysSingle,
+  seedPreloadedKeysMulti,
+  seedPreloadedKeysSingle,
+} from "./patch-key.js";
+
+describe("preload key helpers", () => {
+  it("formats single preload keys as key:locale", () => {
+    expect(preloadKeySingle("welcome", "en")).toBe("welcome:en");
+  });
+
+  it("formats multi preload keys as namespace:key:locale", () => {
+    expect(preloadKeyMulti("billing", "invoice_summary", "it")).toBe("billing:invoice_summary:it");
+  });
+});
+
+describe("seedPreloadedKeysSingle", () => {
+  it("seeds every key/locale pair from the initial dictionary", () => {
+    const preloadedKeys = new Set<string>();
+    seedPreloadedKeysSingle(
+      {
+        login_button: { en: "Login", it: "Accedi" },
+        welcome: { en: "Welcome {name}!" },
+      },
+      preloadedKeys
+    );
+
+    expect(preloadedKeys).toEqual(new Set(["login_button:en", "login_button:it", "welcome:en"]));
+  });
+});
+
+describe("seedPreloadedKeysMulti", () => {
+  it("seeds every namespace/key/locale triple from the initial dictionary", () => {
+    const preloadedKeys = new Set<string>();
+    seedPreloadedKeysMulti(
+      {
+        default: { login_button: { en: "Login" } },
+        billing: { invoice_summary: { en: "One", it: "Uno" } },
+      },
+      preloadedKeys
+    );
+
+    expect(preloadedKeys).toEqual(
+      new Set([
+        "default:login_button:en",
+        "billing:invoice_summary:en",
+        "billing:invoice_summary:it",
+      ])
+    );
+  });
+});
+
+describe("recordPreloadedKeysSingle", () => {
+  it("records locales from a load merge payload", () => {
+    const preloadedKeys = new Set<string>();
+    recordPreloadedKeysSingle(
+      {
+        welcome: { it: "Benvenuto {name}!" },
+      },
+      preloadedKeys
+    );
+
+    expect(preloadedKeys).toEqual(new Set(["welcome:it"]));
+  });
+});
+
+describe("recordPreloadedKeysMulti", () => {
+  it("records locales from a namespace load merge payload", () => {
+    const preloadedKeys = new Set<string>();
+    recordPreloadedKeysMulti(
+      "billing",
+      {
+        invoice_summary: { it: "Hai {count} fatture" },
+      },
+      preloadedKeys
+    );
+
+    expect(preloadedKeys).toEqual(new Set(["billing:invoice_summary:it"]));
+  });
+});
+
+describe("assertPatchKeySingle", () => {
+  const preloadedKeys = new Set(["welcome:en", "welcome:it", "invoice_count:en"]);
+
+  it("accepts a valid patch for a preloaded key", () => {
+    expect(() =>
+      assertPatchKeySingle("welcome", "en", "Hello {name}!", preloadedKeys, {
+        en: "Welcome {name}!",
+        it: "Benvenuto {name}!",
+      })
+    ).not.toThrow();
+  });
+
+  it("rejects a key that was not preloaded", () => {
+    expect(() =>
+      assertPatchKeySingle("welcome", "fr", "Bonjour {name}!", preloadedKeys, {
+        en: "Welcome {name}!",
+      })
+    ).toThrow("[i18n] Key not preloaded: welcome (fr)");
+  });
+
+  it("rejects invalid ICU syntax", () => {
+    expect(() =>
+      assertPatchKeySingle("welcome", "en", "Hi {name", preloadedKeys, {
+        en: "Welcome {name}!",
+      })
+    ).toThrow("[i18n] ICU syntax error on patch:");
+  });
+
+  it("rejects incompatible ICU args against other locales for the same key", () => {
+    expect(() =>
+      assertPatchKeySingle(
+        "invoice_count",
+        "en",
+        "{count, select, other {{count}}}",
+        preloadedKeys,
+        {
+          en: "You have {count, plural, one {1 invoice} other {{count} invoices}}",
+          it: "Hai {count, plural, one {1 fattura} other {{count} fatture}}",
+        }
+      )
+    ).toThrow("[i18n] ICU args mismatch on patch:");
+  });
+});
+
+describe("assertPatchKeyMulti", () => {
+  const preloadedKeys = new Set([
+    "billing:invoice_summary:en",
+    "billing:invoice_summary:it",
+    "default:login_button:en",
+  ]);
+
+  it("accepts a valid patch for a preloaded namespace key", () => {
+    expect(() =>
+      assertPatchKeyMulti(
+        "billing",
+        "invoice_summary",
+        "en",
+        "You have {count, plural, one {1 bill} other {{count} bills}} for {name}",
+        preloadedKeys,
+        {
+          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}",
+        }
+      )
+    ).not.toThrow();
+  });
+
+  it("rejects a namespace key that was not preloaded", () => {
+    expect(() =>
+      assertPatchKeyMulti("billing", "invoice_summary", "fr", "Facture {count}", preloadedKeys, {
+        en: "You have {count} invoices",
+      })
+    ).toThrow("[i18n] Key not preloaded: billing.invoice_summary (fr)");
+  });
+
+  it("rejects invalid ICU syntax", () => {
+    expect(() =>
+      assertPatchKeyMulti("default", "login_button", "en", "Sign {in", preloadedKeys, {
+        en: "Login",
+      })
+    ).toThrow("[i18n] ICU syntax error on patch:");
+  });
+
+  it("rejects incompatible ICU args against other locales for the same key", () => {
+    expect(() =>
+      assertPatchKeyMulti(
+        "billing",
+        "invoice_summary",
+        "en",
+        "{count, select, other {{count}}}",
+        preloadedKeys,
+        {
+          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}",
+        }
+      )
+    ).toThrow("[i18n] ICU args mismatch on patch:");
+  });
+});

package/src/patch-key.ts

@@ -0,0 +1,140 @@
+import { mergeVariableMetaAcrossLocales, type VariableMetaSpec } from "./icu/extract-variables.js";
+import { parseTemplate } from "./icu/parse-template.js";
+import type { KeyDictionary, PartialKeyDictionary } from "./types.js";
+
+export function preloadKeySingle(key: string, locale: string): string {
+  return `${key}:${locale}`;
+}
+
+export function preloadKeyMulti(namespace: string, key: string, locale: string): string {
+  return `${namespace}:${key}:${locale}`;
+}
+
+export function seedPreloadedKeysSingle(
+  dictionary: KeyDictionary,
+  preloadedKeys: Set<string>
+): void {
+  for (const [key, localeByKey] of Object.entries(dictionary)) {
+    if (localeByKey === undefined || typeof localeByKey !== "object") {
+      continue;
+    }
+    for (const locale of Object.keys(localeByKey)) {
+      preloadedKeys.add(preloadKeySingle(key, locale));
+    }
+  }
+}
+
+export function seedPreloadedKeysMulti(
+  dictionary: Record<string, KeyDictionary>,
+  preloadedKeys: Set<string>
+): void {
+  for (const [namespace, keyDictionary] of Object.entries(dictionary)) {
+    if (keyDictionary === undefined || typeof keyDictionary !== "object") {
+      continue;
+    }
+    for (const [key, localeByKey] of Object.entries(keyDictionary)) {
+      if (localeByKey === undefined || typeof localeByKey !== "object") {
+        continue;
+      }
+      for (const locale of Object.keys(localeByKey)) {
+        preloadedKeys.add(preloadKeyMulti(namespace, key, locale));
+      }
+    }
+  }
+}
+
+export function recordPreloadedKeysSingle(
+  partial: PartialKeyDictionary<KeyDictionary, string>,
+  preloadedKeys: Set<string>
+): void {
+  for (const [key, incomingLocales] of Object.entries(partial)) {
+    if (incomingLocales === undefined || typeof incomingLocales !== "object") {
+      continue;
+    }
+    for (const locale of Object.keys(incomingLocales)) {
+      preloadedKeys.add(preloadKeySingle(key, locale));
+    }
+  }
+}
+
+export function recordPreloadedKeysMulti(
+  namespace: string,
+  partial: PartialKeyDictionary<KeyDictionary, string>,
+  preloadedKeys: Set<string>
+): void {
+  for (const [key, incomingLocales] of Object.entries(partial)) {
+    if (incomingLocales === undefined || typeof incomingLocales !== "object") {
+      continue;
+    }
+    for (const locale of Object.keys(incomingLocales)) {
+      preloadedKeys.add(preloadKeyMulti(namespace, key, locale));
+    }
+  }
+}
+
+function collectLocaleMetasForKey(
+  localeByKey: Record<string, string>,
+  patchedLocale: string,
+  patchedMeta: VariableMetaSpec
+): VariableMetaSpec[] {
+  const localeMetas: VariableMetaSpec[] = [patchedMeta];
+
+  for (const [locale, template] of Object.entries(localeByKey)) {
+    if (locale === patchedLocale) {
+      continue;
+    }
+    const parsed = parseTemplate(template);
+    if (parsed.ok) {
+      localeMetas.push(parsed.meta);
+    }
+  }
+
+  return localeMetas;
+}
+
+export function assertPatchKeySingle(
+  key: string,
+  locale: string,
+  template: string,
+  preloadedKeys: Set<string>,
+  localeByKey: Record<string, string> | undefined
+): void {
+  if (!preloadedKeys.has(preloadKeySingle(key, locale))) {
+    throw new Error(`[i18n] Key not preloaded: ${key} (${locale})`);
+  }
+
+  const parsed = parseTemplate(template);
+  if (!parsed.ok) {
+    throw new Error(`[i18n] ICU syntax error on patch: ${parsed.message}`);
+  }
+
+  const localeMetas = collectLocaleMetasForKey(localeByKey ?? {}, locale, parsed.meta);
+  const merged = mergeVariableMetaAcrossLocales(localeMetas);
+  if (!merged.ok) {
+    throw new Error(`[i18n] ICU args mismatch on patch: ${merged.message}`);
+  }
+}
+
+export function assertPatchKeyMulti(
+  namespace: string,
+  key: string,
+  locale: string,
+  template: string,
+  preloadedKeys: Set<string>,
+  localeByKey: Record<string, string> | undefined
+): void {
+  if (!preloadedKeys.has(preloadKeyMulti(namespace, key, locale))) {
+    throw new Error(`[i18n] Key not preloaded: ${namespace}.${key} (${locale})`);
+  }
+
+  const parsed = parseTemplate(template);
+  if (!parsed.ok) {
+    throw new Error(`[i18n] ICU syntax error on patch: ${parsed.message}`);
+  }
+
+  const localeMetas = collectLocaleMetasForKey(localeByKey ?? {}, locale, parsed.meta);
+  const merged = mergeVariableMetaAcrossLocales(localeMetas);
+  if (!merged.ok) {
+    throw new Error(`[i18n] ICU args mismatch on patch: ${merged.message}`);
+  }
+}

package/src/project-locales.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
+  mergeDictionaryLocalesCore,
+  mergeNamespaceLocalesCore,
   projectDictionaryForDeliveryAreaCore,
   projectDictionaryLocalesCore,
   projectNamespaceForDeliveryAreaCore,
@@ -202,3 +204,77 @@ describe("projectDictionaryLocalesCore", () => {
     });
   });
 });
+
+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,5 +1,13 @@
 import { resolveLocaleTemplate } from "./resolve-locale.js";
-import type { KeyDictionary, LocaleFallbackMap, MultiDictionary } from "./types.js";
+import type {
+  KeyDictionary,
+  LocaleFallbackMap,
+  LocaleOfMulti,
+  LocaleOfSingle,
+  MultiDictionary,
+  PartialKeyDictionary,
+  PartialMultiDictionary,
+} from "./types.js";
 
 function classifyAreaLocales(
   areaLocales: readonly string[],
@@ -152,3 +160,52 @@ export function projectDictionaryLocalesCore<T extends MultiDictionary>(
 
   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 = LocaleOfSingle<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;
+}