@xndrjs/i18n 0.8.1 → 0.8.2-alpha.1

package/src/setup/setup-i18n.ts

@@ -1,156 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { buildCodegenConfig } from "../codegen-config/build-config.js";
-import { inferProjectName } from "../codegen-config/type-names.js";
-import { writeCodegenConfig } from "../codegen-config/write-config.js";
-import { DEFAULT_IMPORT_EXTENSION, importExtensionSuffix } from "../codegen/paths.js";
-
-export { buildCodegenConfig } from "../codegen-config/build-config.js";
-
-export interface SetupOptions {
-  targetDir: string;
-  project?: string | undefined;
-  force?: boolean | undefined;
-}
-
-export interface SetupResult {
-  targetDir: string;
-  project: string;
-  created: string[];
-}
-
-const I18N_ROOT = "i18n";
-const CONFIG_FILE = `${I18N_ROOT}/i18n.codegen.json`;
-/** Paths in i18n.codegen.json are relative to the i18n/ folder */
-const GENERATED_DIR = "generated";
-const TRANSLATIONS_DIR = "translations";
-
-const DEFAULT_STARTER = {
-  welcome: { en: "Welcome {name}!" },
-};
-
-const DEFAULT_IMPORT_SUFFIX = importExtensionSuffix(DEFAULT_IMPORT_EXTENSION);
-
-const INDEX_TS =
-  `import { createI18n } from "./generated/instance.generated${DEFAULT_IMPORT_SUFFIX}";\n\n` +
-  `export * from "./generated/instance.generated${DEFAULT_IMPORT_SUFFIX}";\n` +
-  `export * from "./generated/i18n-types.generated${DEFAULT_IMPORT_SUFFIX}";\n` +
-  `export * from "./generated/namespace-loaders.generated${DEFAULT_IMPORT_SUFFIX}";\n\n` +
-  `export const i18n = createI18n();\n`;
-
-function writeJson(filePath: string, value: unknown): void {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
-}
-
-function writeText(filePath: string, content: string): void {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, content);
-}
-
-function relative(fromRoot: string, filePath: string): string {
-  return path.relative(fromRoot, filePath).replace(/\\/g, "/");
-}
-
-export function runSetup(options: SetupOptions): SetupResult {
-  const targetDir = path.resolve(options.targetDir);
-  const project =
-    options.project ?? inferProjectName(path.basename(targetDir.replace(/[/\\]$/, "") || "app"));
-
-  if (!/^[A-Z][a-zA-Z0-9]*$/.test(project)) {
-    throw new Error(
-      `[Setup Error] Invalid project name "${project}". Use PascalCase (e.g. MyApp) via --project.`
-    );
-  }
-
-  const configPath = path.join(targetDir, CONFIG_FILE);
-  if (fs.existsSync(configPath) && !options.force) {
-    throw new Error(
-      `[Setup Error] ${relative(process.cwd(), configPath)} already exists. Use --force to overwrite.`
-    );
-  }
-
-  const created: string[] = [];
-
-  writeCodegenConfig(configPath, buildCodegenConfig(project));
-  created.push(relative(targetDir, configPath));
-
-  const defaultPath = path.join(targetDir, I18N_ROOT, TRANSLATIONS_DIR, "default.json");
-  writeJson(defaultPath, DEFAULT_STARTER);
-  created.push(relative(targetDir, defaultPath));
-
-  const indexPath = path.join(targetDir, I18N_ROOT, "index.ts");
-  writeText(indexPath, INDEX_TS);
-  created.push(relative(targetDir, indexPath));
-
-  fs.mkdirSync(path.join(targetDir, I18N_ROOT, GENERATED_DIR), { recursive: true });
-
-  return { targetDir, project, created };
-}
-
-export function parseSetupArgs(argv: string[]): SetupOptions {
-  const first = argv[0];
-
-  let targetDir = ".";
-  let project: string | undefined;
-  let force = false;
-  let startIndex = 0;
-
-  if (first === "multi") {
-    startIndex = 1;
-  } else if (first !== undefined && !first.startsWith("-")) {
-    // positional targetDir without mode
-  } else if (first === undefined || first.startsWith("-")) {
-    // flags only / empty
-  }
-
-  for (let index = startIndex; index < argv.length; index++) {
-    const arg = argv[index]!;
-    if (arg === "--project") {
-      project = argv[++index];
-      if (!project) {
-        throw new Error("[Setup Error] --project requires a value.");
-      }
-      continue;
-    }
-    if (arg === "--force") {
-      force = true;
-      continue;
-    }
-    if (arg.startsWith("-")) {
-      throw new Error(`[Setup Error] Unknown flag: ${arg}`);
-    }
-    targetDir = arg;
-  }
-
-  return { targetDir, project, force };
-}
-
-function main() {
-  try {
-    const options = parseSetupArgs(process.argv.slice(2));
-    const result = runSetup(options);
-
-    console.log(`✅ Setup i18n in ${result.targetDir}`);
-    console.log(
-      `   Project types: ${result.project}Params, ${result.project}Schema, ${result.project}Locale`
-    );
-    console.log(`   Created: ${result.created.join(", ")}`);
-    const targetLabel = path.relative(process.cwd(), result.targetDir) || ".";
-
-    console.log("");
-    console.log(`Add to package.json scripts (from ${targetLabel}):`);
-    console.log(`  "i18n:codegen": "xndrjs-i18n-codegen --config ${CONFIG_FILE}"`);
-    console.log("");
-    console.log("Then run your package manager's run script (pnpm/npm/yarn).");
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    console.error(message);
-    process.exit(1);
-  }
-}
-
-if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
-  main();
-}

