@xndrjs/i18n 0.2.0-alpha.0

package/src/validation/index.ts

@@ -0,0 +1,90 @@
+import { normalizeDictionary } from "./normalize.js";
+import { toDictionary, toNamespaceDictionary } from "./to-dictionary.js";
+import type { DictionarySpec, NormalizedDictionary, ValidationResult } from "./types.js";
+import { validateNormalizedDictionary } from "./validate-normalized.js";
+
+export function validateExternalDictionary<TSchema>(
+  input: unknown,
+  spec: DictionarySpec
+): ValidationResult<TSchema> {
+  const step1 = normalizeDictionary(input, spec);
+  if (!step1.ok) {
+    return step1;
+  }
+
+  const step2 = validateNormalizedDictionary(step1.data, spec);
+  if (!step2.ok) {
+    return step2;
+  }
+
+  return { ok: true, data: toDictionary(step2.data) as TSchema };
+}
+
+export function validateExternalNamespace<TNamespaceSchema>(
+  namespace: string,
+  input: unknown,
+  spec: DictionarySpec
+): ValidationResult<TNamespaceSchema> {
+  if (spec.mode !== "multi") {
+    return {
+      ok: false,
+      issues: [
+        {
+          kind: "invalid_input",
+          message: "validateExternalNamespace requires multi-mode dictionary spec",
+        },
+      ],
+    };
+  }
+
+  const wrapped = { [namespace]: input };
+  const namespaceSpec: DictionarySpec = {
+    mode: "multi",
+    requiredKeys: {
+      [namespace]: spec.requiredKeys[namespace] ?? [],
+    },
+    argsByKey: {
+      [namespace]: spec.argsByKey[namespace] ?? {},
+    },
+  };
+
+  const step1 = normalizeDictionary(wrapped, namespaceSpec);
+  if (!step1.ok) {
+    return step1;
+  }
+
+  const step2 = validateNormalizedDictionary(step1.data, namespaceSpec);
+  if (!step2.ok) {
+    return step2;
+  }
+
+  return {
+    ok: true,
+    data: toNamespaceDictionary(step2.data, namespace) as TNamespaceSchema,
+  };
+}
+
+export { normalizeDictionary, validateNormalizedDictionary, toDictionary, toNamespaceDictionary };
+export { createArgsSchema } from "./create-args-schema.js";
+export { createNormalizedDictionarySchema } from "./create-normalized-schema.js";
+export { DictionaryValidationError, assertValidDictionary, formatIssues } from "./errors.js";
+export type {
+  DictionarySpec,
+  NormalizedDictionary,
+  NormalizedKeyDictionary,
+  NormalizedMultiDictionary,
+  ParsedKeyEntry,
+  ParsedLocaleEntry,
+  ValidationIssue,
+  ValidationResult,
+  VariableSpec,
+  VariableType,
+} from "./types.js";
+
+export type { ParseTemplateResult } from "../icu/parse-template.js";
+export { parseTemplate } from "../icu/parse-template.js";
+export {
+  extractVariables,
+  mergeVariableSpecs,
+  variableSpecsEqual,
+} from "../icu/extract-variables.js";

package/src/validation/normalize.ts

