@xndrjs/i18n 0.8.0 → 0.8.2-alpha.0

package/src/resolve-locale.ts

@@ -1,88 +0,0 @@
-export type LocaleFallbackMap = Record<string, string | null>;
-
-export interface ResolvedLocaleTemplate {
-  template: string;
-  resolvedLocale: string;
-  fallbackChain: readonly string[];
-}
-
-export function validateLocaleFallback(map: LocaleFallbackMap): void {
-  for (const startLocale of Object.keys(map)) {
-    const visited = new Set<string>();
-    let current: string | undefined = startLocale;
-
-    while (current !== undefined) {
-      if (visited.has(current)) {
-        throw new Error(`[i18n] Circular locale fallback detected involving "${current}"`);
-      }
-      visited.add(current);
-
-      const next: string | null | undefined = map[current];
-      if (next === undefined || next === null) {
-        break;
-      }
-      current = next;
-    }
-  }
-}
-
-export function resolveLocaleTemplate(
-  localeByKey: Record<string, string | undefined> | undefined,
-  requestedLocale: string,
-  fallbackMap?: LocaleFallbackMap
-): ResolvedLocaleTemplate | undefined {
-  const chain: string[] = [requestedLocale];
-  let currentLocale = requestedLocale;
-
-  while (true) {
-    const template = localeByKey?.[currentLocale];
-    if (template !== undefined) {
-      return { template, resolvedLocale: currentLocale, fallbackChain: chain };
-    }
-
-    if (!fallbackMap) {
-      return undefined;
-    }
-
-    const fallback = fallbackMap[currentLocale];
-    if (fallback === undefined || fallback === null) {
-      return undefined;
-    }
-
-    if (chain.includes(fallback)) {
-      throw new Error(
-        `[i18n] Circular locale fallback detected: ${[...chain, fallback].join(" → ")}`
-      );
-    }
-
-    chain.push(fallback);
-    currentLocale = fallback;
-  }
-}
-
-export function formatLocaleFallbackChain(
-  requestedLocale: string,
-  fallbackMap?: LocaleFallbackMap
-): string {
-  if (!fallbackMap) {
-    return requestedLocale;
-  }
-
-  const chain: string[] = [requestedLocale];
-  let current = requestedLocale;
-
-  while (true) {
-    const fallback = fallbackMap[current];
-    if (fallback === undefined || fallback === null) {
-      break;
-    }
-    if (chain.includes(fallback)) {
-      chain.push(fallback);
-      break;
-    }
-    chain.push(fallback);
-    current = fallback;
-  }
-
-  return chain.join(" → ");
-}

package/src/scope-multi.ts