package/src/types.ts

@@ -1,65 +0,0 @@
-import type { IntlMessageFormat } from "intl-messageformat";
-
-export type LocaleDictionary = Record<string, string>;
-export type KeyDictionary = Record<string, LocaleDictionary>;
-export type MultiDictionary = Record<string, KeyDictionary>;
-
-/** Locales present on any key of a flat (per-namespace) key dictionary. */
-export type LocaleOfKeys<Schema extends KeyDictionary> = {
-  [K in keyof Schema]: keyof Schema[K];
-}[keyof Schema] &
-  string;
-
-export type LocaleOfMulti<Schema extends MultiDictionary> = {
-  [NS in keyof Schema]: {
-    [K in keyof Schema[NS]]: keyof Schema[NS][K];
-  }[keyof Schema[NS]];
-}[keyof Schema] &
-  string;
-
-/** Subset of schema keys with any subset of project locales per key — valid input for merge operations. */
-export type PartialKeyDictionary<
-  T extends KeyDictionary,
-  Locales extends string = LocaleOfKeys<T>,
-> = {
-  [K in keyof T]?: Partial<Record<Locales, string>>;
-};
-
-/** Subset of schema namespaces with partial keys/locales — valid input for multi merge operations. */
-export type PartialMultiDictionary<
-  T extends MultiDictionary,
-  Locales extends string = LocaleOfMulti<T>,
-> = {
-  [NS in keyof T]?: PartialKeyDictionary<T[NS], Locales>;
-};
-
-export type LocaleFallbackMap = Record<string, string | null>;
-
-export type MissingTranslationContext = {
-  /** Only set by the multi-namespace provider. */
-  namespace?: string;
-  key: string;
-  locale: string;
-  fallbackChain: string;
-};
-
-export type OnMissingTranslation =
-  | "throw"
-  | "key"
-  | ((context: MissingTranslationContext) => string);
-
-export type IcuTranslationProviderOptions<
-  Fallback extends LocaleFallbackMap | undefined = undefined,
-> = {
-  localeFallback?: Fallback;
-  /**
-   * Strategy when no template resolves for a key/locale (after walking the
-   * fallback chain). "throw" (default) raises an error, "key" returns the
-   * translation key itself, a function receives the context and returns the
-   * string to display. ICU syntax and formatting errors always throw.
-   */
-  onMissing?: OnMissingTranslation;
-};
-
-export type LocaleCache = Record<string, IntlMessageFormat>;
-export type MultiCompiledCache = Record<string, Record<string, LocaleCache>>;

