@xndrjs/i18n 0.8.0 → 0.8.2-alpha.0

package/src/codegen/run-codegen.ts

@@ -1,252 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import {
-  loadConfig,
-  resolveArtifactsPath,
-  resolveCodegenPaths,
-  resolveNamespaces,
-} from "./config.js";
-import type { CodegenConfig } from "./codegen-config-schema.js";
-import {
-  formatDictionarySchemaFile,
-  formatDictionarySpecBlock,
-} from "./emit/dictionary-schema-file.js";
-import { formatInstanceFile } from "./emit/instance-file.js";
-import { formatNamespaceLoadersFile } from "./emit/namespace-loaders-file.js";
-import { formatTypesFile } from "./emit/types-file.js";
-import { analyzeDictionaries } from "./icu-analysis.js";
-import { getDeliveryArtifactsIssues } from "./delivery-artifacts.js";
-import { collectRequestLocales, getCodegenLocaleFallbackIssues } from "./locale-fallback.js";
-import { enrichLocaleFallback } from "./locale-policy.js";
-import { DEFAULT_IMPORT_EXTENSION, reportCodegenIssues, toModuleBasename } from "./paths.js";
-import { prepareDictionaryEntries } from "./read-dictionary.js";
-import { writeFileIfChanged } from "./write-file-if-changed.js";
-
-export type RunCodegenInput =
-  | string
-  | {
-      configPath?: string;
-      config?: CodegenConfig;
-      projectRoot?: string;
-      /** When false, skip console.log summaries (default true). */
-      log?: boolean;
-    };
-
-export interface RunCodegenResult {
-  projectRoot: string;
-  generatedFiles: string[];
-  compiledFiles: string[];
-}
-
-function resolveRunCodegenInput(input?: RunCodegenInput): {
-  projectRoot: string;
-  config: CodegenConfig;
-  log: boolean;
-} {
-  if (typeof input === "string" || input === undefined) {
-    const configPath = path.resolve(
-      process.cwd(),
-      typeof input === "string" ? input : "i18n/i18n.codegen.json"
-    );
-    if (!fs.existsSync(configPath)) {
-      throw new Error(`[Codegen Error] Config file not found: ${configPath}`);
-    }
-    return {
-      projectRoot: path.dirname(configPath),
-      config: loadConfig(configPath),
-      log: true,
-    };
-  }
-
-  const log = input.log !== false;
-
-  if (input.config !== undefined) {
-    const projectRoot = path.resolve(input.projectRoot ?? process.cwd());
-    return { projectRoot, config: input.config, log };
-  }
-
-  const configPath = path.resolve(process.cwd(), input.configPath ?? "i18n/i18n.codegen.json");
-  if (!fs.existsSync(configPath)) {
-    throw new Error(`[Codegen Error] Config file not found: ${configPath}`);
-  }
-  return {
-    projectRoot: path.dirname(configPath),
-    config: loadConfig(configPath),
-    log,
-  };
-}
-
-/**
- * Full codegen pipeline: types + instance + loaders + delivery JSON (+ schema).
- * Run at build time or when the *contract* changes (keys, params, namespaces, locales).
- * Content-only refreshes (same ICU contract) should use {@link regenerateNamespaces} instead.
- */
-export function runCodegen(input?: RunCodegenInput): RunCodegenResult {
-  const { projectRoot, config, log } = resolveRunCodegenInput(input);
-  const sourceEntries = resolveNamespaces(config);
-  const artifactsPathRelative = resolveArtifactsPath(config);
-  const delivery = config.delivery ?? "split-by-locale";
-  const loaderStrategy = config.loaderStrategy ?? "import";
-
-  const analysisResult = analyzeDictionaries(projectRoot, sourceEntries);
-  if (!analysisResult.ok) {
-    throw new Error("[Codegen Error] Dictionary ICU analysis failed. See messages above.");
-  }
-
-  const { paramsByNamespace, argsSpecByNamespace, locales, dictionariesByNamespace } =
-    analysisResult.analysis;
-
-  if (config.localeFallback) {
-    const localeFallbackIssues = getCodegenLocaleFallbackIssues(config.localeFallback, locales);
-    if (localeFallbackIssues.length > 0) {
-      reportCodegenIssues(localeFallbackIssues);
-      throw new Error("[Codegen Error] Invalid localeFallback configuration.");
-    }
-  }
-
-  const paths = resolveCodegenPaths(config);
-  const {
-    paramsTypeName,
-    schemaTypeName,
-    localeTypeName,
-    localeFallbackConstName,
-    factoryName,
-    deliveryAreaTypeName: resolvedDeliveryAreaTypeName,
-  } = paths;
-  const localeFallbackTypeName = `${localeTypeName}Fallback`;
-  const importExtension = DEFAULT_IMPORT_EXTENSION;
-
-  const requestLocales = collectRequestLocales(locales, config.localeFallback);
-  const requestLocalesList = [...requestLocales].sort();
-
-  if (delivery === "custom" && config.deliveryArtifacts) {
-    const deliveryArtifactsIssues = getDeliveryArtifactsIssues(
-      config.deliveryArtifacts,
-      requestLocales
-    );
-    if (deliveryArtifactsIssues.length > 0) {
-      reportCodegenIssues(deliveryArtifactsIssues);
-      throw new Error("[Codegen Error] Invalid deliveryArtifacts configuration.");
-    }
-  }
-
-  const {
-    resolvedEntries: entries,
-    splitPathsByNamespace,
-    compiledFiles,
-  } = prepareDictionaryEntries(projectRoot, sourceEntries, artifactsPathRelative, {
-    dictionariesByNamespace,
-    delivery,
-    localeFallback: config.localeFallback,
-    requestLocales: delivery === "split-by-locale" ? requestLocalesList : undefined,
-    deliveryArtifacts: delivery === "custom" ? config.deliveryArtifacts : undefined,
-  });
-
-  const typesOutputPath = path.resolve(projectRoot, paths.typesOutput);
-  const instanceOutputPath = path.resolve(projectRoot, paths.instanceOutput);
-  const namespaceLoadersOutputPath = path.resolve(projectRoot, paths.namespaceLoadersOutput);
-  const dictionarySchemaOutputPath = path.resolve(projectRoot, paths.dictionarySchemaOutput);
-  const typesModule = toModuleBasename(typesOutputPath);
-
-  const deliveryAreaNames =
-    delivery === "custom" && config.deliveryArtifacts
-      ? Object.keys(config.deliveryArtifacts).sort()
-      : undefined;
-  const deliveryAreaTypeName = delivery === "custom" ? resolvedDeliveryAreaTypeName : undefined;
-
-  const localeFallbackForEmit = config.localeFallback
-    ? enrichLocaleFallback(locales, config.localeFallback)
-    : undefined;
-
-  const typesContent = formatTypesFile({
-    entries,
-    projectRoot,
-    typesOutputPath,
-    paramsTypeName,
-    schemaTypeName,
-    localeTypeName,
-    localeFallbackConstName,
-    localeFallbackTypeName,
-    localeFallback: localeFallbackForEmit,
-    paramsByNamespace,
-    requestLocales: requestLocalesList,
-    ...(deliveryAreaTypeName && deliveryAreaNames
-      ? {
-          deliveryAreaTypeName,
-          deliveryAreaNames,
-          ...(delivery === "custom" && config.deliveryArtifacts
-            ? { deliveryArtifacts: config.deliveryArtifacts }
-            : {}),
-        }
-      : {}),
-    lazyEntries: entries,
-  });
-
-  const instanceContent = formatInstanceFile({
-    typesOutputPath,
-    namespaceLoadersOutputPath,
-    paramsTypeName,
-    schemaTypeName,
-    localeTypeName,
-    localeFallbackConstName,
-    factoryName,
-    hasLocaleFallback: Boolean(config.localeFallback),
-    hasLocaleType: requestLocalesList.length > 0,
-    importExtension,
-    delivery,
-    loaderStrategy,
-    ...(delivery === "custom" ? { localeDeliveryAreaConstName: "LOCALE_DELIVERY_AREA" } : {}),
-  });
-
-  writeFileIfChanged(typesOutputPath, typesContent);
-
-  const generatedFiles = [
-    path.relative(projectRoot, typesOutputPath),
-    path.relative(projectRoot, instanceOutputPath),
-  ];
-
-  writeFileIfChanged(instanceOutputPath, instanceContent);
-
-  const dictionarySpecBlock = formatDictionarySpecBlock(entries, argsSpecByNamespace);
-  const dictionarySchemaContent = formatDictionarySchemaFile(
-    schemaTypeName,
-    typesModule,
-    dictionarySpecBlock,
-    importExtension
-  );
-  writeFileIfChanged(dictionarySchemaOutputPath, dictionarySchemaContent);
-  generatedFiles.push(path.relative(projectRoot, dictionarySchemaOutputPath));
-
-  const lazyEntriesWithPaths = entries.map((entry) => ({
-    ...entry,
-    absolutePath: path.resolve(projectRoot, entry.filePath),
-  }));
-  const namespaceLoadersContent = formatNamespaceLoadersFile({
-    loadersOutputPath: namespaceLoadersOutputPath,
-    lazyEntries: lazyEntriesWithPaths,
-    schemaTypeName,
-    localeTypeName,
-    typesModule,
-    importExtension,
-    projectRoot,
-    delivery,
-    splitPathsByNamespace,
-    loaderStrategy,
-    ...(delivery === "split-by-locale" ? { requestLocales: requestLocalesList } : {}),
-    ...(delivery === "custom" && deliveryAreaTypeName && deliveryAreaNames
-      ? { deliveryAreaTypeName, deliveryAreaNames }
-      : {}),
-  });
-
-  writeFileIfChanged(namespaceLoadersOutputPath, namespaceLoadersContent);
-  generatedFiles.push(path.relative(projectRoot, namespaceLoadersOutputPath));
-
-  if (log) {
-    console.log(`✅ Generated: ${generatedFiles.join(", ")}`);
-    if (compiledFiles.length > 0) {
-      console.log(`✅ Compiled: ${compiledFiles.join(", ")}`);
-    }
-  }
-
-  return { projectRoot, generatedFiles, compiledFiles };
-}

