@xndrjs/i18n 0.6.1 → 0.7.0-alpha.0

package/src/builder-types.test.ts

@@ -0,0 +1,80 @@
+import { describe, expectTypeOf, it } from "vitest";
+import { createI18nMultiBuilder } from "./builder.js";
+import type { I18nBuilderMultiInitialImpl, I18nBuilderMultiReadyImpl } from "./builder-multi.js";
+import { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
+import type { LocalesForDeliveryArea, LocalesForDeliveryAreaOrAll } from "./builder-types.js";
+
+type TypestateSchema = {
+  billing: { invoice_summary: { en: string; it: string } };
+};
+
+type TypestateParams = {
+  billing: { invoice_summary: { count: number } };
+};
+
+function assertBuilderTypestate(): void {
+  const engine = new IcuTranslationProviderMulti<TypestateSchema, TypestateParams>({});
+  const initial = createI18nMultiBuilder(engine);
+
+  // @ts-expect-error withLocale requires withNamespaces first
+  initial.withLocale("en");
+  // @ts-expect-error load requires withNamespaces first
+  void initial.load();
+  // @ts-expect-error withDeliveryArea requires withNamespaces first
+  initial.withDeliveryArea("eu");
+  // @ts-expect-error empty namespace list is rejected
+  initial.withNamespaces([]);
+
+  const ready = initial.withNamespaces(["billing"]);
+  ready.withLocale("en");
+  void ready.load();
+}
+
+void assertBuilderTypestate;
+
+describe("builder-types", () => {
+  type ProjectLocale = "en" | "en-US" | "it" | "fr";
+  type DeliveryArea = "eu" | "amer";
+  type Artifacts = {
+    eu: readonly ["en", "it", "fr"];
+    amer: readonly ["en-US"];
+  };
+
+  it("LocalesForDeliveryArea indexes artifact locales", () => {
+    expectTypeOf<LocalesForDeliveryArea<Artifacts, "eu">>().toEqualTypeOf<"en" | "it" | "fr">();
+    expectTypeOf<LocalesForDeliveryArea<Artifacts, "amer">>().toEqualTypeOf<"en-US">();
+  });
+
+  it("LocalesForDeliveryAreaOrAll narrows only when a delivery map is configured", () => {
+    expectTypeOf<
+      LocalesForDeliveryAreaOrAll<ProjectLocale, DeliveryArea, Artifacts, "eu">
+    >().toEqualTypeOf<"en" | "it" | "fr">();
+    expectTypeOf<
+      LocalesForDeliveryAreaOrAll<ProjectLocale, never, Record<string, never>, "eu">
+    >().toEqualTypeOf<ProjectLocale>();
+  });
+});
+
+describe("I18nBuilderMulti typestate", () => {
+  it("initial builder only exposes withNamespaces", () => {
+    const engine = new IcuTranslationProviderMulti<TypestateSchema, TypestateParams>({});
+    const initial = createI18nMultiBuilder(engine);
+    expectTypeOf(initial).toEqualTypeOf<
+      I18nBuilderMultiInitialImpl<TypestateSchema, TypestateParams>
+    >();
+  });
+
+  it("ready builder exposes partition and load", () => {
+    const engine = new IcuTranslationProviderMulti<TypestateSchema, TypestateParams>({});
+    const ready = createI18nMultiBuilder(engine).withNamespaces(["billing"]);
+    expectTypeOf(ready).toEqualTypeOf<
+      I18nBuilderMultiReadyImpl<
+        TypestateSchema,
+        TypestateParams,
+        "en" | "it",
+        "en" | "it",
+        readonly ["billing"]
+      >
+    >();
+  });
+});

package/src/builder-types.ts

@@ -0,0 +1,24 @@
+/** Locales served by a delivery area, from a codegen `DELIVERY_ARTIFACTS`-shaped map. */
+export type LocalesForDeliveryArea<
+  Artifacts extends Record<string, readonly string[]>,
+  Area extends keyof Artifacts & string,
+> = Artifacts[Area][number];
+
+/** Map from delivery area to locale lists; empty when custom delivery is not configured. */
+export type DeliveryArtifactsMap<RequestLocales extends string, DeliveryArea extends string> = [
+  DeliveryArea,
+] extends [never]
+  ? Record<string, never>
+  : Record<DeliveryArea, readonly RequestLocales[]>;
+
+/** When a delivery-area map is configured, resolve partition locales; otherwise keep the full pool. */
+export type LocalesForDeliveryAreaOrAll<
+  RequestLocales extends string,
+  DeliveryArea extends string,
+  DeliveryArtifacts extends DeliveryArtifactsMap<RequestLocales, DeliveryArea>,
+  Area extends string,
+> = [DeliveryArea] extends [never]
+  ? RequestLocales
+  : Area extends DeliveryArea
+    ? DeliveryArtifacts[Area][number]
+    : never;

package/src/builder.test.ts

@@ -0,0 +1,421 @@
+import { describe, expect, expectTypeOf, it, vi } from "vitest";
+import { createI18nBuilder, createI18nMultiBuilder } from "./builder.js";
+import { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
+import { IcuTranslationProviderSingle } from "./IcuTranslationProviderSingle.js";
+
+type SingleSchema = {
+  login_button: { en: string; it: string };
+  welcome: { en: string; it: string };
+};
+
+type SingleParams = {
+  login_button: never;
+  welcome: { name: string };
+};
+
+type MultiSchema = {
+  default: {
+    login_button: { en: string; it: string };
+    welcome: { en: string };
+  };
+  billing: {
+    invoice_summary: { en: string; it: string };
+  };
+};
+
+type TestMultiParams = {
+  default: {
+    login_button: never;
+    welcome: { name: string };
+  };
+  billing: {
+    invoice_summary: { count: number; name: string };
+  };
+};
+
+type TestDeliveryArea = "eu" | "us";
+type TestDeliveryArtifacts = {
+  eu: readonly ["it"];
+  us: readonly ["en"];
+};
+
+const billingIt = {
+  invoice_summary: {
+    it: "Hai {count, plural, one {1 fattura} other {{count} fatture}} per {name}",
+  },
+};
+
+const billingEn = {
+  invoice_summary: {
+    en: "You have {count, plural, one {1 invoice} other {{count} invoices}} for {name}",
+  },
+};
+
+const defaultIt = {
+  login_button: { it: "Accedi" },
+  welcome: { it: "Benvenuto {name}!" },
+};
+
+describe("I18nBuilder multi", () => {
+  it("load() invokes mock loaders, merges into the engine, and returns a bound view", async () => {
+    const billingLoader = vi.fn(async (locale: string) => {
+      return locale === "it" ? billingIt : billingEn;
+    });
+    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
+    const builder = createI18nBuilder(engine, {
+      namespaceLoaders: {
+        billing: billingLoader,
+      },
+    });
+
+    const view = await builder.withNamespaces(["billing"]).withLocale("it").load();
+
+    expect(billingLoader).toHaveBeenCalledWith("it");
+    expect(view.locale).toBe("it");
+    expect(view.t("billing", "invoice_summary", { count: 2, name: "Ada" })).toBe(
+      "Hai 2 fatture per Ada"
+    );
+  });
+
+  it("chains withNamespaces and withLocale before load()", async () => {
+    const billingLoader = vi.fn(async (locale: string) =>
+      locale === "it" ? billingIt : billingEn
+    );
+    const defaultLoader = vi.fn(async () => defaultIt);
+    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
+
+    const view = await createI18nMultiBuilder(engine, {
+      namespaceLoaders: {
+        billing: billingLoader,
+        default: defaultLoader,
+      },
+    })
+      .withNamespaces(["billing", "default"])
+      .withLocale("it")
+      .load();
+
+    expect(billingLoader).toHaveBeenCalledWith("it");
+    expect(defaultLoader).toHaveBeenCalledWith("it");
+    expect(view.t("default", "login_button")).toBe("Accedi");
+    expect(view.t("billing", "invoice_summary", { count: 1, name: "Bob" })).toBe(
+      "Hai 1 fattura per Bob"
+    );
+  });
+
+  it("patches a preloaded key via scope.set() after load()", async () => {
+    const billingLoader = vi.fn(async () => billingEn);
+    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
+
+    const view = await createI18nBuilder(engine, {
+      namespaceLoaders: { billing: billingLoader },
+    })
+      .withNamespaces(["billing"])
+      .withLocale("en")
+      .load();
+
+    view.set(
+      "billing",
+      "invoice_summary",
+      "You have {count, plural, one {1 invoice only} other {{count} invoices only}} for {name}"
+    );
+
+    expect(view.t("billing", "invoice_summary", { count: 1, name: "Ada" })).toBe(
+      "You have 1 invoice only for Ada"
+    );
+  });
+
+  it("accumulates engine data across repeated load() calls on the same builder", async () => {
+    const billingLoader = vi.fn(async (locale: string) =>
+      locale === "it" ? billingIt : billingEn
+    );
+    const defaultLoader = vi.fn(async () => defaultIt);
+    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
+    const builder = createI18nBuilder(engine, {
+      namespaceLoaders: {
+        billing: billingLoader,
+        default: defaultLoader,
+      },
+    });
+
+    const billingView = await builder.withNamespaces(["billing"]).withLocale("it").load();
+    const defaultView = await builder.withNamespaces(["default"]).withLocale("it").load();
+
+    expect(billingLoader).toHaveBeenCalledTimes(1);
+    expect(defaultLoader).toHaveBeenCalledTimes(1);
+    expect(billingView.t("billing", "invoice_summary", { count: 1, name: "Ada" })).toBe(
+      "Hai 1 fattura per Ada"
+    );
+    expect(defaultView.t("default", "login_button")).toBe("Accedi");
+    expect(engine.getAll().billing.invoice_summary.it).toBe(billingIt.invoice_summary.it);
+    expect(engine.getAll().default.login_button.it).toBe("Accedi");
+  });
+
+  it("returns a view scoped to namespaces declared at load time", async () => {
+    const billingLoader = vi.fn(async (locale: string) =>
+      locale === "it" ? billingIt : billingEn
+    );
+    const defaultLoader = vi.fn(async () => defaultIt);
+    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
+    const builder = createI18nBuilder(engine, {
+      namespaceLoaders: {
+        billing: billingLoader,
+        default: defaultLoader,
+      },
+    });
+
+    const billingView = await builder.withNamespaces(["billing"]).withLocale("it").load();
+    await builder.withNamespaces(["default"]).withLocale("it").load();
+
+    expect(billingView.t("billing", "invoice_summary", { count: 1, name: "Ada" })).toBe(
+      "Hai 1 fattura per Ada"
+    );
+    // billingView is typed for the billing namespace only; default is excluded at compile time.
+  });
+
+  it("loads via withDeliveryArea for custom delivery partitions", async () => {
+    const billingLoader = vi.fn(async (area: string) => {
+      return area === "eu" ? billingIt : billingEn;
+    });
+    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
+
+    const euView = await createI18nMultiBuilder<
+      MultiSchema,
+      TestMultiParams,
+      "en" | "it",
+      TestDeliveryArea,
+      TestDeliveryArtifacts
+    >(engine, {
+      namespaceLoaders: {
+        billing: billingLoader,
+      },
+    })
+      .withNamespaces(["billing"])
+      .withDeliveryArea("eu")
+      .load();
+
+    expect(billingLoader).toHaveBeenCalledWith("eu");
+    expect(euView.t("billing", "invoice_summary", "it", { count: 2, name: "Ada" })).toBe(
+      "Hai 2 fatture per Ada"
+    );
+    expectTypeOf(euView.t).toBeCallableWith("billing", "invoice_summary", "it", {
+      count: 2,
+      name: "Ada",
+    });
+    expectTypeOf(euView.forLocale).toBeCallableWith("it");
+    expectTypeOf(euView.forLocale).parameters.not.toMatchTypeOf<["en-US"]>();
+  });
+
+  it("loads canonical namespace loaders without a partition", async () => {
+    const billingLoader = vi.fn(async () => ({
+      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}",
+      },
+    }));
+    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
+
+    const view = await createI18nBuilder(engine, {
+      namespaceLoaders: {
+        billing: billingLoader,
+      },
+    })
+      .withNamespaces(["billing"])
+      .load();
+
+    expect(billingLoader).toHaveBeenCalledTimes(1);
+    expect(billingLoader.mock.calls[0]).toEqual([]);
+    expect(view.t("billing", "invoice_summary", "en", { count: 1, name: "Ada" })).toBe(
+      "You have 1 invoice for Ada"
+    );
+  });
+
+  it("skips a repeated load for the same namespace partition", async () => {
+    const billingLoader = vi.fn(async (locale: string) =>
+      locale === "it" ? billingIt : billingEn
+    );
+    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
+    const options = { namespaceLoaders: { billing: billingLoader } };
+    const chain = () =>
+      createI18nBuilder(engine, options).withNamespaces(["billing"]).withLocale("it");
+
+    await chain().load();
+    await chain().load();
+
+    expect(billingLoader).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns a destructuring-safe locale-bound scope from load()", async () => {
+    const billingLoader = vi.fn(async () => billingEn);
+    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
+    const { t } = await createI18nBuilder(engine, {
+      namespaceLoaders: { billing: billingLoader },
+    })
+      .withNamespaces(["billing"])
+      .withLocale("en")
+      .load();
+
+    expect(t("billing", "invoice_summary", { count: 1, name: "Ada" })).toBe(
+      "You have 1 invoice for Ada"
+    );
+  });
+
+  it("preserves runtime patches when a later builder reloads the same resource", async () => {
+    const billingLoader = vi.fn(async () => billingEn);
+    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
+    const options = { namespaceLoaders: { billing: billingLoader } };
+
+    const firstView = await createI18nBuilder(engine, options)
+      .withNamespaces(["billing"])
+      .withLocale("en")
+      .load();
+
+    firstView.set(
+      "billing",
+      "invoice_summary",
+      "You have {count, plural, one {1 invoice only} other {{count} invoices only}} for {name}"
+    );
+
+    const secondView = await createI18nBuilder(engine, options)
+      .withNamespaces(["billing"])
+      .withLocale("en")
+      .load();
+
+    expect(billingLoader).toHaveBeenCalledTimes(1);
+    expect(secondView.t("billing", "invoice_summary", { count: 1, name: "Ada" })).toBe(
+      "You have 1 invoice only for Ada"
+    );
+  });
+
+  it("still loads a different partition for the same namespace", async () => {
+    const billingLoader = vi.fn(async (locale: string) =>
+      locale === "it" ? billingIt : billingEn
+    );
+    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
+    const builder = createI18nBuilder(engine, {
+      namespaceLoaders: { billing: billingLoader },
+    });
+
+    await builder.withNamespaces(["billing"]).withLocale("it").load();
+    await builder.withNamespaces(["billing"]).withLocale("en").load();
+
+    expect(billingLoader).toHaveBeenCalledTimes(2);
+    expect(billingLoader).toHaveBeenNthCalledWith(1, "it");
+    expect(billingLoader).toHaveBeenNthCalledWith(2, "en");
+  });
+});
+
+describe("I18nBuilder single", () => {
+  it("load() invokes a locale loader and returns a bound view", async () => {
+    const dictionaryLoader = vi.fn(async (locale: string) => {
+      return locale === "it"
+        ? {
+            login_button: { it: "Accedi" },
+            welcome: { it: "Benvenuto {name}!" },
+          }
+        : {
+            login_button: { en: "Login" },
+            welcome: { en: "Welcome {name}!" },
+          };
+    });
+    const engine = new IcuTranslationProviderSingle<SingleSchema, SingleParams>({
+      login_button: { en: "", it: "" },
+      welcome: { en: "", it: "" },
+    });
+
+    const view = await createI18nBuilder<SingleSchema, SingleParams>(engine, { dictionaryLoader })
+      .withLocale("it")
+      .load();
+
+    expect(dictionaryLoader).toHaveBeenCalledWith("it");
+    expect(view.locale).toBe("it");
+    expect(view.t("login_button")).toBe("Accedi");
+    expect(view.t("welcome", { name: "Ada" })).toBe("Benvenuto Ada!");
+  });
+
+  it("patches a preloaded key via scope.set() after load()", async () => {
+    const dictionaryLoader = vi.fn(async () => ({
+      login_button: { en: "Login" },
+      welcome: { en: "Welcome {name}!" },
+    }));
+    const engine = new IcuTranslationProviderSingle<SingleSchema, SingleParams>({
+      login_button: { en: "", it: "" },
+      welcome: { en: "", it: "" },
+    });
+
+    const view = await createI18nBuilder<SingleSchema, SingleParams>(engine, { dictionaryLoader })
+      .withLocale("en")
+      .load();
+
+    view.set("login_button", "Sign in");
+
+    expect(view.t("login_button")).toBe("Sign in");
+    expect(view.t("welcome", { name: "Ada" })).toBe("Welcome Ada!");
+  });
+
+  it("throws when scope.set() targets a key that was not preloaded", async () => {
+    const dictionaryLoader = vi.fn(async () => ({
+      login_button: { en: "Login" },
+      welcome: { en: "Welcome {name}!" },
+    }));
+    const engine = new IcuTranslationProviderSingle<SingleSchema, SingleParams>({
+      // @ts-expect-error
+      login_button: { en: "" },
+      // @ts-expect-error
+      welcome: { en: "" },
+    });
+
+    const view = await createI18nBuilder<SingleSchema, SingleParams>(engine, { dictionaryLoader })
+      .withLocale("en")
+      .load();
+
+    // @ts-expect-error
+    expect(() => view.forLocale("it").set("login_button", "Accedi")).toThrow(
+      "[i18n] Key not preloaded: login_button (it)"
+    );
+  });
+
+  it("skips a repeated load for the same locale partition", async () => {
+    const dictionaryLoader = vi.fn(async () => ({
+      login_button: { en: "Login" },
+      welcome: { en: "Welcome {name}!" },
+    }));
+    const engine = new IcuTranslationProviderSingle<SingleSchema, SingleParams>({
+      login_button: { en: "", it: "" },
+      welcome: { en: "", it: "" },
+    });
+    const options = { dictionaryLoader };
+    const chain = () =>
+      createI18nBuilder<SingleSchema, SingleParams>(engine, options).withLocale("en");
+
+    await chain().load();
+    await chain().load();
+
+    expect(dictionaryLoader).toHaveBeenCalledTimes(1);
+  });
+
+  it("preserves runtime patches when a later builder reloads the same resource", async () => {
+    const dictionaryLoader = vi.fn(async () => ({
+      login_button: { en: "Login" },
+      welcome: { en: "Welcome {name}!" },
+    }));
+    const engine = new IcuTranslationProviderSingle<SingleSchema, SingleParams>({
+      login_button: { en: "", it: "" },
+      welcome: { en: "", it: "" },
+    });
+    const options = { dictionaryLoader };
+
+    const firstView = await createI18nBuilder<SingleSchema, SingleParams>(engine, options)
+      .withLocale("en")
+      .load();
+
+    firstView.set("login_button", "Sign in");
+
+    const secondView = await createI18nBuilder<SingleSchema, SingleParams>(engine, options)
+      .withLocale("en")
+      .load();
+
+    expect(dictionaryLoader).toHaveBeenCalledTimes(1);
+    expect(secondView.t("login_button")).toBe("Sign in");
+    expect(secondView.t("welcome", { name: "Ada" })).toBe("Welcome Ada!");
+  });
+});