package/src/validation/create-args-schema.ts

@@ -1,76 +0,0 @@
-import { z } from "zod";
-import type { VariableSpec, VariableType } from "../icu/extract-variables.js";
-
-export const variableTypeSchema = z.enum(["string", "number", "date"]);
-
-function formatVariableMismatch(expected: VariableSpec, found: VariableSpec): string {
-  const expectedKeys = Object.keys(expected).sort();
-  const foundKeys = Object.keys(found).sort();
-  return `Expected variables [${expectedKeys.join(", ")}], found [${foundKeys.join(", ")}]`;
-}
-
-export function createArgsSchema(expected: VariableSpec): z.ZodType<VariableSpec> {
-  return z.record(z.string(), variableTypeSchema).superRefine((found, ctx) => {
-    const expectedKeys = Object.keys(expected).sort();
-    const foundKeys = Object.keys(found).sort();
-
-    if (expectedKeys.join() !== foundKeys.join()) {
-      ctx.addIssue({
-        code: "custom",
-        message: formatVariableMismatch(expected, found),
-      });
-      return;
-    }
-
-    for (const [name, type] of Object.entries(expected)) {
-      if (found[name] !== type) {
-        ctx.addIssue({
-          code: "custom",
-          message: `Variable "${name}": expected ${type}, found ${found[name]}`,
-        });
-      }
-    }
-  });
-}
-
-export function mapArgsSchemaError(
-  expected: VariableSpec,
-  found: VariableSpec,
-  message: string,
-  path: readonly string[]
-) {
-  const expectedKeys = Object.keys(expected).sort();
-  const foundKeys = Object.keys(found).sort();
-
-  if (expectedKeys.join() !== foundKeys.join()) {
-    return {
-      kind: "variable_mismatch" as const,
-      path,
-      expected,
-      found,
-      message,
-    };
-  }
-
-  for (const [name, type] of Object.entries(expected)) {
-    const foundType = found[name];
-    if (foundType !== undefined && foundType !== type) {
-      return {
-        kind: "variable_type_mismatch" as const,
-        path,
-        variable: name,
-        expected: type,
-        found: foundType as VariableType,
-        message,
-      };
-    }
-  }
-
-  return {
-    kind: "variable_mismatch" as const,
-    path,
-    expected,
-    found,
-    message,
-  };
-}

package/src/validation/create-normalized-schema.ts

@@ -1,52 +0,0 @@
-import { z } from "zod";
-import type { VariableSpec } from "../icu/extract-variables.js";
-import { createArgsSchema, variableTypeSchema } from "./create-args-schema.js";
-import type { DictionarySpec, NormalizedDictionary, ParsedKeyEntry } from "./types.js";
-
-const parsedLocaleEntrySchema = z.object({
-  template: z.string(),
-  args: z.record(z.string(), variableTypeSchema),
-});
-
-const parsedKeyEntrySchema = z.object({
-  locales: z.record(z.string(), parsedLocaleEntrySchema),
-  mergedArgs: z.record(z.string(), variableTypeSchema),
-});
-
-export function createKeyDictionarySchema(
-  argsByKey: Readonly<Record<string, VariableSpec>>
-): z.ZodType<Record<string, ParsedKeyEntry>> {
-  const keySchemas = Object.fromEntries(
-    Object.entries(argsByKey).map(([key, expectedArgs]) => [
-      key,
-      parsedKeyEntrySchema.extend({
-        mergedArgs: createArgsSchema(expectedArgs),
-      }),
-    ])
-  );
-
-  return z.object(keySchemas);
-}
-
-export function createNormalizedDictionarySchema(
-  spec: DictionarySpec
-): z.ZodType<NormalizedDictionary> {
-  if (spec.mode === "single") {
-    return z.object({
-      mode: z.literal("single"),
-      keys: createKeyDictionarySchema(spec.argsByKey),
-    }) as z.ZodType<NormalizedDictionary>;
-  }
-
-  const namespaceSchemas = Object.fromEntries(
-    Object.entries(spec.argsByKey).map(([namespace, argsByKey]) => [
-      namespace,
-      createKeyDictionarySchema(argsByKey),
-    ])
-  );
-
-  return z.object({
-    mode: z.literal("multi"),
-    namespaces: z.object(namespaceSchemas),
-  }) as z.ZodType<NormalizedDictionary>;
-}