package/src/codegen/types.ts

@@ -1,10 +0,0 @@
-import type { SUPPORTED_IMPORT_EXTENSIONS } from "./constants.js";
-
-export type ImportExtension = (typeof SUPPORTED_IMPORT_EXTENSIONS)[number];
-
-export interface NamespaceEntry {
-  namespace: string;
-  filePath: string;
-}
-
-export type DictionaryJson = Record<string, Record<string, string>>;

package/src/codegen/write-file-if-changed.test.ts

@@ -1,42 +0,0 @@
-import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import { writeFileIfChanged } from "./write-file-if-changed.js";
-
-describe("writeFileIfChanged", () => {
-  let tempDir: string;
-
-  afterEach(() => {
-    if (tempDir) {
-      rmSync(tempDir, { recursive: true, force: true });
-    }
-  });
-
-  it("creates missing files together with their parent directories", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-write-"));
-    const filePath = join(tempDir, "nested/dir/output.ts");
-
-    expect(writeFileIfChanged(filePath, "export {};\n")).toBe(true);
-    expect(readFileSync(filePath, "utf8")).toBe("export {};\n");
-  });
-
-  it("skips the write when content is unchanged", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-write-"));
-    const filePath = join(tempDir, "output.ts");
-    writeFileSync(filePath, "export {};\n");
-    const mtimeBefore = statSync(filePath).mtimeMs;
-
-    expect(writeFileIfChanged(filePath, "export {};\n")).toBe(false);
-    expect(statSync(filePath).mtimeMs).toBe(mtimeBefore);
-  });
-
-  it("overwrites the file when content differs", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-write-"));
-    const filePath = join(tempDir, "output.ts");
-    writeFileSync(filePath, "export const a = 1;\n");
-
-    expect(writeFileIfChanged(filePath, "export const a = 2;\n")).toBe(true);
-    expect(readFileSync(filePath, "utf8")).toBe("export const a = 2;\n");
-  });
-});