package/src/builder.ts

@@ -0,0 +1,112 @@
+import type { DeliveryArtifactsMap } from "./builder-types.js";
+import { I18nBuilderMultiInitialImpl, type I18nBuilderMultiOptions } from "./builder-multi.js";
+import { I18nBuilderSingleImpl, type I18nBuilderSingleOptions } from "./single-builder.js";
+import type { I18nEngineMultiImpl, I18nEngineSingleImpl } from "./engine.js";
+import type { KeyDictionary, LocaleOfMulti, LocaleOfSingle, MultiDictionary } from "./types.js";
+import type { MultiParams } from "./scope-types.js";
+
+export type { CanonicalLoader, NamespaceLoader, PartitionedLoader } from "./builder-loaders.js";
+export { invokeNamespaceLoader } from "./builder-loaders.js";
+export type {
+  I18nBuilderMulti,
+  I18nBuilderMultiForLocale,
+  I18nBuilderMultiInitial,
+  I18nBuilderMultiOptions,
+  I18nBuilderMultiPartitioned,
+  I18nBuilderMultiReady,
+} from "./builder-multi.js";
+export type {
+  I18nBuilderSingle,
+  I18nBuilderSingleForLocale,
+  I18nBuilderSingleOptions,
+} from "./single-builder.js";
+
+type AnySingleEngine = I18nEngineSingleImpl<KeyDictionary, { [K in keyof KeyDictionary]: unknown }>;
+type AnyMultiEngine = I18nEngineMultiImpl<MultiDictionary, MultiParams<MultiDictionary>>;
+
+function isMultiEngine(engine: AnySingleEngine | AnyMultiEngine): engine is AnyMultiEngine {
+  return engine.__i18nEngineMode === "multi";
+}
+
+export function createI18nSingleBuilder<
+  Schema extends KeyDictionary,
+  Params extends { [K in keyof Schema]: unknown },
+  RequestLocales extends string = LocaleOfSingle<Schema>,
+>(
+  engine: I18nEngineSingleImpl<Schema, Params, RequestLocales>,
+  options?: I18nBuilderSingleOptions<Schema, RequestLocales>
+): I18nBuilderSingleImpl<Schema, Params, RequestLocales> {
+  return new I18nBuilderSingleImpl(engine, options);
+}
+
+export function createI18nMultiBuilder<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string = LocaleOfMulti<Schema>,
+  DeliveryArea extends string = never,
+  DeliveryArtifacts extends DeliveryArtifactsMap<RequestLocales, DeliveryArea> =
+    DeliveryArtifactsMap<RequestLocales, DeliveryArea>,
+>(
+  engine: I18nEngineMultiImpl<Schema, Params, RequestLocales>,
+  options?: I18nBuilderMultiOptions<Schema, RequestLocales>
+): I18nBuilderMultiInitialImpl<
+  Schema,
+  Params,
+  RequestLocales,
+  RequestLocales,
+  DeliveryArea,
+  DeliveryArtifacts
+> {
+  return new I18nBuilderMultiInitialImpl<
+    Schema,
+    Params,
+    RequestLocales,
+    RequestLocales,
+    DeliveryArea,
+    DeliveryArtifacts
+  >(engine, options);
+}
+
+export function createI18nBuilder<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string = LocaleOfMulti<Schema>,
+>(
+  engine: I18nEngineMultiImpl<Schema, Params, RequestLocales>,
+  options?: I18nBuilderMultiOptions<Schema, RequestLocales>
+): I18nBuilderMultiInitialImpl<
+  Schema,
+  Params,
+  RequestLocales,
+  RequestLocales,
+  never,
+  DeliveryArtifactsMap<RequestLocales, never>
+>;
+
+export function createI18nBuilder<
+  Schema extends KeyDictionary,
+  Params extends { [K in keyof Schema]: unknown },
+  RequestLocales extends string = LocaleOfSingle<Schema>,
+>(
+  engine: I18nEngineSingleImpl<Schema, Params, RequestLocales>,
+  options?: I18nBuilderSingleOptions<Schema, RequestLocales>
+): I18nBuilderSingleImpl<Schema, Params, RequestLocales>;
+
+export function createI18nBuilder(
+  engine: AnySingleEngine | AnyMultiEngine,
+  options?:
+    | I18nBuilderMultiOptions<MultiDictionary, string>
+    | I18nBuilderSingleOptions<KeyDictionary, string>
+): never {
+  if (isMultiEngine(engine)) {
+    return createI18nMultiBuilder(
+      engine,
+      options as I18nBuilderMultiOptions<MultiDictionary, string> | undefined
+    ) as never;
+  }
+
+  return createI18nSingleBuilder(
+    engine,
+    options as I18nBuilderSingleOptions<KeyDictionary, string> | undefined
+  ) as never;
+}