package/src/validation/errors.ts

@@ -1,43 +0,0 @@
-import type { ValidationIssue, ValidationResult } from "./types.js";
-
-function issueMessage(issue: ValidationIssue): string {
-  switch (issue.kind) {
-    case "missing_key":
-      return `Missing required key at ${issue.path.join(".")}`;
-    case "unknown_key":
-      return `Unknown key at ${issue.path.join(".")}`;
-    case "invalid_input":
-    case "invalid_locale_value":
-    case "icu_syntax_error":
-    case "locale_args_mismatch":
-    case "variable_mismatch":
-    case "variable_type_mismatch":
-      return issue.message;
-  }
-}
-
-export function formatIssues(issues: readonly ValidationIssue[]): string {
-  return issues
-    .map((issue) => {
-      if ("path" in issue && issue.path.length > 0) {
-        return `[${issue.path.join(".")}] ${issue.kind}: ${issueMessage(issue)}`;
-      }
-      return `${issue.kind}: ${issueMessage(issue)}`;
-    })
-    .join("\n");
-}
-
-export class DictionaryValidationError extends Error {
-  constructor(public readonly issues: readonly ValidationIssue[]) {
-    super(formatIssues(issues));
-    this.name = "DictionaryValidationError";
-  }
-}
-
-export function assertValidDictionary<T>(
-  result: ValidationResult<T>
-): asserts result is { ok: true; data: T } {
-  if (!result.ok) {
-    throw new DictionaryValidationError(result.issues);
-  }
-}

package/src/validation/index.ts