package/src/codegen/write-file-if-changed.ts

@@ -1,20 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-
-/**
- * Writes `content` to `absolutePath` only when it differs from the current
- * file content, keeping mtimes stable for downstream watchers/bundlers.
- * Returns true when the file was actually written.
- */
-export function writeFileIfChanged(absolutePath: string, content: string): boolean {
-  if (fs.existsSync(absolutePath)) {
-    const currentContent = fs.readFileSync(absolutePath, "utf8");
-    if (currentContent === content) {
-      return false;
-    }
-  }
-
-  fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
-  fs.writeFileSync(absolutePath, content);
-  return true;
-}

package/src/codegen-config/build-config.ts

@@ -1,15 +0,0 @@
-import type { CodegenConfigInput } from "../codegen/codegen-config-schema.js";
-
-const GENERATED_DIR = "generated";
-const TRANSLATIONS_DIR = "translations";
-
-export function buildCodegenConfig(project: string): CodegenConfigInput {
-  return {
-    projectName: project,
-    namespaces: {
-      default: `${TRANSLATIONS_DIR}/default.json`,
-    },
-    delivery: "split-by-locale",
-    codegenPath: GENERATED_DIR,
-  };
-}

package/src/codegen-config/codegen-config.test.ts

@@ -1,36 +0,0 @@
-import { mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { describe, expect, it, afterEach } from "vitest";
-import { buildCodegenConfig, type CodegenConfigInput, writeCodegenConfig } from "./index.js";
-
-describe("codegen-config", () => {
-  let tempDir: string;
-
-  afterEach(() => {
-    if (tempDir) {
-      rmSync(tempDir, { recursive: true, force: true });
-    }
-  });
-
-  it("buildCodegenConfig returns a valid multi-namespace input shape", () => {
-    const config = buildCodegenConfig("MyApp");
-    expect(config.namespaces).toEqual({
-      default: "translations/default.json",
-    });
-    expect(config.projectName).toBe("MyApp");
-    expect(config.codegenPath).toBe("generated");
-    expect(config).not.toHaveProperty("dictionary");
-    expect(config).not.toHaveProperty("paramsTypeName");
-  });
-
-  it("writeCodegenConfig writes formatted JSON", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-codegen-config-"));
-    const configPath = join(tempDir, "i18n/i18n.codegen.json");
-    const config: CodegenConfigInput = buildCodegenConfig("Demo");
-
-    writeCodegenConfig(configPath, config);
-
-    expect(readFileSync(configPath, "utf8")).toBe(`${JSON.stringify(config, null, 2)}\n`);
-  });
-});