@@ -1,105 +0,0 @@
-import type { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
-import type { LocaleFallbackMap, LocaleOfMulti, MultiDictionary } from "./types.js";
-import type { MultiParams, ParamArgs } from "./scope-types.js";
-
-/** Type-safe translation scope for a multi-namespace schema subset. */
-export interface I18nScopeMulti<
-  Schema extends MultiDictionary,
-  Params,
-  RequestLocales extends string = LocaleOfMulti<Schema>,
-> {
-  t<
-    const NS extends keyof Schema & keyof Params & string,
-    const K extends keyof Schema[NS] & keyof Params[NS] & string,
-  >(
-    namespace: NS,
-    key: K,
-    locale: RequestLocales,
-    ...params: ParamArgs<Params[NS][K]>
-  ): string;
-  forLocale<Locale extends RequestLocales>(
-    locale: Locale
-  ): I18nScopeMultiForLocale<Schema, Params, RequestLocales, Locale>;
-}
-
-/** Multi-namespace scope with a bound locale — `t(namespace, key)` without a locale argument. */
-export interface I18nScopeMultiForLocale<
-  Schema extends MultiDictionary,
-  Params,
-  RequestLocales extends string,
-  Locale extends RequestLocales,
-> {
-  readonly locale: Locale;
-  t<
-    const NS extends keyof Schema & keyof Params & string,
-    const K extends keyof Schema[NS] & keyof Params[NS] & string,
-  >(
-    namespace: NS,
-    key: K,
-    ...params: ParamArgs<Params[NS][K]>
-  ): string;
-  forLocale<Next extends RequestLocales>(
-    locale: Next
-  ): I18nScopeMultiForLocale<Schema, Params, RequestLocales, Next>;
-}
-
-export class I18nScopeMultiImpl<
-  Schema extends MultiDictionary,
-  Params extends MultiParams<Schema>,
-  RequestLocales extends string,
-  Fallback extends LocaleFallbackMap | undefined,
-> implements I18nScopeMulti<Schema, Params, RequestLocales> {
-  constructor(
-    private readonly engine: IcuTranslationProviderMulti<Schema, Params, RequestLocales, Fallback>
-  ) {}
-
-  t = <
-    const NS extends keyof Schema & keyof Params & string,
-    const K extends keyof Schema[NS] & keyof Params[NS] & string,
-  >(
-    namespace: NS,
-    key: K,
-    locale: RequestLocales,
-    ...args: ParamArgs<Params[NS][K]>
-  ): string => {
-    const params = args[0] as Record<string, unknown> | undefined;
-    return this.engine.getWithLocale(String(namespace), String(key), locale, params);
-  };
-
-  forLocale = <Locale extends RequestLocales>(
-    locale: Locale
-  ): I18nScopeMultiForLocaleImpl<Schema, Params, RequestLocales, Locale, Fallback> => {
-    return new I18nScopeMultiForLocaleImpl(this.engine, locale);
-  };
-}
-
-export class I18nScopeMultiForLocaleImpl<
-  Schema extends MultiDictionary,
-  Params extends MultiParams<Schema>,
-  RequestLocales extends string,
-  Locale extends RequestLocales,
-  Fallback extends LocaleFallbackMap | undefined,
-> implements I18nScopeMultiForLocale<Schema, Params, RequestLocales, Locale> {
-  constructor(
-    private readonly engine: IcuTranslationProviderMulti<Schema, Params, RequestLocales, Fallback>,
-    readonly locale: Locale
-  ) {}
-
-  t = <
-    const NS extends keyof Schema & keyof Params & string,
-    const K extends keyof Schema[NS] & keyof Params[NS] & string,
-  >(
-    namespace: NS,
-    key: K,
-    ...args: ParamArgs<Params[NS][K]>
-  ): string => {
-    const params = args[0] as Record<string, unknown> | undefined;
-    return this.engine.getWithLocale(String(namespace), String(key), this.locale, params);
-  };
-
-  forLocale = <Next extends RequestLocales>(
-    locale: Next
-  ): I18nScopeMultiForLocaleImpl<Schema, Params, RequestLocales, Next, Fallback> => {
-    return new I18nScopeMultiForLocaleImpl(this.engine, locale);
-  };
-}

package/src/scope-types.ts

@@ -1,35 +0,0 @@
-import type { MultiDictionary } from "./types.js";
-
-/** ICU argument map for a multi-namespace schema. */
-export type MultiParams<Schema extends MultiDictionary> = {
-  [NS in keyof Schema]: { [K in keyof Schema[NS]]: unknown };
-};
-
-/** Restrict a multi schema to a subset of namespaces. */
-export type SchemaForNamespaces<
-  Schema extends MultiDictionary,
-  NsList extends readonly (keyof Schema & string)[],
-> = Pick<Schema, NsList[number]>;
-
-/** Restrict multi ICU params to a subset of namespaces. */
-export type ParamsForNamespaces<
-  Schema extends MultiDictionary,
-  Params extends MultiParams<Schema>,
-  NsList extends readonly (keyof Schema & string)[],
-> = Pick<Params, NsList[number]>;
-
-/** Rest args for `t()` — `never` params omit the third argument. */
-export type ParamArgs<P> = [P] extends [never] ? [] : [params: P];
-
-/**
- * Namespace-bound `t(key, …)` — locale already bound.
- * Call sites omit the namespace argument.
- */
-export type NamespaceBoundTranslateFn<
-  Schema extends MultiDictionary,
-  Params extends MultiParams<Schema>,
-  NS extends keyof Schema & keyof Params & string,
-> = <const K extends keyof Schema[NS] & keyof Params[NS] & string>(
-  key: K,
-  ...params: ParamArgs<Params[NS][K]>
-) => string;

package/src/scope.test.ts

@@ -1,172 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
-import type { LocaleOfMulti } from "./types.js";
-
-type MultiSchema = {
-  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 MultiParams = {
-  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 multiDictionary: MultiSchema = {
-  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("I18nScope multi", () => {
-  const engine = new IcuTranslationProviderMulti<MultiSchema, MultiParams>(multiDictionary);
-
-  it("translates with t(namespace, key, locale)", () => {
-    const view = engine.toScope({ namespaces: ["default", "billing"] });
-
-    expect(view.t("default", "login_button", "it")).toBe("Accedi");
-    expect(view.t("default", "welcome", "en", { name: "Ada" })).toBe("Welcome Ada!");
-    expect(view.t("billing", "invoice_summary", "en", { count: 3, name: "Ada" })).toBe(
-      "You have 3 invoices for Ada"
-    );
-  });
-
-  it("restricts namespaces at the type level", () => {
-    const billingOnly = engine.toScope({ namespaces: ["billing"] });
-
-    expect(billingOnly.t("billing", "invoice_summary", "en", { count: 1, name: "Ada" })).toBe(
-      "You have 1 invoice for Ada"
-    );
-  });
-
-  it("binds locale via forLocale", () => {
-    const view = engine.toScope({ namespaces: ["default", "billing"] });
-    const it = view.forLocale("it");
-
-    expect(it.locale).toBe("it");
-    expect(it.t("default", "login_button")).toBe("Accedi");
-    expect(it.t("billing", "invoice_summary", { count: 2, name: "Ada" })).toBe(
-      "Hai 2 fatture per Ada"
-    );
-  });
-
-  it("binds locale via toScope({ namespaces, locale })", () => {
-    const it = engine.toScope({ namespaces: ["billing"], locale: "it" });
-    expect(it.locale).toBe("it");
-    expect(it.t("billing", "invoice_summary", { count: 2, name: "Ada" })).toBe(
-      "Hai 2 fatture per Ada"
-    );
-  });
-
-  it("supports destructuring t from locale-bound scopes", () => {
-    const { t } = engine.toScope({ namespaces: ["billing"] }).forLocale("en");
-
-    expect(t("billing", "invoice_summary", { count: 1, name: "Ada" })).toBe(
-      "You have 1 invoice for Ada"
-    );
-  });
-
-  it("reflects partial applyLoadMergeNamespace via a fresh toScope", () => {
-    const partial = new IcuTranslationProviderMulti<MultiSchema, MultiParams>({
-      billing: {
-        invoice_summary: {
-          en: "You have {count, plural, one {1 invoice} other {{count} invoices}} for {name}",
-        },
-      },
-    });
-
-    partial.applyLoadMergeNamespace("billing", {
-      invoice_summary: {
-        it: "Hai {count, plural, one {1 fattura} other {{count} fatture}} per {name}",
-      },
-    });
-
-    const view = partial.toScope({ namespaces: ["billing"], locale: "it" });
-    expect(view.t("billing", "invoice_summary", { count: 2, name: "Bob" })).toBe(
-      "Hai 2 fatture per Bob"
-    );
-  });
-
-  it("degrades to onMissing for namespaces not in dictionary", () => {
-    const partial = new IcuTranslationProviderMulti<MultiSchema, MultiParams>(
-      { default: multiDictionary.default },
-      { onMissing: "key" }
-    );
-    const view = partial.toScope({ namespaces: ["billing"], locale: "en" });
-
-    expect(view.t("billing", "invoice_summary", { count: 1, name: "Ada" })).toBe(
-      "billing.invoice_summary"
-    );
-  });
-
-  describe("locale fallback", () => {
-    const fallbackMap = {
-      en: null,
-      "de-DE": "en",
-      "de-CH": "de-DE",
-      it: "en",
-    } as const;
-
-    const fallbackEngine = new IcuTranslationProviderMulti<
-      MultiSchema,
-      MultiParams,
-      keyof typeof fallbackMap | LocaleOfMulti<MultiSchema>,
-      typeof fallbackMap
-    >(multiDictionary, { localeFallback: fallbackMap });
-
-    it("resolves a locale through the fallback chain", () => {
-      const view = fallbackEngine.toScope({ namespaces: ["default"] });
-      expect(view.t("default", "login_button", "de-CH")).toBe("Login");
-    });
-  });
-});

package/src/serialized-state.test.ts

@@ -1,114 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { createI18nHandle } from "./builder.js";
-import { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
-import { normalizeI18nCreateInput } from "./serialized-state.js";
-
-type MultiSchema = {
-  default: { greeting: { en: string; it: string } };
-  billing: { invoice: { en: string; it: string } };
-};
-type MultiParams = {
-  default: { greeting: never };
-  billing: { invoice: never };
-};
-
-describe("serialize / createI18n({ state })", () => {
-  it("normalizeI18nCreateInput defaults missing state to empty dictionary and [] resources", () => {
-    expect(normalizeI18nCreateInput()).toEqual({
-      dictionary: {},
-      resources: [],
-    });
-  });
-
-  it("normalizeI18nCreateInput defaults missing resources to []", () => {
-    expect(normalizeI18nCreateInput({ dictionary: { greeting: { en: "Hi" } } })).toEqual({
-      dictionary: { greeting: { en: "Hi" } },
-      resources: [],
-    });
-  });
-
-  it("serialize after load → fresh handle skips loaders for marked resources", async () => {
-    const defaultLoader = vi.fn(async (locale: string) => ({
-      greeting: { [locale]: locale === "it" ? "Ciao" : "Hello" },
-    }));
-    const billingLoader = vi.fn(async (locale: string) => ({
-      invoice: { [locale]: locale === "it" ? "Fattura" : "Invoice" },
-    }));
-
-    const ssrEngine = new IcuTranslationProviderMulti<MultiSchema, MultiParams>({});
-    const ssr = createI18nHandle(ssrEngine, {
-      namespaceLoaders: {
-        default: defaultLoader,
-        billing: billingLoader,
-      },
-    });
-
-    await ssr.load({ namespaces: ["default", "billing"], locale: "it" });
-    expect(defaultLoader).toHaveBeenCalledTimes(1);
-    expect(billingLoader).toHaveBeenCalledTimes(1);
-
-    const serialized = ssr.serialize();
-    expect(serialized.resources).toEqual(
-      expect.arrayContaining([
-        ["default", "it"],
-        ["billing", "it"],
-      ])
-    );
-    expect(serialized.dictionary.default?.greeting?.it).toBe("Ciao");
-
-    const csrEngine = new IcuTranslationProviderMulti<MultiSchema, MultiParams>(
-      serialized.dictionary
-    );
-    csrEngine.seedBuilderResources(serialized.resources);
-    const csr = createI18nHandle(csrEngine, {
-      namespaceLoaders: {
-        default: defaultLoader,
-        billing: billingLoader,
-      },
-    });
-
-    expect(csrEngine.hasBuilderResourceLoaded("default", "it")).toBe(true);
-    expect(csrEngine.hasBuilderResourceLoaded("billing", "it")).toBe(true);
-
-    await csr.load({ namespaces: ["default", "billing"], locale: "it" });
-    expect(defaultLoader).toHaveBeenCalledTimes(1);
-    expect(billingLoader).toHaveBeenCalledTimes(1);
-
-    const scope = csr.peek({ namespaces: ["default", "billing"], locale: "it" });
-    expect(scope).not.toBeNull();
-    expect(scope!.t("default", "greeting")).toBe("Ciao");
-    expect(scope!.t("billing", "invoice")).toBe("Fattura");
-  });
-
-  it("peek returns scope after hydrate seed without invoking loaders", async () => {
-    const defaultLoader = vi.fn(async (locale: string) => ({
-      greeting: { [locale]: "Hello" },
-    }));
-    const billingLoader = vi.fn(async (locale: string) => ({
-      invoice: { [locale]: "Invoice" },
-    }));
-
-    const ssrEngine = new IcuTranslationProviderMulti<MultiSchema, MultiParams>({});
-    const ssr = createI18nHandle(ssrEngine, {
-      namespaceLoaders: { default: defaultLoader, billing: billingLoader },
-    });
-    await ssr.load({ namespaces: ["default", "billing"], locale: "en" });
-    const serialized = ssr.serialize();
-
-    const csrEngine = new IcuTranslationProviderMulti<MultiSchema, MultiParams>(
-      serialized.dictionary
-    );
-    csrEngine.seedBuilderResources(serialized.resources);
-    const csr = createI18nHandle(csrEngine, {
-      namespaceLoaders: { default: defaultLoader, billing: billingLoader },
-    });
-
-    const sync = csr.peek({ namespaces: ["default", "billing"], locale: "en" });
-    expect(sync).not.toBeNull();
-    expect(sync!.t("default", "greeting")).toBe("Hello");
-    expect(defaultLoader).toHaveBeenCalledTimes(1);
-    expect(billingLoader).toHaveBeenCalledTimes(1);
-
-    expect(csr.peek({ namespaces: ["default"], locale: "it" })).toBeNull();
-  });
-});

package/src/serialized-state.ts

@@ -1,28 +0,0 @@
-import type { BuilderResourceEntry } from "./builder-load-registry.js";
-
-/**
- * Portable i18n instance state after `serialize()`: dictionary strings + which
- * builder resources are already loaded (namespace × partition).
- */
-export interface I18nSerializedState<Dictionary = Record<string, unknown>> {
-  dictionary: Dictionary;
-  resources: readonly BuilderResourceEntry[];
-}
-
-/**
- * Input nested under generated `createI18n({ state? })`. Omitted `state` defaults to an empty
- * dictionary (lazy cold start). `resources` may be omitted or `[]`.
- */
-export type I18nCreateInput<Dictionary = Record<string, unknown>> = {
-  dictionary: Dictionary;
-  resources?: readonly BuilderResourceEntry[];
-};
-
-export function normalizeI18nCreateInput<Dictionary>(
-  value?: I18nCreateInput<Dictionary>
-): I18nSerializedState<Dictionary> {
-  return {
-    dictionary: value?.dictionary ?? ({} as Dictionary),
-    resources: value?.resources ?? [],
-  };
-}

package/src/setup/setup-i18n.test.ts

@@ -1,85 +0,0 @@
-import { mkdtempSync, readFileSync, rmSync, existsSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { describe, expect, it, afterEach } from "vitest";
-import { buildCodegenConfig, parseSetupArgs, runSetup } from "./setup-i18n.js";
-import { inferProjectName, typeNamesForProject } from "../codegen-config/type-names.js";
-
-describe("type-names", () => {
-  it("derives PascalCase project names from directory names", () => {
-    expect(inferProjectName("myapp")).toBe("Myapp");
-    expect(inferProjectName("my-app")).toBe("MyApp");
-    expect(inferProjectName("apps")).toBe("Apps");
-  });
-
-  it("builds type names from project prefix", () => {
-    expect(typeNamesForProject("MyApp")).toEqual({
-      paramsTypeName: "MyAppParams",
-      schemaTypeName: "MyAppSchema",
-      localeTypeName: "MyAppLocale",
-    });
-  });
-});
-
-describe("setup-i18n", () => {
-  let tempDir: string;
-
-  afterEach(() => {
-    if (tempDir) {
-      rmSync(tempDir, { recursive: true, force: true });
-    }
-  });
-
-  it("accepts multi alias or positional targetDir", () => {
-    expect(parseSetupArgs(["multi", "apps/myapp", "--project", "MyApp", "--force"])).toEqual({
-      targetDir: "apps/myapp",
-      project: "MyApp",
-      force: true,
-    });
-    expect(parseSetupArgs([".", "--project", "MyApp"])).toEqual({
-      targetDir: ".",
-      project: "MyApp",
-      force: false,
-    });
-  });
-
-  it("scaffolds multi mode with projectName and codegenPath", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-setup-"));
-    const result = runSetup({ targetDir: tempDir, project: "MyApp" });
-
-    const config = JSON.parse(readFileSync(join(tempDir, "i18n/i18n.codegen.json"), "utf8"));
-    expect(config.namespaces).toEqual({
-      default: "translations/default.json",
-    });
-    expect(config.projectName).toBe("MyApp");
-    expect(config.codegenPath).toBe("generated");
-    expect(config).not.toHaveProperty("paramsTypeName");
-    expect(existsSync(join(tempDir, "i18n/translations/default.json"))).toBe(true);
-    expect(existsSync(join(tempDir, "i18n/index.ts"))).toBe(true);
-    expect(existsSync(join(tempDir, "src"))).toBe(false);
-    expect(result.created).toContain("i18n/i18n.codegen.json");
-  });
-
-  it("scaffolds under src/i18n when targetDir is src", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-setup-"));
-    const srcDir = join(tempDir, "src");
-    runSetup({ targetDir: srcDir, project: "MyApp" });
-
-    expect(existsSync(join(srcDir, "i18n/i18n.codegen.json"))).toBe(true);
-    expect(existsSync(join(tempDir, "i18n"))).toBe(false);
-  });
-
-  it("refuses to overwrite an existing config without --force", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-setup-"));
-    runSetup({ targetDir: tempDir, project: "MyApp" });
-
-    expect(() => runSetup({ targetDir: tempDir, project: "MyApp" })).toThrow("already exists");
-  });
-
-  it("buildCodegenConfig defaults to split-by-locale", () => {
-    const config = buildCodegenConfig("MyApp");
-    expect(config.delivery).toBe("split-by-locale");
-    expect(config.codegenPath).toBe("generated");
-    expect(config.projectName).toBe("MyApp");
-  });
-});