@@ -1,202 +0,0 @@
-/**
- * External payload validation for server-side codegen/ingest (CMS → authoring files).
- * Not a runtime patch API — validate before writing authoring, then `regenerateNamespaces` / `load()`.
- */
-import { normalizeDictionaryPartial, normalizeKeyDictionaryPartial } from "./normalize.js";
-import { toDictionary, toNamespaceDictionary } from "./to-dictionary.js";
-import type {
-  DictionarySpec,
-  NormalizedKeyDictionary,
-  ValidationIssue,
-  ValidationResult,
-} from "./types.js";
-import { validateNormalizedKeyDictionaryPartial } from "./validate-normalized.js";
-
-export function validateExternalDictionaryPartial<TSchema>(
-  input: unknown,
-  spec: DictionarySpec
-): ValidationResult<Partial<TSchema>> {
-  if (spec.mode === "single") {
-    const step1 = normalizeKeyDictionaryPartial(input, spec.requiredKeys, spec.argsByKey, []);
-    if (!step1.ok) {
-      return step1;
-    }
-
-    const step2 = validateNormalizedKeyDictionaryPartial(step1.data, spec.argsByKey, spec, []);
-    if (!step2.ok) {
-      return step2;
-    }
-
-    return {
-      ok: true,
-      data: toDictionary({ mode: "single", keys: step2.data }) as Partial<TSchema>,
-    };
-  }
-
-  const step1 = normalizeDictionaryPartial(input, spec);
-  if (!step1.ok) {
-    return step1;
-  }
-
-  if (step1.data.mode !== "multi") {
-    return {
-      ok: false,
-      issues: [
-        {
-          kind: "invalid_input",
-          message: "validateExternalDictionaryPartial requires multi-mode dictionary spec",
-        },
-      ],
-    };
-  }
-
-  const issues: ValidationIssue[] = [];
-  const namespaces: Record<string, NormalizedKeyDictionary> = {};
-
-  for (const [namespace, keys] of Object.entries(step1.data.namespaces)) {
-    const step2 = validateNormalizedKeyDictionaryPartial(
-      keys,
-      spec.argsByKey[namespace] ?? {},
-      spec,
-      [namespace]
-    );
-    if (!step2.ok) {
-      issues.push(...step2.issues);
-    } else {
-      namespaces[namespace] = step2.data;
-    }
-  }
-
-  if (issues.length > 0) {
-    return { ok: false, issues };
-  }
-
-  return {
-    ok: true,
-    data: toDictionary({ mode: "multi", namespaces }) as Partial<TSchema>,
-  };
-}
-
-export function validateExternalNamespacePartial<TNamespaceSchema>(
-  namespace: string,
-  input: unknown,
-  spec: DictionarySpec
-): ValidationResult<Partial<TNamespaceSchema>> {
-  if (spec.mode !== "multi") {
-    return {
-      ok: false,
-      issues: [
-        {
-          kind: "invalid_input",
-          message: "validateExternalNamespacePartial requires multi-mode dictionary spec",
-        },
-      ],
-    };
-  }
-
-  const knownKeys = spec.requiredKeys[namespace];
-  if (!knownKeys) {
-    return {
-      ok: false,
-      issues: [{ kind: "unknown_key", path: [namespace] }],
-    };
-  }
-
-  const step1 = normalizeKeyDictionaryPartial(input, knownKeys, spec.argsByKey[namespace] ?? {}, [
-    namespace,
-  ]);
-  if (!step1.ok) {
-    return step1;
-  }
-
-  const step2 = validateNormalizedKeyDictionaryPartial(
-    step1.data,
-    spec.argsByKey[namespace] ?? {},
-    spec,
-    [namespace]
-  );
-  if (!step2.ok) {
-    return step2;
-  }
-
-  return {
-    ok: true,
-    data: toNamespaceDictionary(
-      { mode: "multi", namespaces: { [namespace]: step2.data } },
-      namespace
-    ) as Partial<TNamespaceSchema>,
-  };
-}
-
-export function validateExternalKey<TKeySlice>(
-  key: string,
-  input: unknown,
-  spec: Extract<DictionarySpec, { mode: "single" }>
-): ValidationResult<TKeySlice>;
-
-export function validateExternalKey<TKeySlice>(
-  namespace: string,
-  key: string,
-  input: unknown,
-  spec: Extract<DictionarySpec, { mode: "multi" }>
-): ValidationResult<TKeySlice>;
-
-export function validateExternalKey<TKeySlice>(
-  namespaceOrKey: string,
-  keyOrInput: string | unknown,
-  inputOrSpec?: unknown,
-  specMaybe?: DictionarySpec
-): ValidationResult<TKeySlice> {
-  if (specMaybe?.mode === "multi") {
-    const namespace = namespaceOrKey;
-    const key = keyOrInput as string;
-    const input = inputOrSpec;
-    const spec = specMaybe;
-
-    return validateExternalNamespacePartial<TKeySlice>(
-      namespace,
-      { [key]: input },
-      spec
-    ) as ValidationResult<TKeySlice>;
-  }
-
-  const key = namespaceOrKey;
-  const input = keyOrInput;
-  const spec = inputOrSpec as Extract<DictionarySpec, { mode: "single" }>;
-
-  return validateExternalDictionaryPartial<TKeySlice>(
-    { [key]: input },
-    spec
-  ) as ValidationResult<TKeySlice>;
-}
-
-export {
-  normalizeDictionaryPartial,
-  normalizeKeyDictionaryPartial,
-  toDictionary,
-  toNamespaceDictionary,
-};
-export { validateNormalizedKeyDictionaryPartial } from "./validate-normalized.js";
-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";