package/src/codegen-config/index.ts

@@ -1,37 +0,0 @@
-export type {
-  CodegenConfig,
-  CodegenConfigInput,
-  DeliveryMode,
-  LoaderStrategy,
-  ResolvedCodegenPaths,
-} from "../codegen/codegen-config-schema.js";
-export {
-  codegenConfigKeys,
-  DELIVERY_MODES,
-  LOADER_STRATEGIES,
-  GENERATED_BASENAMES,
-  DEFAULT_FACTORY_NAME,
-  DEFAULT_LOCALE_FALLBACK_CONST_NAME,
-  formatCodegenConfigIssues,
-  resolveCodegenPaths,
-  resolveArtifactsPath,
-} from "../codegen/codegen-config-schema.js";
-export { loadConfig, resolveNamespaces } from "../codegen/config.js";
-
-export type { DeliveryArtifactsMap } from "../codegen/delivery-artifacts.js";
-
-export {
-  SUPPORTED_IMPORT_EXTENSIONS,
-  type SupportedImportExtension,
-} from "../codegen/constants.js";
-
-export { buildCodegenConfig } from "./build-config.js";
-export { inferProjectName, typeNamesForProject } from "./type-names.js";
-export { writeCodegenConfig } from "./write-config.js";
-
-export { runCodegen, type RunCodegenInput, type RunCodegenResult } from "../codegen/run-codegen.js";
-export {
-  regenerateNamespaces,
-  type RegenerateNamespacesInput,
-  type RegenerateNamespacesResult,
-} from "../codegen/regenerate-namespaces.js";