package/src/codegen/delivery-artifacts.test.ts

@@ -160,7 +160,8 @@ describe("delivery-artifacts", () => {
         '  "eu": ["fr", "it"] as const,\n' +
         '  "us": ["en-US"] as const,\n' +
         "} as const satisfies Record<AppDeliveryArea, readonly AppLocale[]>;\n\n" +
-        "export type AppDeliveryArtifacts = typeof DELIVERY_ARTIFACTS;\n\n"
+        "export type AppDeliveryArtifacts = typeof DELIVERY_ARTIFACTS;\n\n" +
+        "export type LocalesForDeliveryArea<A extends AppDeliveryArea> = AppDeliveryArtifacts[A][number];\n\n"
     );
   });
 });

package/src/codegen/delivery-artifacts.ts

@@ -148,6 +148,7 @@ export function formatDeliveryArtifactsBlock(
 
   return (
     `export const ${constName} = {\n${areaEntries}\n} as const satisfies Record<${deliveryAreaTypeName}, readonly ${localeTypeName}[]>;\n\n` +
-    `export type ${deliveryArtifactsTypeName} = typeof ${constName};\n\n`
+    `export type ${deliveryArtifactsTypeName} = typeof ${constName};\n\n` +
+    `export type LocalesForDeliveryArea<A extends ${deliveryAreaTypeName}> = ${deliveryArtifactsTypeName}[A][number];\n\n`
   );
 }