@xndrjs/i18n 0.2.1 → 0.3.0

package/README.md

@@ -112,7 +112,8 @@ xndrjs-toolkit/
 ├── packages/
 │   └── i18n/                       # @xndrjs/i18n — the publishable library
 │       ├── bin/
-│       │   └── codegen.mjs         # CLI entry: xndrjs-i18n-codegen
+│       │   ├── codegen.mjs         # CLI entry: xndrjs-i18n-codegen
+│       │   └── audit.mjs           # CLI entry: xndrjs-i18n-audit
 │       └── src/
 │           ├── index.ts            # public exports
 │           ├── types.ts            # generic dictionary/cache types
@@ -283,6 +284,8 @@ When a translation is missing for the requested locale (`undefined` in the dicti
 
 Codegen emits `LOCALE_FALLBACK` and extends `MyProjectLocale` with the fallback locales. The generated factory wires the map into the provider automatically.
 
+When `localeFallback` is present in config, codegen **enriches** the generated map: every locale in `MyProjectLocale` that is missing from your config is added with `null` (explicit terminal — no fallback chain). Runtime behavior is unchanged; the map is simply complete. If `localeFallback` is omitted from config, no `LOCALE_FALLBACK` is emitted (current behavior).
+
 You can also pass a fallback map manually when constructing a provider:
 
 ```ts
@@ -296,6 +299,27 @@ const localeFallback = {
 const i18n = new IcuTranslationProviderMulti(schema, { localeFallback });
 ```
 
+### 6. Translation audit (`xndrjs-i18n-audit`)
+
+Report missing translations as JSON — useful for translator backlogs and optional CI gates.
+
+```bash
+xndrjs-i18n-audit --config i18n/i18n.codegen.json
+xndrjs-i18n-audit --config i18n/i18n.codegen.json --out audit.json
+xndrjs-i18n-audit --config i18n/i18n.codegen.json --fail-on effective
+```
+
+**`requiredLocales`** in the report match generated `MyProjectLocale` (dictionary locales ∪ fallback keys and targets).
+
+| Field                      | Meaning                                                                                  |
+| -------------------------- | ---------------------------------------------------------------------------------------- |
+| `missingDirectByLocale`    | No template for that locale on the key (or empty string when `--allow-empty` is not set) |
+| `missingEffectiveByLocale` | Runtime would fail after walking `LOCALE_FALLBACK` — real coverage gaps                  |
+
+By default the CLI **does not fail** (exit `0`) — report-only. Pass `--fail-on effective`, `direct`, or `any` to exit `1` when gaps exist (for CI).
+
+Locales such as `de-CH` that exist only in `localeFallback` (not in source files) typically show high `missingDirect` but low `missingEffective` when `en` covers the chain — that is expected.
+
 ## Configuration (`i18n/i18n.codegen.json`)
 
 Specify **exactly one** of `dictionary` (single-file) or `namespaces` (multi-file). Paths in the config are relative to the directory containing `i18n.codegen.json` (the `i18n/` folder created by setup).
@@ -307,7 +331,7 @@ Specify **exactly one** of `dictionary` (single-file) or `namespaces` (multi-fil
   "namespaces": {
     "default": "translations/default.json",
     "user": "translations/user.json",
-    "billing": "translations/billing.json"
+    "billing": "translations/billing.yaml"
   },
   "typesOutput": "generated/i18n-types.generated.ts",
   "dictionaryOutput": "generated/dictionary.generated.ts",
@@ -349,12 +373,13 @@ Specify **exactly one** of `dictionary` (single-file) or `namespaces` (multi-fil
 
 | Field                               | Description                                                                                                                                                                         |
 | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
-| `dictionary`                        | Path to a single JSON file (flat API). Mutually exclusive with `namespaces`.                                                                                                        |
-| `namespaces`                        | Map of `namespace -> JSON path` (namespaced API). Mutually exclusive with `dictionary`.                                                                                             |
+| `dictionary`                        | Path to a single dictionary file (`.json`, `.yaml`, or `.yml`) for the flat API. Mutually exclusive with `namespaces`.                                                              |
+| `namespaces`                        | Map of `namespace -> dictionary path` (`.json`, `.yaml`, or `.yml`) for the namespaced API. Mutually exclusive with `dictionary`.                                                   |
 | `defaultNamespace`                  | Optional. Namespace label used internally in single-file mode (default `"default"`). Not exposed in the flat API.                                                                   |
 | `typesOutput`                       | Output path for the generated types.                                                                                                                                                |
 | `dictionaryOutput`                  | Output path for the generated dictionary manifest.                                                                                                                                  |
 | `instanceOutput`                    | Output path for the generated factory (`createI18n`).                                                                                                                               |
+| `importExtension`                   | Optional. Relative import suffix between generated `.ts` modules: `"none"` (default, extensionless), `".ts"`, or `".js"`.                                                           |
 | `factoryName`                       | Name of the exported factory function (default `createI18n`).                                                                                                                       |
 | `paramsTypeName` / `schemaTypeName` | Names of the exported types (customizable per project).                                                                                                                             |
 | `localeTypeName`                    | Name of the exported locale union type (default `MyProjectLocale`).                                                                                                                 |
@@ -366,6 +391,29 @@ Specify **exactly one** of `dictionary` (single-file) or `namespaces` (multi-fil
 
 > Paths are resolved relative to the directory containing `i18n.codegen.json` (e.g. `i18n/` when using `xndrjs-i18n-setup .`).
 
+### YAML authoring
+
+Dictionary paths may use `.yaml` or `.yml` instead of `.json`. **YAML is an authoring format, not a runtime format** — codegen compiles YAML to JSON under the generated output directory (for example `translations/billing.yaml` → `{dirname(typesOutput)}/translations/billing.json`); generated TypeScript imports the compiled JSON at runtime. Edit only the YAML source — the compiled JSON is overwritten on each codegen run.
+
+YAML block scalars make long ICU messages much easier to read while preserving (or intentionally folding) line breaks.
+
+```yaml
+# translations/billing.yaml
+appointment_summary:
+  en: |
+    Due {dueDate, date, short}
+    at {startTime, time, short}
+  it: "Scade il {dueDate, date, short} alle {startTime, time, short}"
+```
+
+Workflow:
+
+1. Edit the `.yaml` / `.yml` source file under `translations/`.
+2. Run `xndrjs-i18n-codegen`.
+3. Commit the YAML source; the compiled JSON lives under `generated/translations/` and is safe to commit or gitignore if CI regenerates it before build.
+
+Mixed namespaces are supported: some namespaces can stay `.json` while others use YAML.
+
 ## Usage
 
 ### Single vs. multi-namespace API
@@ -421,7 +469,7 @@ Split namespaces across chunks by listing only the namespaces you need at startu
 {
   "namespaces": {
     "default": "translations/default.json",
-    "billing": "translations/billing.json"
+    "billing": "translations/billing.yaml"
   },
   "loadOnInit": ["default"],
   "dictionarySchemaOutput": "generated/dictionary-schema.generated.ts",
@@ -537,8 +585,10 @@ pnpm --filter @xndrjs/i18n test
 From inside `apps/i18n-demo/`:
 
 ```bash
-pnpm run i18n:codegen:single   # xndrjs-i18n-codegen --config single/i18n.codegen.json
-pnpm run i18n:codegen:multi    # xndrjs-i18n-codegen --config multi/i18n.codegen.json
+pnpm run i18n:codegen:single   # xndrjs-i18n-codegen --config single/src/i18n/i18n.codegen.json
+pnpm run i18n:codegen:multi    # xndrjs-i18n-codegen --config multi/src/i18n/i18n.codegen.json
+pnpm run i18n:audit:single     # xndrjs-i18n-audit --config single/src/i18n/i18n.codegen.json
+pnpm run i18n:audit:multi      # xndrjs-i18n-audit --config multi/src/i18n/i18n.codegen.json
 pnpm run demo:single           # tsx single/src/index.ts
 pnpm run demo:multi            # tsx multi/src/index.ts
 ```
@@ -551,7 +601,7 @@ pnpm run demo:multi            # tsx multi/src/index.ts
 
 ## Adding a namespace
 
-1. Create a new JSON file (any name/path).
+1. Create a new dictionary file (`.json`, `.yaml`, or `.yml`, any path).
 2. Add it to `namespaces` in `i18n/i18n.codegen.json`.
 3. Re-run codegen. `dictionary.generated.ts` wires the import automatically.
 

package/bin/audit.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const script = join(dirname(fileURLToPath(import.meta.url)), "../src/audit/run-audit.ts");
+
+const result = spawnSync("tsx", [script, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+  env: process.env,
+});
+
+process.exit(result.status ?? 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xndrjs/i18n",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Compiler-first, type-safe ICU MessageFormat i18n with runtime dictionary override from external sources.",
   "private": false,
   "license": "MIT",
@@ -12,7 +12,8 @@
   "type": "module",
   "bin": {
     "xndrjs-i18n-codegen": "./bin/codegen.mjs",
-    "xndrjs-i18n-setup": "./bin/setup.mjs"
+    "xndrjs-i18n-setup": "./bin/setup.mjs",
+    "xndrjs-i18n-audit": "./bin/audit.mjs"
   },
   "types": "./dist/index.d.ts",
   "exports": {
@@ -37,7 +38,8 @@
   },
   "dependencies": {
     "@formatjs/icu-messageformat-parser": "^3.5.12",
-    "intl-messageformat": "^11.2.9"
+    "intl-messageformat": "^11.2.9",
+    "yaml": "^2.8.1"
   },
   "peerDependencies": {
     "tsx": ">=4",

package/src/IcuTranslationProviderSingle.test.ts

@@ -8,11 +8,15 @@ type TestSchema = {
   empty_label: { en: string };
   broken: { en: string };
   invoice_count: { en: string; it: string };
+  item_count_zero: { en: string };
+  item_count_exact: { en: string };
   dashboard_status: { en: string; it: string };
   inbox_owner: { en: string; it: string };
   ranking_position: { en: string; it: string };
   account_balance: { en: string; it: string };
   appointment_summary: { en: string; it: string };
+  invoice_due_long: { en: string; it: string };
+  discount_rate: { en: string; it: string };
 };
 
 type TestParams = {
@@ -21,11 +25,15 @@ type TestParams = {
   empty_label: never;
   broken: { name: string };
   invoice_count: { count: number };
+  item_count_zero: { count: number };
+  item_count_exact: { count: number };
   dashboard_status: { msgCount: number; chatCount: number };
   inbox_owner: { gender: string; name: string };
   ranking_position: { position: number };
   account_balance: { amount: number };
   appointment_summary: { dueDate: Date | number; startTime: Date | number };
+  invoice_due_long: { dueDate: Date | number };
+  discount_rate: { rate: number };
 };
 
 const dictionary: TestSchema = {
@@ -37,6 +45,12 @@ const dictionary: TestSchema = {
     en: "You have {count, plural, one {1 invoice} other {{count} invoices}}",
     it: "Hai {count, plural, one {1 fattura} other {{count} fatture}}",
   },
+  item_count_zero: {
+    en: "{count, plural, zero {no items} one {1 item} other {{count} items}}",
+  },
+  item_count_exact: {
+    en: "{count, plural, =5 {five items} one {1 item} other {{count} items}}",
+  },
   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}}",
@@ -57,6 +71,14 @@ const dictionary: TestSchema = {
     en: "Due {dueDate, date, short} at {startTime, time, short}",
     it: "Scade il {dueDate, date, short} alle {startTime, time, short}",
   },
+  invoice_due_long: {
+    en: "Payment due on {dueDate, date, ::yMMMMd}",
+    it: "Pagamento entro il {dueDate, date, ::yMMMMd}",
+  },
+  discount_rate: {
+    en: "Save {rate, number, ::percent} today",
+    it: "Risparmia il {rate, number, ::percent} oggi",
+  },
 };
 
 describe("IcuTranslationProviderSingle", () => {
@@ -78,6 +100,15 @@ describe("IcuTranslationProviderSingle", () => {
       expect(provider.get("invoice_count", "it", { count: 5 })).toBe("Hai 5 fatture");
     });
 
+    it("uses =5 for an exact match; zero is a locale plural category, not exact match in English", () => {
+      // ICU "zero" is a plural rule category (e.g. Arabic); in English, 0 maps to "other".
+      expect(provider.get("item_count_zero", "en", { count: 0 })).toBe("0 items");
+      // "=5" is an exact-value selector and matches count === 5 in any locale.
+      expect(provider.get("item_count_exact", "en", { count: 0 })).toBe("0 items");
+      expect(provider.get("item_count_exact", "en", { count: 1 })).toBe("1 item");
+      expect(provider.get("item_count_exact", "en", { count: 5 })).toBe("five items");
+    });
+
     it("formats nested numeric plurals with double-brace references", () => {
       expect(provider.get("dashboard_status", "en", { msgCount: 1, chatCount: 1 })).toBe(
         "You have 1 message in one chat"
@@ -149,6 +180,25 @@ describe("IcuTranslationProviderSingle", () => {
         })
       ).toBe(`Due ${expectedDate} at ${expectedTime}`);
     });
+
+    it("formats ICU date and number skeletons (::yMMMMd, ::percent)", () => {
+      const when = new Date("2026-07-01T13:30:00Z");
+      const expectedLongDate = new Intl.DateTimeFormat("en", {
+        year: "numeric",
+        month: "long",
+        day: "numeric",
+      }).format(when);
+      const expectedPercent = new Intl.NumberFormat("en", {
+        style: "percent",
+      }).format(0.25);
+
+      expect(provider.get("invoice_due_long", "en", { dueDate: when })).toBe(
+        `Payment due on ${expectedLongDate}`
+      );
+      expect(provider.get("discount_rate", "en", { rate: 0.25 })).toBe(
+        `Save ${expectedPercent} today`
+      );
+    });
   });
 
   it("treats an empty string template as valid", () => {
@@ -209,11 +259,15 @@ describe("IcuTranslationProviderSingle", () => {
         en: "You have {count, plural, one {1 invoice} other {{count} invoices}}",
         it: "Hai {count, plural, one {1 fattura} other {{count} fatture}}",
       },
+      item_count_zero: dictionary.item_count_zero,
+      item_count_exact: dictionary.item_count_exact,
       dashboard_status: dictionary.dashboard_status,
       inbox_owner: dictionary.inbox_owner,
       ranking_position: dictionary.ranking_position,
       account_balance: dictionary.account_balance,
       appointment_summary: dictionary.appointment_summary,
+      invoice_due_long: dictionary.invoice_due_long,
+      discount_rate: dictionary.discount_rate,
     };
     const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(external);
     external.login_button.en = "Sign in";

package/src/audit/audit-dictionaries.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from "vitest";
+import { auditDictionaries, reportHasGaps } from "./audit-dictionaries.js";
+
+describe("auditDictionaries", () => {
+  it("reports missingDirect for fallback-only locales while missingEffective stays empty when en covers", () => {
+    const report = auditDictionaries({
+      namespaces: {
+        default: {
+          login_button: { en: "Login", it: "Accedi" },
+        },
+      },
+      config: {
+        localeFallback: {
+          en: null,
+          "de-DE": "en",
+          "de-CH": "de-DE",
+          it: "en",
+        },
+      },
+    });
+
+    expect(report.requiredLocales).toEqual(["de-CH", "de-DE", "en", "it"]);
+    expect(report.missingDirectByLocale.default?.["de-CH"]).toEqual(["login_button"]);
+    expect(report.missingEffectiveByLocale.default?.["de-CH"]).toEqual([]);
+    expect(report.missingDirectByLocale.default?.en).toEqual([]);
+  });
+
+  it("treats empty strings as missing by default", () => {
+    const report = auditDictionaries({
+      namespaces: {
+        default: {
+          empty_label: { en: "" },
+        },
+      },
+      config: {},
+    });
+
+    expect(report.missingDirectByLocale.default?.en).toEqual(["empty_label"]);
+    expect(report.missingEffectiveByLocale.default?.en).toEqual(["empty_label"]);
+  });
+
+  it("allows empty strings when treatEmptyAsMissing is false", () => {
+    const report = auditDictionaries({
+      namespaces: {
+        default: {
+          empty_label: { en: "" },
+        },
+      },
+      config: {},
+      treatEmptyAsMissing: false,
+    });
+
+    expect(report.missingDirectByLocale.default?.en).toEqual([]);
+    expect(report.missingEffectiveByLocale.default?.en).toEqual([]);
+  });
+
+  it("uses enriched locale fallback for effective gaps", () => {
+    const report = auditDictionaries({
+      namespaces: {
+        default: {
+          welcome: { en: "Welcome {name}!" },
+        },
+      },
+      config: {
+        localeFallback: {
+          en: null,
+          it: "en",
+        },
+      },
+    });
+
+    expect(report.localeFallback).toEqual({
+      en: null,
+      it: "en",
+    });
+    expect(report.missingEffectiveByLocale.default?.it).toEqual([]);
+  });
+
+  it("matches direct and effective when localeFallback is absent", () => {
+    const report = auditDictionaries({
+      namespaces: {
+        default: {
+          login_button: { en: "Login" },
+        },
+      },
+      config: {},
+    });
+
+    expect(report.localeFallback).toBeUndefined();
+    expect(report.requiredLocales).toEqual(["en"]);
+    expect(report.missingDirectByLocale.default?.en).toEqual([]);
+    expect(report.missingEffectiveByLocale.default?.en).toEqual([]);
+  });
+
+  it("reports effective gaps when fallback chain cannot resolve", () => {
+    const report = auditDictionaries({
+      namespaces: {
+        default: {
+          login_button: { it: "Accedi" },
+        },
+      },
+      config: {
+        localeFallback: {
+          en: null,
+          it: "en",
+        },
+      },
+    });
+
+    expect(report.missingEffectiveByLocale.default?.en).toEqual(["login_button"]);
+  });
+});
+
+describe("reportHasGaps", () => {
+  const report = auditDictionaries({
+    namespaces: {
+      default: {
+        login_button: { en: "Login", it: "Accedi" },
+      },
+    },
+    config: {
+      localeFallback: {
+        en: null,
+        "de-CH": "en",
+      },
+    },
+  });
+
+  it("detects direct gaps", () => {
+    expect(reportHasGaps(report, "direct")).toBe(true);
+    expect(reportHasGaps(report, "effective")).toBe(false);
+    expect(reportHasGaps(report, "any")).toBe(true);
+  });
+});

package/src/audit/audit-dictionaries.ts

@@ -0,0 +1,172 @@
+import path from "node:path";
+import type { CodegenConfig, DictionaryJson } from "../codegen/types.js";
+import { buildRequiredLocales, enrichLocaleFallback } from "../codegen/locale-policy.js";
+import { resolveLocaleTemplate } from "../resolve-locale.js";
+
+export type FailOnCriterion = "effective" | "direct" | "any";
+
+export interface I18nAuditReport {
+  requiredLocales: string[];
+  localeFallback?: Record<string, string | null>;
+  summary: Record<string, Record<string, { missingDirect: number; missingEffective: number }>>;
+  missingDirectByLocale: Record<string, Record<string, string[]>>;
+  missingEffectiveByLocale: Record<string, Record<string, string[]>>;
+}
+
+export interface AuditDictionariesOptions {
+  namespaces: Record<string, DictionaryJson>;
+  config: Pick<CodegenConfig, "localeFallback" | "defaultNamespace">;
+  treatEmptyAsMissing?: boolean;
+}
+
+function isDirectlyMissing(
+  localesByKey: Record<string, string>,
+  locale: string,
+  treatEmptyAsMissing: boolean
+): boolean {
+  const template = localesByKey[locale];
+  if (template === undefined) {
+    return true;
+  }
+  return treatEmptyAsMissing && template === "";
+}
+
+function isEffectivelyMissing(
+  localesByKey: Record<string, string>,
+  locale: string,
+  localeFallback: Record<string, string | null> | undefined,
+  treatEmptyAsMissing: boolean
+): boolean {
+  const resolved = resolveLocaleTemplate(localesByKey, locale, localeFallback);
+  if (resolved === undefined) {
+    return true;
+  }
+  return treatEmptyAsMissing && resolved.template === "";
+}
+
+function collectDictionaryLocales(namespaces: Record<string, DictionaryJson>): Set<string> {
+  const locales = new Set<string>();
+
+  for (const dictionary of Object.values(namespaces)) {
+    for (const localesByKey of Object.values(dictionary)) {
+      for (const locale of Object.keys(localesByKey)) {
+        locales.add(locale);
+      }
+    }
+  }
+
+  return locales;
+}
+
+export function auditDictionaries(options: AuditDictionariesOptions): I18nAuditReport {
+  const { namespaces, config, treatEmptyAsMissing = true } = options;
+  const dictionaryLocales = collectDictionaryLocales(namespaces);
+  const requiredLocales = buildRequiredLocales(dictionaryLocales, config.localeFallback);
+  const localeFallbackForAudit = config.localeFallback
+    ? enrichLocaleFallback(dictionaryLocales, config.localeFallback)
+    : undefined;
+
+  const summary: I18nAuditReport["summary"] = {};
+  const missingDirectByLocale: I18nAuditReport["missingDirectByLocale"] = {};
+  const missingEffectiveByLocale: I18nAuditReport["missingEffectiveByLocale"] = {};
+
+  for (const [namespace, dictionary] of Object.entries(namespaces)) {
+    summary[namespace] = {};
+    missingDirectByLocale[namespace] = {};
+    missingEffectiveByLocale[namespace] = {};
+
+    for (const locale of requiredLocales) {
+      summary[namespace]![locale] = { missingDirect: 0, missingEffective: 0 };
+      missingDirectByLocale[namespace]![locale] = [];
+      missingEffectiveByLocale[namespace]![locale] = [];
+    }
+
+    for (const [key, localesByKey] of Object.entries(dictionary)) {
+      for (const locale of requiredLocales) {
+        if (isDirectlyMissing(localesByKey, locale, treatEmptyAsMissing)) {
+          summary[namespace]![locale]!.missingDirect += 1;
+          missingDirectByLocale[namespace]![locale]!.push(key);
+        }
+
+        if (
+          isEffectivelyMissing(localesByKey, locale, localeFallbackForAudit, treatEmptyAsMissing)
+        ) {
+          summary[namespace]![locale]!.missingEffective += 1;
+          missingEffectiveByLocale[namespace]![locale]!.push(key);
+        }
+      }
+    }
+
+    for (const locale of requiredLocales) {
+      missingDirectByLocale[namespace]![locale]!.sort();
+      missingEffectiveByLocale[namespace]![locale]!.sort();
+    }
+  }
+
+  return {
+    requiredLocales,
+    localeFallback: localeFallbackForAudit,
+    summary,
+    missingDirectByLocale,
+    missingEffectiveByLocale,
+  };
+}
+
+export function reportHasGaps(report: I18nAuditReport, criterion: FailOnCriterion): boolean {
+  for (const namespace of Object.keys(report.missingDirectByLocale)) {
+    for (const locale of report.requiredLocales) {
+      const direct = report.missingDirectByLocale[namespace]?.[locale] ?? [];
+      const effective = report.missingEffectiveByLocale[namespace]?.[locale] ?? [];
+
+      if (criterion === "direct" && direct.length > 0) {
+        return true;
+      }
+      if (criterion === "effective" && effective.length > 0) {
+        return true;
+      }
+      if (criterion === "any" && (direct.length > 0 || effective.length > 0)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+export interface RunAuditOptions {
+  projectRoot: string;
+  config: CodegenConfig;
+  configPath: string;
+  treatEmptyAsMissing?: boolean;
+  failOn?: FailOnCriterion;
+}
+
+export interface RunAuditResult {
+  report: I18nAuditReport;
+  exitCode: 0 | 1;
+}
+
+export async function runAuditFromConfig(options: RunAuditOptions): Promise<RunAuditResult> {
+  const { resolveNamespaces } = await import("../codegen/config.js");
+  const { readDictionaryFile } = await import("../codegen/read-dictionary.js");
+
+  const config = options.config;
+  const entries = resolveNamespaces(config);
+  const namespaces: Record<string, DictionaryJson> = {};
+
+  for (const entry of entries) {
+    const absolutePath = path.resolve(options.projectRoot, entry.filePath);
+    namespaces[entry.namespace] = readDictionaryFile(absolutePath);
+  }
+
+  const report = auditDictionaries({
+    namespaces,
+    config,
+    treatEmptyAsMissing: options.treatEmptyAsMissing,
+  });
+
+  const exitCode =
+    options.failOn && reportHasGaps(report, options.failOn) ? (1 as const) : (0 as const);
+
+  return { report, exitCode };
+}