@xndrjs/i18n 0.2.0 → 0.3.0

package/src/icu/extract-variables.test.ts

@@ -0,0 +1,199 @@
+import { parse } from "@formatjs/icu-messageformat-parser";
+import { describe, expect, it } from "vitest";
+import {
+  extractVariableMeta,
+  inferMergedVariableType,
+  mergeVariableMetaAcrossLocales,
+  variableMetaToSpec,
+  type VariableRole,
+} from "./extract-variables.js";
+
+function metaFor(template: string) {
+  return extractVariableMeta(parse(template));
+}
+
+function mergeTemplates(...templates: string[]) {
+  return mergeVariableMetaAcrossLocales(templates.map((template) => metaFor(template)));
+}
+
+function roles(...items: VariableRole[]) {
+  return new Set(items);
+}
+
+describe("inferMergedVariableType", () => {
+  describe("string family", () => {
+    it.each<[VariableRole[], "string"]>([
+      [["simple"], "string"],
+      [["select"], "string"],
+      [["simple", "select"], "string"],
+    ])("accepts %j → %s", (items, expected) => {
+      expect(inferMergedVariableType(roles(...items))).toBe(expected);
+    });
+  });
+
+  describe("number family", () => {
+    it.each<[VariableRole[], "number"]>([
+      [["plural"], "number"],
+      [["selectordinal"], "number"],
+      [["number"], "number"],
+      [["simple", "plural"], "number"],
+      [["simple", "selectordinal"], "number"],
+      [["simple", "number"], "number"],
+      [["plural", "number"], "number"],
+      [["selectordinal", "number"], "number"],
+    ])("accepts %j → %s", (items, expected) => {
+      expect(inferMergedVariableType(roles(...items))).toBe(expected);
+    });
+  });
+
+  describe("date family", () => {
+    it.each<[VariableRole[], "date"]>([
+      [["date"], "date"],
+      [["time"], "date"],
+      [["date", "time"], "date"],
+    ])("accepts %j → %s", (items, expected) => {
+      expect(inferMergedVariableType(roles(...items))).toBe(expected);
+    });
+  });
+
+  describe("conflicts", () => {
+    it.each<{ label: string; roles: VariableRole[] }>([
+      { label: "plural + select", roles: ["plural", "select"] },
+      { label: "selectordinal + select", roles: ["selectordinal", "select"] },
+      { label: "plural + selectordinal", roles: ["plural", "selectordinal"] },
+      { label: "select + number", roles: ["select", "number"] },
+      { label: "select + simple + number", roles: ["select", "simple", "number"] },
+      { label: "plural + simple + select", roles: ["plural", "simple", "select"] },
+      { label: "date + simple", roles: ["date", "simple"] },
+      { label: "date + plural", roles: ["date", "plural"] },
+      { label: "time + select", roles: ["time", "select"] },
+      { label: "date + number", roles: ["date", "number"] },
+    ])("rejects $label", ({ roles: roleList }) => {
+      expect(inferMergedVariableType(roles(...roleList))).toBe("CONFLICT");
+    });
+  });
+});
+
+describe("mergeVariableMetaAcrossLocales", () => {
+  describe("compatible cross-locale merges", () => {
+    it("infers string for simple interpolation in every locale", () => {
+      const result = mergeTemplates("Welcome {name}!", "Benvenuto {name}!");
+
+      expect(result).toEqual({ ok: true, merged: { name: "string" } });
+    });
+
+    it("infers string when one locale uses select and another uses simple interpolation", () => {
+      const result = mergeTemplates(
+        "{gender, select, female {she} other {they}}",
+        "Pronome: {gender}"
+      );
+
+      expect(result).toEqual({ ok: true, merged: { gender: "string" } });
+      expect(variableMetaToSpec(metaFor("Pronome: {gender}"))).toEqual({ gender: "string" });
+      expect(variableMetaToSpec(metaFor("{gender, select, other {x}}"))).toEqual({
+        gender: "string",
+      });
+    });
+
+    it("infers number when English uses plural and Italian uses simple interpolation", () => {
+      const result = mergeTemplates(
+        "You have {count, plural, one {1 invoice} other {# invoices}}",
+        "Hai {count} fatture"
+      );
+
+      expect(result).toEqual({ ok: true, merged: { count: "number" } });
+      expect(variableMetaToSpec(metaFor("Hai {count} fatture"))).toEqual({ count: "string" });
+      expect(
+        variableMetaToSpec(metaFor("You have {count, plural, one {1 invoice} other {# invoices}}"))
+      ).toEqual({ count: "number" });
+    });
+
+    it("infers number when one locale uses selectordinal and another uses simple interpolation", () => {
+      const result = mergeTemplates(
+        "You finished {position, selectordinal, one {#st} other {#th}}",
+        "Sei al {position} posto"
+      );
+
+      expect(result).toEqual({ ok: true, merged: { position: "number" } });
+    });
+
+    it("infers number when one locale uses plural and another uses number format", () => {
+      const result = mergeTemplates(
+        "{amount, plural, one {1} other {#}}",
+        "Totale: {amount, number}"
+      );
+
+      expect(result).toEqual({ ok: true, merged: { amount: "number" } });
+    });
+
+    it("infers date when locales use date and time on the same variable", () => {
+      const result = mergeTemplates("{due, date, short}", "{due, time, short}");
+
+      expect(result).toEqual({ ok: true, merged: { due: "date" } });
+    });
+  });
+
+  describe("incompatible cross-locale merges", () => {
+    it("rejects plural and select on the same variable", () => {
+      const result = mergeTemplates(
+        "{myVar, select, other {x}}",
+        "{myVar, plural, one {1} other {#}}"
+      );
+
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.message).toContain('Incompatible ICU variable "myVar"');
+      }
+    });
+
+    it("rejects plural and selectordinal on the same variable", () => {
+      const result = mergeTemplates(
+        "{rank, plural, one {1} other {#}}",
+        "{rank, selectordinal, one {#st} other {#th}}"
+      );
+
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.message).toContain('Incompatible ICU variable "rank"');
+        expect(result.message).toContain("plural");
+        expect(result.message).toContain("selectordinal");
+      }
+    });
+
+    it("rejects select and number format on the same variable", () => {
+      const result = mergeTemplates("{value, select, other {x}}", "Valore: {value, number}");
+
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.message).toContain('Incompatible ICU variable "value"');
+      }
+    });
+
+    it("rejects date and simple interpolation on the same variable", () => {
+      const result = mergeTemplates("{due, date, short}", "Scadenza {due}");
+
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.message).toContain('Incompatible ICU variable "due"');
+      }
+    });
+
+    it("rejects different variable names across locales", () => {
+      const result = mergeTemplates("Welcome {name}!", "Benvenuto {nome}!");
+
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.message).toContain("Inconsistent ICU variable names across locales");
+      }
+    });
+
+    it("rejects when one locale omits a variable present in another", () => {
+      const result = mergeTemplates("Welcome {name}!", "{name} and {count}");
+
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.message).toContain("Inconsistent ICU variable names across locales");
+      }
+    });
+  });
+});