@@ -0,0 +1,158 @@
+import { variableSpecsEqual } from "../icu/extract-variables.js";
+import { parseTemplate } from "../icu/parse-template.js";
+import type {
+  DictionarySpec,
+  NormalizedDictionary,
+  NormalizedKeyDictionary,
+  ParsedKeyEntry,
+  ValidationIssue,
+  ValidationResult,
+} from "./types.js";
+
+function failure(issues: ValidationIssue[]): ValidationResult<NormalizedDictionary> {
+  return { ok: false, issues };
+}
+
+function success(data: NormalizedDictionary): ValidationResult<NormalizedDictionary> {
+  return { ok: true, data };
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeKeyDictionary(
+  input: Record<string, unknown>,
+  requiredKeys: readonly string[],
+  keyPathPrefix: readonly string[]
+): ValidationResult<NormalizedKeyDictionary> {
+  const issues: ValidationIssue[] = [];
+  const keys: Record<string, ParsedKeyEntry> = {};
+
+  for (const key of requiredKeys) {
+    if (!(key in input)) {
+      issues.push({ kind: "missing_key", path: [...keyPathPrefix, key] });
+      continue;
+    }
+
+    const keyValue = input[key];
+    if (!isPlainObject(keyValue)) {
+      issues.push({
+        kind: "invalid_input",
+        message: `Expected object for key "${key}", got ${typeof keyValue}`,
+      });
+      continue;
+    }
+
+    const locales: Record<string, ParsedKeyEntry["locales"][string]> = {};
+    let mergedArgs: ParsedKeyEntry["mergedArgs"] = {};
+    let hasLocaleArgs = false;
+
+    for (const [locale, template] of Object.entries(keyValue)) {
+      const localePath = [...keyPathPrefix, key, locale];
+
+      if (typeof template !== "string") {
+        issues.push({
+          kind: "invalid_locale_value",
+          path: localePath,
+          message: `expected string, got ${typeof template}`,
+        });
+        continue;
+      }
+
+      const parsed = parseTemplate(template);
+      if (!parsed.ok) {
+        issues.push({
+          kind: "icu_syntax_error",
+          path: localePath,
+          message: parsed.message,
+        });
+        continue;
+      }
+
+      locales[locale] = { template, args: parsed.args };
+
+      if (!hasLocaleArgs) {
+        mergedArgs = { ...parsed.args };
+        hasLocaleArgs = true;
+      } else if (!variableSpecsEqual(mergedArgs, parsed.args)) {
+        const localeArgs: Record<string, ParsedKeyEntry["mergedArgs"]> = {};
+        for (const [loc, entry] of Object.entries(locales)) {
+          localeArgs[loc] = entry.args;
+        }
+        issues.push({
+          kind: "locale_args_mismatch",
+          path: [...keyPathPrefix, key],
+          locales: localeArgs,
+          message: `Inconsistent ICU variables across locales for key "${key}"`,
+        });
+        break;
+      }
+    }
+
+    keys[key] = { locales, mergedArgs };
+  }
+
+  if (issues.length > 0) {
+    return { ok: false, issues };
+  }
+
+  return { ok: true, data: keys };
+}
+
+export function normalizeDictionary(
+  input: unknown,
+  spec: DictionarySpec
+): ValidationResult<NormalizedDictionary> {
+  if (!isPlainObject(input)) {
+    return failure([
+      {
+        kind: "invalid_input",
+        message: `Expected object, got ${input === null ? "null" : typeof input}`,
+      },
+    ]);
+  }
+
+  if (spec.mode === "single") {
+    const result = normalizeKeyDictionary(input, spec.requiredKeys, []);
+    if (!result.ok) {
+      return result;
+    }
+
+    return success({ mode: "single", keys: result.data });
+  }
+
+  const issues: ValidationIssue[] = [];
+  const namespaces: Record<string, NormalizedKeyDictionary> = {};
+
+  for (const [namespace, requiredKeys] of Object.entries(spec.requiredKeys)) {
+    if (!(namespace in input)) {
+      for (const key of requiredKeys) {
+        issues.push({ kind: "missing_key", path: [namespace, key] });
+      }
+      continue;
+    }
+
+    const namespaceValue = input[namespace];
+    if (!isPlainObject(namespaceValue)) {
+      issues.push({
+        kind: "invalid_input",
+        message: `Expected object for namespace "${namespace}", got ${typeof namespaceValue}`,
+      });
+      continue;
+    }
+
+    const result = normalizeKeyDictionary(namespaceValue, requiredKeys, [namespace]);
+    if (!result.ok) {
+      issues.push(...result.issues);
+    } else {
+      namespaces[namespace] = result.data;
+    }
+  }
+
+  if (issues.length > 0) {
+    return failure(issues);
+  }
+
+  return success({ mode: "multi", namespaces });
+}

package/src/validation/to-dictionary.ts

@@ -0,0 +1,67 @@
+import type { NormalizedDictionary } from "./types.js";
+
+type LocaleDictionary = Record<string, string>;
+type KeyDictionary = Record<string, LocaleDictionary>;
+type MultiDictionary = Record<string, KeyDictionary>;
+
+export function toDictionary(normalized: NormalizedDictionary): KeyDictionary | MultiDictionary {
+  if (normalized.mode === "single") {
+    const dictionary: KeyDictionary = {};
+
+    for (const [key, entry] of Object.entries(normalized.keys)) {
+      const locales: LocaleDictionary = {};
+      for (const [locale, localeEntry] of Object.entries(entry.locales)) {
+        locales[locale] = localeEntry.template;
+      }
+      dictionary[key] = locales;
+    }
+
+    return dictionary;
+  }
+
+  const dictionary: MultiDictionary = {};
+
+  for (const [namespace, keys] of Object.entries(normalized.namespaces)) {
+    const namespaceDictionary: KeyDictionary = {};
+
+    for (const [key, entry] of Object.entries(keys)) {
+      const locales: LocaleDictionary = {};
+      for (const [locale, localeEntry] of Object.entries(entry.locales)) {
+        locales[locale] = localeEntry.template;
+      }
+      namespaceDictionary[key] = locales;
+    }
+
+    dictionary[namespace] = namespaceDictionary;
+  }
+
+  return dictionary;
+}
+
+export function toNamespaceDictionary(
+  normalized: NormalizedDictionary,
+  namespace: string
+): KeyDictionary {
+  if (normalized.mode !== "multi") {
+    throw new Error(
+      `[i18n] toNamespaceDictionary requires multi-mode normalized dictionary, got "${normalized.mode}"`
+    );
+  }
+
+  const keys = normalized.namespaces[namespace];
+  if (!keys) {
+    return {};
+  }
+
+  const dictionary: KeyDictionary = {};
+
+  for (const [key, entry] of Object.entries(keys)) {
+    const locales: LocaleDictionary = {};
+    for (const [locale, localeEntry] of Object.entries(entry.locales)) {
+      locales[locale] = localeEntry.template;
+    }
+    dictionary[key] = locales;
+  }
+
+  return dictionary;
+}

package/src/validation/types.ts

@@ -0,0 +1,78 @@
+import type { VariableSpec, VariableType } from "../icu/extract-variables.js";
+
+export type { VariableSpec, VariableType };
+
+export type ParsedLocaleEntry = {
+  readonly template: string;
+  readonly args: VariableSpec;
+};
+
+export type ParsedKeyEntry = {
+  readonly locales: Readonly<Record<string, ParsedLocaleEntry>>;
+  readonly mergedArgs: VariableSpec;
+};
+
+export type NormalizedKeyDictionary = Readonly<Record<string, ParsedKeyEntry>>;
+
+export type NormalizedMultiDictionary = Readonly<Record<string, NormalizedKeyDictionary>>;
+
+export type NormalizedDictionary =
+  | { readonly mode: "single"; readonly keys: NormalizedKeyDictionary }
+  | { readonly mode: "multi"; readonly namespaces: NormalizedMultiDictionary };
+
+export type DictionarySpec =
+  | {
+      readonly mode: "single";
+      readonly requiredKeys: readonly string[];
+      readonly argsByKey: Readonly<Record<string, VariableSpec>>;
+    }
+  | {
+      readonly mode: "multi";
+      readonly requiredKeys: Readonly<Record<string, readonly string[]>>;
+      readonly argsByKey: Readonly<Record<string, Readonly<Record<string, VariableSpec>>>>;
+    };
+
+export type ValidationIssue =
+  | {
+      readonly kind: "invalid_input";
+      readonly message: string;
+    }
+  | {
+      readonly kind: "missing_key";
+      readonly path: readonly string[];
+    }
+  | {
+      readonly kind: "invalid_locale_value";
+      readonly path: readonly string[];
+      readonly message: string;
+    }
+  | {
+      readonly kind: "icu_syntax_error";
+      readonly path: readonly string[];
+      readonly message: string;
+    }
+  | {
+      readonly kind: "locale_args_mismatch";
+      readonly path: readonly string[];
+      readonly locales: Readonly<Record<string, VariableSpec>>;
+      readonly message: string;
+    }
+  | {
+      readonly kind: "variable_mismatch";
+      readonly path: readonly string[];
+      readonly expected: VariableSpec;
+      readonly found: VariableSpec;
+      readonly message: string;
+    }
+  | {
+      readonly kind: "variable_type_mismatch";
+      readonly path: readonly string[];
+      readonly variable: string;
+      readonly expected: VariableType;
+      readonly found: VariableType;
+      readonly message: string;
+    };
+
+export type ValidationResult<T> =
+  | { readonly ok: true; readonly data: T }
+  | { readonly ok: false; readonly issues: readonly ValidationIssue[] };

package/src/validation/validate-normalized.ts

@@ -0,0 +1,91 @@
+import type { ZodError } from "zod";
+import { mapArgsSchemaError } from "./create-args-schema.js";
+import { createNormalizedDictionarySchema } from "./create-normalized-schema.js";
+import type {
+  DictionarySpec,
+  NormalizedDictionary,
+  ValidationIssue,
+  ValidationResult,
+  VariableSpec,
+} from "./types.js";
+
+function getExpectedArgs(spec: DictionarySpec, path: readonly string[]): VariableSpec | undefined {
+  if (spec.mode === "single") {
+    const key = path[path.length - 1];
+    if (typeof key !== "string") {
+      return undefined;
+    }
+    return spec.argsByKey[key];
+  }
+
+  const namespace = path[0];
+  const key = path[path.length - 1];
+  if (typeof namespace !== "string" || typeof key !== "string") {
+    return undefined;
+  }
+
+  return spec.argsByKey[namespace]?.[key];
+}
+
+function getFoundArgs(
+  normalized: NormalizedDictionary,
+  path: readonly string[]
+): VariableSpec | undefined {
+  if (normalized.mode === "single") {
+    const key = path[path.length - 1];
+    if (typeof key !== "string") {
+      return undefined;
+    }
+    return normalized.keys[key]?.mergedArgs;
+  }
+
+  const namespace = path[0];
+  const key = path[path.length - 1];
+  if (typeof namespace !== "string" || typeof key !== "string") {
+    return undefined;
+  }
+
+  return normalized.namespaces[namespace]?.[key]?.mergedArgs;
+}
+
+function mapZodError(
+  error: ZodError,
+  spec: DictionarySpec,
+  normalized: NormalizedDictionary
+): ValidationIssue[] {
+  return error.issues.map((issue) => {
+    const path = issue.path.map(String);
+
+    if (path.includes("mergedArgs")) {
+      const keyPath = path.slice(0, path.indexOf("mergedArgs"));
+      const expected = getExpectedArgs(spec, keyPath);
+      const found = getFoundArgs(normalized, keyPath);
+
+      if (expected && found) {
+        return mapArgsSchemaError(expected, found, issue.message, keyPath);
+      }
+    }
+
+    return {
+      kind: "invalid_input" as const,
+      message: path.length > 0 ? `${path.join(".")}: ${issue.message}` : issue.message,
+    };
+  });
+}
+
+export function validateNormalizedDictionary(
+  normalized: NormalizedDictionary,
+  spec: DictionarySpec
+): ValidationResult<NormalizedDictionary> {
+  const schema = createNormalizedDictionarySchema(spec);
+  const result = schema.safeParse(normalized);
+
+  if (result.success) {
+    return { ok: true, data: result.data };
+  }
+
+  return {
+    ok: false,
+    issues: mapZodError(result.error, spec, normalized),
+  };
+}