package/src/codegen-config/type-names.ts

@@ -1,20 +0,0 @@
-export function inferProjectName(dirName: string): string {
-  const parts = dirName.split(/[-_]+/).filter(Boolean);
-  if (parts.length === 0) {
-    return "App";
-  }
-
-  return parts.map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
-}
-
-export function typeNamesForProject(project: string): {
-  paramsTypeName: string;
-  schemaTypeName: string;
-  localeTypeName: string;
-} {
-  return {
-    paramsTypeName: `${project}Params`,
-    schemaTypeName: `${project}Schema`,
-    localeTypeName: `${project}Locale`,
-  };
-}

package/src/codegen-config/write-config.ts

@@ -1,8 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import type { CodegenConfigInput } from "../codegen/codegen-config-schema.js";
-
-export function writeCodegenConfig(configPath: string, config: CodegenConfigInput): void {
-  fs.mkdirSync(path.dirname(configPath), { recursive: true });
-  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
-}

package/src/engine.ts

@@ -1,47 +0,0 @@
-import type { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
-import type {
-  LocaleFallbackMap,
-  LocaleOfMulti,
-  MultiDictionary,
-  PartialMultiDictionary,
-} from "./types.js";
-import type { I18nScopeMulti, I18nScopeMultiForLocale } from "./scope-multi.js";
-import type { MultiParams, ParamsForNamespaces, SchemaForNamespaces } from "./scope-types.js";
-
-/** Mutable translation engine for a multi-namespace dictionary. */
-export interface I18nEngineMulti<
-  Schema extends MultiDictionary,
-  Params extends MultiParams<Schema>,
-  RequestLocales extends string = LocaleOfMulti<Schema>,
-> {
-  readonly __i18nEngineMode: "multi";
-  /** Loaded namespaces only — may be empty at cold start. */
-  getAll(): PartialMultiDictionary<Schema, RequestLocales>;
-  toScope<NsList extends readonly (keyof Schema & string)[]>(options: {
-    namespaces: NsList;
-  }): I18nScopeMulti<
-    SchemaForNamespaces<Schema, NsList>,
-    ParamsForNamespaces<Schema, Params, NsList>,
-    RequestLocales
-  >;
-  toScope<
-    NsList extends readonly (keyof Schema & string)[],
-    Locale extends RequestLocales,
-  >(options: {
-    namespaces: NsList;
-    locale: Locale;
-  }): I18nScopeMultiForLocale<
-    SchemaForNamespaces<Schema, NsList>,
-    ParamsForNamespaces<Schema, Params, NsList>,
-    RequestLocales,
-    Locale
-  >;
-}
-
-/** Alias for the default multi-namespace engine implementation. */
-export type I18nEngineMultiImpl<
-  Schema extends MultiDictionary,
-  Params extends MultiParams<Schema>,
-  RequestLocales extends string = LocaleOfMulti<Schema>,
-  Fallback extends LocaleFallbackMap | undefined = undefined,
-> = IcuTranslationProviderMulti<Schema, Params, RequestLocales, Fallback>;

package/src/fetch-artifact.ts

@@ -1,16 +0,0 @@
-/**
- * Identifies a delivery JSON artifact. Codegen passes this to {@link FetchArtifact};
- * URL / filesystem mapping is an application concern.
- */
-export type DeliveryResourceId = {
-  locale: string;
-  namespace: string;
-  /** Present for `delivery: "custom"` (partition key is the area). */
-  area?: string;
-};
-
-/**
- * Loads a translation JSON artifact by resource id.
- * Must return the parsed JSON value (not a raw Response).
- */
-export type FetchArtifact = (id: DeliveryResourceId) => Promise<unknown>;

package/src/format-core.ts

@@ -1,91 +0,0 @@
-import { IntlMessageFormat } from "intl-messageformat";
-import { formatLocaleFallbackChain, resolveLocaleTemplate } from "./resolve-locale.js";
-import type { LocaleCache, LocaleFallbackMap, OnMissingTranslation } from "./types.js";
-
-export type FormatCoreContext = {
-  key: string;
-  namespace?: string | undefined;
-  locale: string;
-  localeFallback?: LocaleFallbackMap | undefined;
-  onMissing: OnMissingTranslation;
-};
-
-export type ResolveAndFormatOptions = {
-  localeByKey: Record<string, string | undefined> | undefined;
-  locale: string;
-  params?: Record<string, unknown> | undefined;
-  getCache: (resolvedLocale: string) => LocaleCache;
-  context: FormatCoreContext;
-};
-
-function formatErrorLabel(context: Pick<FormatCoreContext, "key" | "namespace">): string {
-  if (context.namespace !== undefined) {
-    return `namespace "${context.namespace}", key "${context.key}"`;
-  }
-  return `key "${context.key}"`;
-}
-
-function formatMissingError(context: FormatCoreContext): string {
-  const chain = formatLocaleFallbackChain(context.locale, context.localeFallback);
-  if (context.namespace !== undefined) {
-    return `[i18n] Missing key or locale: namespace "${context.namespace}", key "${context.key}" [${context.locale}] (fallback chain: ${chain})`;
-  }
-  return `[i18n] Missing key or locale: "${context.key}" [${context.locale}] (fallback chain: ${chain})`;
-}
-
-function resolveMissing(context: FormatCoreContext): string {
-  const chain = formatLocaleFallbackChain(context.locale, context.localeFallback);
-  if (context.onMissing === "key") {
-    if (context.namespace !== undefined) {
-      return `${context.namespace}.${context.key}`;
-    }
-    return context.key;
-  }
-  if (typeof context.onMissing === "function") {
-    return context.onMissing({
-      ...(context.namespace !== undefined ? { namespace: context.namespace } : {}),
-      key: context.key,
-      locale: context.locale,
-      fallbackChain: chain,
-    });
-  }
-  throw new Error(formatMissingError(context));
-}
-
-/**
- * Shared runtime path for both ICU providers: resolve locale (with fallback) →
- * compile template (cached) → format with params; handles missing keys via `onMissing`.
- */
-export function resolveAndFormat(options: ResolveAndFormatOptions): string {
-  const { localeByKey, locale, params, getCache, context } = options;
-  const resolved = resolveLocaleTemplate(localeByKey, locale, context.localeFallback);
-
-  if (!resolved) {
-    return resolveMissing(context);
-  }
-
-  const { template, resolvedLocale } = resolved;
-  const cache = getCache(resolvedLocale);
-  const cacheKey = context.key;
-  const label = formatErrorLabel(context);
-
-  if (!cache[cacheKey]) {
-    try {
-      cache[cacheKey] = new IntlMessageFormat(template, resolvedLocale);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      throw new Error(
-        `[i18n ICU Syntax Error] Dictionary error for ${label} [${resolvedLocale}]: ${message}`
-      );
-    }
-  }
-
-  try {
-    return cache[cacheKey].format(params) as string;
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    throw new Error(
-      `[i18n Formatting Error] Invalid or missing parameters for ${label} [${resolvedLocale}]: ${message}`
-    );
-  }
-}