package/src/icu/extract-variables.ts

@@ -3,40 +3,79 @@ import type { parse } from "@formatjs/icu-messageformat-parser";
 export type VariableType = "string" | "number" | "date";
 export type VariableSpec = Record<string, VariableType>;
 
+export type VariableRole =
+  | "simple"
+  | "plural"
+  | "selectordinal"
+  | "select"
+  | "number"
+  | "date"
+  | "time";
+
+export type VariableMeta = {
+  type: VariableType;
+  roles: Set<VariableRole>;
+};
+
+export type VariableMetaSpec = Record<string, VariableMeta>;
+
 type IcuAst = ReturnType<typeof parse>;
 type IcuNode = IcuAst[number];
 
-function isNumericIcuNode(node: IcuNode): boolean {
-  if (node.type === 2) {
-    return true;
-  }
+function isPluralOrOrdinalNode(node: IcuNode): node is Extract<IcuNode, { type: 6 }> {
+  return node.type === 6 && "pluralType" in node && Boolean(node.pluralType);
+}
+
+function hasVariableName(node: IcuNode): node is Extract<IcuNode, { value: string }> {
+  return "value" in node && typeof node.value === "string";
+}
 
-  if (node.type === 6 && "pluralType" in node && node.pluralType) {
-    return true;
+function addVariableMeta(
+  variables: VariableMetaSpec,
+  name: string,
+  type: VariableType,
+  role: VariableRole
+): void {
+  const existing = variables[name];
+  if (!existing) {
+    variables[name] = { type, roles: new Set([role]) };
+    return;
   }
 
-  return false;
+  existing.roles.add(role);
+  existing.type = mergeVariableTypes(existing.type, type);
 }
 
-function hasVariableName(node: IcuNode): node is Extract<IcuNode, { value: string }> {
-  return "value" in node && typeof node.value === "string";
+function mergeVariableTypes(left: VariableType, right: VariableType): VariableType {
+  if (left === right) {
+    return left;
+  }
+
+  if ((left === "string" && right === "number") || (left === "number" && right === "string")) {
+    return "number";
+  }
+
+  return right;
 }
 
-export function extractVariables(nodes: IcuAst): VariableSpec {
-  const variables: VariableSpec = {};
+export function extractVariableMeta(nodes: IcuAst): VariableMetaSpec {
+  const variables: VariableMetaSpec = {};
 
   const walk = (walkNodes: IcuAst) => {
     for (const node of walkNodes) {
-      if (node.type === 1) {
-        variables[node.value] = variables[node.value] ?? "string";
-      } else if (isNumericIcuNode(node) && hasVariableName(node)) {
-        variables[node.value] = "number";
-      } else if ((node.type === 3 || node.type === 4) && hasVariableName(node)) {
-        variables[node.value] = "date";
+      if (node.type === 1 && hasVariableName(node)) {
+        addVariableMeta(variables, node.value, "string", "simple");
+      } else if (node.type === 2 && hasVariableName(node)) {
+        addVariableMeta(variables, node.value, "number", "number");
+      } else if (isPluralOrOrdinalNode(node) && hasVariableName(node)) {
+        const role = node.pluralType === "ordinal" ? "selectordinal" : "plural";
+        addVariableMeta(variables, node.value, "number", role);
+      } else if (node.type === 3 && hasVariableName(node)) {
+        addVariableMeta(variables, node.value, "date", "date");
+      } else if (node.type === 4 && hasVariableName(node)) {
+        addVariableMeta(variables, node.value, "date", "time");
       } else if (node.type === 5 && hasVariableName(node)) {
-        variables[node.value] = variables[node.value] ?? "string";
-      } else if (node.type === 6 && hasVariableName(node)) {
-        variables[node.value] = variables[node.value] ?? "string";
+        addVariableMeta(variables, node.value, "string", "select");
       }
 
       if ("options" in node && node.options) {
@@ -55,6 +94,107 @@ export function extractVariables(nodes: IcuAst): VariableSpec {
   return variables;
 }
 
+export function variableMetaToSpec(meta: VariableMetaSpec): VariableSpec {
+  return Object.fromEntries(Object.entries(meta).map(([name, entry]) => [name, entry.type]));
+}
+
+export function extractVariables(nodes: IcuAst): VariableSpec {
+  return variableMetaToSpec(extractVariableMeta(nodes));
+}
+
+export function inferMergedVariableType(roles: Set<VariableRole>): VariableType | "CONFLICT" {
+  const hasPlural = roles.has("plural");
+  const hasSelectordinal = roles.has("selectordinal");
+  const hasSelect = roles.has("select");
+  const hasSimple = roles.has("simple");
+  const hasNumber = roles.has("number");
+  const hasDate = roles.has("date");
+  const hasTime = roles.has("time");
+
+  // Incompatible numeric ICU constructs on the same variable.
+  if (hasPlural && hasSelectordinal) {
+    return "CONFLICT";
+  }
+
+  // Select (string-family) vs plural / ordinal / number-format (number-family).
+  if (hasSelect && (hasPlural || hasSelectordinal || hasNumber)) {
+    return "CONFLICT";
+  }
+
+  // Legacy explicit pairs — covered by the rule above, kept for clarity.
+  if (hasPlural && hasSelect) {
+    return "CONFLICT";
+  }
+
+  if (hasSelectordinal && hasSelect) {
+    return "CONFLICT";
+  }
+
+  if (hasDate || hasTime) {
+    if (hasPlural || hasSelect || hasSelectordinal || hasSimple || hasNumber) {
+      return "CONFLICT";
+    }
+    return "date";
+  }
+
+  if (hasPlural || hasSelectordinal || hasNumber) {
+    return "number";
+  }
+
+  if (hasSelect || hasSimple) {
+    return "string";
+  }
+
+  return "string";
+}
+
+export function mergeVariableMetaAcrossLocales(
+  localeMetas: readonly VariableMetaSpec[]
+): { ok: true; merged: VariableSpec } | { ok: false; message: string } {
+  const keySignatures = localeMetas.map((meta) => Object.keys(meta).sort().join(","));
+  if (new Set(keySignatures).size > 1) {
+    return {
+      ok: false,
+      message: `Inconsistent ICU variable names across locales (keys: ${keySignatures.join(" vs ")})`,
+    };
+  }
+
+  const merged: VariableSpec = {};
+  const variableNames = new Set(localeMetas.flatMap((meta) => Object.keys(meta)));
+
+  for (const variableName of variableNames) {
+    const combinedRoles = new Set<VariableRole>();
+
+    for (const meta of localeMetas) {
+      for (const role of meta[variableName]?.roles ?? []) {
+        combinedRoles.add(role);
+      }
+    }
+
+    const mergedType = inferMergedVariableType(combinedRoles);
+    if (mergedType === "CONFLICT") {
+      const rolesByLocale = localeMetas
+        .map((meta) => {
+          const entry = meta[variableName];
+          if (!entry) {
+            return null;
+          }
+          return [...entry.roles].sort().join("|");
+        })
+        .filter((value): value is string => value !== null);
+
+      return {
+        ok: false,
+        message: `Incompatible ICU variable "${variableName}" across locales (roles: ${rolesByLocale.join(" vs ")})`,
+      };
+    }
+
+    merged[variableName] = mergedType;
+  }
+
+  return { ok: true, merged };
+}
+
 export function mergeVariableSpecs(target: VariableSpec, source: VariableSpec): VariableSpec {
   const merged = { ...target };
 

package/src/icu/parse-template.ts

@@ -1,9 +1,15 @@
 import { parse } from "@formatjs/icu-messageformat-parser";
-import { extractVariables, type VariableSpec } from "./extract-variables.js";
+import {
+  extractVariableMeta,
+  variableMetaToSpec,
+  type VariableMetaSpec,
+  type VariableSpec,
+} from "./extract-variables.js";
 
 export type ParseTemplateSuccess = {
   readonly ok: true;
   readonly args: VariableSpec;
+  readonly meta: VariableMetaSpec;
 };
 
 export type ParseTemplateFailure = {
@@ -16,7 +22,8 @@ export type ParseTemplateResult = ParseTemplateSuccess | ParseTemplateFailure;
 export function parseTemplate(template: string): ParseTemplateResult {
   try {
     const ast = parse(template);
-    return { ok: true, args: extractVariables(ast) };
+    const meta = extractVariableMeta(ast);
+    return { ok: true, args: variableMetaToSpec(meta), meta };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     return { ok: false, message };

package/src/setup/setup-i18n.ts

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { DEFAULT_IMPORT_EXTENSION, importExtensionSuffix } from "../codegen/paths.js";
 import { inferProjectName, typeNamesForProject } from "./type-names.js";
 
 export type SetupMode = "single" | "multi";
@@ -28,11 +29,13 @@ const DEFAULT_STARTER = {
   welcome: { en: "Welcome {name}!" },
 };
 
+const DEFAULT_IMPORT_SUFFIX = importExtensionSuffix(DEFAULT_IMPORT_EXTENSION);
+
 const INDEX_TS =
-  `import { createI18n } from "./generated/instance.generated.js";\n\n` +
-  `export * from "./generated/instance.generated.js";\n` +
-  `export * from "./generated/dictionary.generated.js";\n` +
-  `export * from "./generated/i18n-types.generated.js";\n\n` +
+  `import { createI18n } from "./generated/instance.generated${DEFAULT_IMPORT_SUFFIX}";\n\n` +
+  `export * from "./generated/instance.generated${DEFAULT_IMPORT_SUFFIX}";\n` +
+  `export * from "./generated/dictionary.generated${DEFAULT_IMPORT_SUFFIX}";\n` +
+  `export * from "./generated/i18n-types.generated${DEFAULT_IMPORT_SUFFIX}";\n\n` +
   `export const i18n = createI18n();\n`;
 
 function writeJson(filePath: string, value: unknown): void {

package/src/validation/normalize.ts

@@ -1,4 +1,4 @@
-import { variableSpecsEqual } from "../icu/extract-variables.js";
+import { mergeVariableMetaAcrossLocales, type VariableMetaSpec } from "../icu/extract-variables.js";
 import { parseTemplate } from "../icu/parse-template.js";
 import type {
   DictionarySpec,
@@ -45,8 +45,9 @@ function normalizeKeyDictionary(
     }
 
     const locales: Record<string, ParsedKeyEntry["locales"][string]> = {};
+    const localeMetas: VariableMetaSpec[] = [];
     let mergedArgs: ParsedKeyEntry["mergedArgs"] = {};
-    let hasLocaleArgs = false;
+    let localeArgsMismatch: ValidationIssue | undefined;
 
     for (const [locale, template] of Object.entries(keyValue)) {
       const localePath = [...keyPathPrefix, key, locale];
@@ -71,25 +72,31 @@ function normalizeKeyDictionary(
       }
 
       locales[locale] = { template, args: parsed.args };
+      localeMetas.push(parsed.meta);
+    }
 
-      if (!hasLocaleArgs) {
-        mergedArgs = { ...parsed.args };
-        hasLocaleArgs = true;
-      } else if (!variableSpecsEqual(mergedArgs, parsed.args)) {
+    if (localeMetas.length > 0) {
+      const merged = mergeVariableMetaAcrossLocales(localeMetas);
+      if (!merged.ok) {
         const localeArgs: Record<string, ParsedKeyEntry["mergedArgs"]> = {};
         for (const [loc, entry] of Object.entries(locales)) {
           localeArgs[loc] = entry.args;
         }
-        issues.push({
+        localeArgsMismatch = {
           kind: "locale_args_mismatch",
           path: [...keyPathPrefix, key],
           locales: localeArgs,
-          message: `Inconsistent ICU variables across locales for key "${key}"`,
-        });
-        break;
+          message: merged.message,
+        };
+      } else {
+        mergedArgs = merged.merged;
       }
     }
 
+    if (localeArgsMismatch) {
+      issues.push(localeArgsMismatch);
+    }
+
     keys[key] = { locales, mergedArgs };
   }
 

package/src/validation/validation.test.ts

@@ -87,6 +87,110 @@ describe("normalizeDictionary", () => {
       expect(result.issues[0]?.kind).toBe("locale_args_mismatch");
     }
   });
+
+  it("accepts plural in one locale and simple interpolation in another for the same variable", () => {
+    const result = normalizeDictionary(
+      {
+        login_button: { en: "Login" },
+        welcome: { en: "Welcome {name}!" },
+        invoice_count: {
+          en: "You have {count, plural, one {1 invoice} other {# invoices}}",
+          it: "Hai {count} fatture",
+        },
+      },
+      spec
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok && result.data.mode === "single") {
+      expect(result.data.keys.invoice_count?.mergedArgs).toEqual({ count: "number" });
+    }
+  });
+
+  it("rejects plural and select on the same variable across locales", () => {
+    const result = normalizeDictionary(
+      {
+        login_button: { en: "Login" },
+        welcome: { en: "Welcome {name}!" },
+        invoice_count: {
+          en: "{count, select, other {{count}}}",
+          it: "{count, plural, one {1} other {#}}",
+        },
+      },
+      spec
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.issues.some((issue) => issue.kind === "locale_args_mismatch")).toBe(true);
+    }
+  });
+
+  it("rejects plural and selectordinal on the same variable across locales", () => {
+    const result = normalizeDictionary(
+      {
+        login_button: { en: "Login" },
+        welcome: { en: "Welcome {name}!" },
+        invoice_count: {
+          en: "{count, plural, one {1} other {#}}",
+          it: "{count, selectordinal, one {#°} other {#°}}",
+        },
+      },
+      spec
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.issues.some((issue) => issue.kind === "locale_args_mismatch")).toBe(true);
+    }
+  });
+
+  it("rejects select and number format on the same variable across locales", () => {
+    const result = normalizeDictionary(
+      {
+        login_button: { en: "Login" },
+        welcome: { en: "Welcome {name}!" },
+        invoice_count: {
+          en: "{count, select, other {x}}",
+          it: "{count, number}",
+        },
+      },
+      spec
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.issues.some((issue) => issue.kind === "locale_args_mismatch")).toBe(true);
+    }
+  });
+
+  it("accepts select in one locale and simple interpolation in another", () => {
+    const result = normalizeDictionary(
+      {
+        login_button: { en: "Login" },
+        welcome: {
+          en: "{gender, select, female {she} other {they}}",
+          it: "Pronome: {gender}",
+        },
+        invoice_count: {
+          en: "You have {count, plural, one {1 invoice} other {# invoices}}",
+        },
+      },
+      {
+        ...spec,
+        requiredKeys: ["login_button", "welcome", "invoice_count"],
+        argsByKey: {
+          ...spec.argsByKey,
+          welcome: { gender: "string" },
+        },
+      }
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok && result.data.mode === "single") {
+      expect(result.data.keys.welcome?.mergedArgs).toEqual({ gender: "string" });
+    }
+  });
 });
 
 describe("validateNormalizedDictionary", () => {