@xndrjs/i18n 0.2.1 → 0.3.1

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 };
+}

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

@@ -0,0 +1,136 @@
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { parseAuditArgs, runAuditCli } from "./run-audit.js";
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
+const auditBin = join(packageRoot, "bin/audit.mjs");
+
+describe("parseAuditArgs", () => {
+  it("defaults to report-only mode without --fail-on", () => {
+    expect(parseAuditArgs([])).toEqual({
+      configPath: join(process.cwd(), "i18n/i18n.codegen.json"),
+      outPath: undefined,
+      failOn: undefined,
+      treatEmptyAsMissing: true,
+    });
+  });
+
+  it("parses fail-on and allow-empty", () => {
+    const parsed = parseAuditArgs([
+      "--config",
+      "cfg.json",
+      "--fail-on",
+      "effective",
+      "--allow-empty",
+    ]);
+    expect(parsed.failOn).toBe("effective");
+    expect(parsed.treatEmptyAsMissing).toBe(false);
+    expect(parsed.configPath).toBe(join(process.cwd(), "cfg.json"));
+  });
+});
+
+describe("runAuditCli", () => {
+  let tempDir = "";
+
+  afterEach(() => {
+    if (tempDir) {
+      rmSync(tempDir, { recursive: true, force: true });
+      tempDir = "";
+    }
+  });
+
+  function writeFixture(dictionary: Record<string, Record<string, string>>) {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-audit-"));
+    mkdirSync(join(tempDir, "i18n/translations"), { recursive: true });
+    writeFileSync(join(tempDir, "i18n/translations/translations.json"), JSON.stringify(dictionary));
+    writeFileSync(
+      join(tempDir, "i18n/i18n.codegen.json"),
+      JSON.stringify({
+        dictionary: "translations/translations.json",
+        typesOutput: "generated/i18n-types.generated.ts",
+        dictionaryOutput: "generated/dictionary.generated.ts",
+        instanceOutput: "generated/instance.generated.ts",
+        paramsTypeName: "AppParams",
+        schemaTypeName: "AppSchema",
+        localeFallback: {
+          en: null,
+          it: "en",
+        },
+      })
+    );
+  }
+
+  it("exits 0 without --fail-on even when effective gaps exist", async () => {
+    writeFixture({
+      welcome: { en: "Welcome" },
+    });
+
+    const previousCwd = process.cwd();
+    process.chdir(tempDir);
+    try {
+      const exitCode = await runAuditCli(["--config", "i18n/i18n.codegen.json"]);
+      expect(exitCode).toBe(0);
+    } finally {
+      process.chdir(previousCwd);
+    }
+  });
+
+  it("exits 1 with --fail-on effective when effective gaps exist", async () => {
+    writeFixture({
+      login_button: { it: "Accedi" },
+    });
+
+    const previousCwd = process.cwd();
+    process.chdir(tempDir);
+    try {
+      const exitCode = await runAuditCli([
+        "--config",
+        "i18n/i18n.codegen.json",
+        "--fail-on",
+        "effective",
+      ]);
+      expect(exitCode).toBe(1);
+    } finally {
+      process.chdir(previousCwd);
+    }
+  });
+
+  it("writes JSON report to --out", async () => {
+    writeFixture({
+      login_button: { en: "Login", it: "Accedi" },
+    });
+
+    const outPath = join(tempDir, "audit.json");
+    const previousCwd = process.cwd();
+    process.chdir(tempDir);
+    try {
+      const exitCode = await runAuditCli(["--config", "i18n/i18n.codegen.json", "--out", outPath]);
+      expect(exitCode).toBe(0);
+      const report = JSON.parse(readFileSync(outPath, "utf8"));
+      expect(report.requiredLocales).toEqual(["en", "it"]);
+      expect(report.missingEffectiveByLocale.default.en).toEqual([]);
+    } finally {
+      process.chdir(previousCwd);
+    }
+  });
+
+  it("runs through the bin wrapper", () => {
+    writeFixture({
+      login_button: { en: "Login" },
+    });
+
+    const result = spawnSync("node", [auditBin, "--config", "i18n/i18n.codegen.json"], {
+      cwd: tempDir,
+      encoding: "utf8",
+    });
+
+    expect(result.status).toBe(0);
+    const report = JSON.parse(result.stdout);
+    expect(report.requiredLocales).toEqual(["en", "it"]);
+  });
+});

package/src/audit/run-audit.ts

@@ -0,0 +1,81 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig } from "../codegen/config.js";
+import { fail } from "../codegen/paths.js";
+import { type FailOnCriterion, runAuditFromConfig } from "./audit-dictionaries.js";
+
+const FAIL_ON_VALUES = new Set<FailOnCriterion>(["effective", "direct", "any"]);
+
+export interface AuditCliOptions {
+  configPath: string;
+  outPath?: string;
+  failOn?: FailOnCriterion;
+  treatEmptyAsMissing: boolean;
+}
+
+export function parseAuditArgs(argv: string[]): AuditCliOptions {
+  const configArgIndex = argv.indexOf("--config");
+  const outArgIndex = argv.indexOf("--out");
+  const failOnArgIndex = argv.indexOf("--fail-on");
+
+  const configPath = path.resolve(
+    process.cwd(),
+    configArgIndex >= 0 ? argv[configArgIndex + 1]! : "i18n/i18n.codegen.json"
+  );
+
+  const outPath =
+    outArgIndex >= 0 ? path.resolve(process.cwd(), argv[outArgIndex + 1]!) : undefined;
+
+  let failOn: FailOnCriterion | undefined;
+  if (failOnArgIndex >= 0) {
+    const value = argv[failOnArgIndex + 1];
+    if (!value || !FAIL_ON_VALUES.has(value as FailOnCriterion)) {
+      fail(`[Audit Error] --fail-on must be one of: effective, direct, any`);
+    }
+    failOn = value as FailOnCriterion;
+  }
+
+  const treatEmptyAsMissing = !argv.includes("--allow-empty");
+
+  return { configPath, outPath, failOn, treatEmptyAsMissing };
+}
+
+export async function runAuditCli(argv = process.argv.slice(2)): Promise<number> {
+  const options = parseAuditArgs(argv);
+
+  if (!fs.existsSync(options.configPath)) {
+    console.error(`[Audit Error] Config file not found: ${options.configPath}`);
+    return 2;
+  }
+
+  const projectRoot = path.dirname(options.configPath);
+  const config = loadConfig(options.configPath);
+
+  const { report, exitCode } = await runAuditFromConfig({
+    projectRoot,
+    config,
+    configPath: options.configPath,
+    treatEmptyAsMissing: options.treatEmptyAsMissing,
+    failOn: options.failOn,
+  });
+
+  const json = `${JSON.stringify(report, null, 2)}\n`;
+
+  if (options.outPath) {
+    fs.mkdirSync(path.dirname(options.outPath), { recursive: true });
+    fs.writeFileSync(options.outPath, json);
+  } else {
+    process.stdout.write(json);
+  }
+
+  return exitCode;
+}
+
+async function main(): Promise<void> {
+  const exitCode = await runAuditCli();
+  process.exit(exitCode);
+}
+
+if (process.argv[1]?.endsWith("run-audit.ts")) {
+  void main();
+}

package/src/codegen/emit/dictionary-file.ts

@@ -4,8 +4,9 @@ import {
   toImportIdentifier,
   toImportPath,
   toModuleBasename,
+  toRelativeModuleImport,
 } from "../paths.js";
-import type { NamespaceEntry } from "../types.js";
+import type { ImportExtension, NamespaceEntry } from "../types.js";
 
 export interface DictionaryFileOptions {
   isSingle: boolean;
@@ -16,6 +17,7 @@ export interface DictionaryFileOptions {
   dictionaryOutputPath: string;
   typesOutputPath: string;
   schemaTypeName: string;
+  importExtension: ImportExtension;
 }
 
 export function formatDictionaryFile(options: DictionaryFileOptions): string {
@@ -28,9 +30,11 @@ export function formatDictionaryFile(options: DictionaryFileOptions): string {
     dictionaryOutputPath,
     typesOutputPath,
     schemaTypeName,
+    importExtension,
   } = options;
 
   const typesModule = toModuleBasename(typesOutputPath);
+  const typesImport = toRelativeModuleImport(typesModule, importExtension);
 
   if (isSingle) {
     const entry = entries[0]!;
@@ -43,7 +47,7 @@ export function formatDictionaryFile(options: DictionaryFileOptions): string {
     return (
       `${GENERATED_FILE_BANNER}` +
       `import ${importId} from '${importPath}.json';\n` +
-      `import type { ${schemaTypeName} } from './${typesModule}.js';\n\n` +
+      `import type { ${schemaTypeName} } from '${typesImport}';\n\n` +
       `export const dictionary: ${schemaTypeName} = ${importId};\n`
     );
   }
@@ -67,7 +71,7 @@ export function formatDictionaryFile(options: DictionaryFileOptions): string {
   return (
     `${GENERATED_FILE_BANNER}` +
     `${imports}\n` +
-    `import type { ${dictionaryTypeName} } from './${typesModule}.js';\n\n` +
+    `import type { ${dictionaryTypeName} } from '${typesImport}';\n\n` +
     `export const dictionary: ${dictionaryTypeName} = {\n${objectEntries}\n};\n`
   );
 }

package/src/codegen/emit/dictionary-schema-file.ts

@@ -1,6 +1,6 @@
 import type { VariableSpec } from "../../icu/extract-variables.js";
-import { GENERATED_FILE_BANNER } from "../paths.js";
-import type { NamespaceEntry } from "../types.js";
+import { GENERATED_FILE_BANNER, toRelativeModuleImport } from "../paths.js";
+import type { ImportExtension, NamespaceEntry } from "../types.js";
 
 function formatVariableSpecObject(spec: VariableSpec): string {
   const entries = Object.entries(spec);
@@ -70,8 +70,10 @@ export function formatDictionarySchemaFile(
   schemaTypeName: string,
   typesModule: string,
   isSingle: boolean,
-  dictionarySpecBlock: string
+  dictionarySpecBlock: string,
+  importExtension: ImportExtension
 ): string {
+  const typesImport = toRelativeModuleImport(typesModule, importExtension);
   const namespaceImport = isSingle
     ? ""
     : `  validateExternalNamespace as validateExternalNamespaceImpl,\n`;
@@ -99,7 +101,7 @@ export function formatDictionarySchemaFile(
     `  type NormalizedDictionary,\n` +
     `  type ValidationResult,\n` +
     `} from '@xndrjs/i18n/validation';\n` +
-    `import type { ${schemaTypeName} } from './${typesModule}.js';\n\n` +
+    `import type { ${schemaTypeName} } from '${typesImport}';\n\n` +
     `${dictionarySpecBlock}\n` +
     `export function normalizeExternalDictionary(\n` +
     `  input: unknown,\n` +

package/src/codegen/emit/instance-file.ts

@@ -1,4 +1,5 @@
-import { GENERATED_FILE_BANNER, toModuleBasename } from "../paths.js";
+import { GENERATED_FILE_BANNER, toModuleBasename, toRelativeModuleImport } from "../paths.js";
+import type { ImportExtension } from "../types.js";
 
 export interface InstanceFileOptions {
   isSingle: boolean;
@@ -11,6 +12,8 @@ export interface InstanceFileOptions {
   localeFallbackConstName: string;
   factoryName: string;
   hasLocaleFallback: boolean;
+  hasLocaleType: boolean;
+  importExtension: ImportExtension;
 }
 
 export function formatInstanceFile(options: InstanceFileOptions): string {
@@ -25,36 +28,51 @@ export function formatInstanceFile(options: InstanceFileOptions): string {
     localeFallbackConstName,
     factoryName,
     hasLocaleFallback,
+    hasLocaleType,
+    importExtension,
   } = options;
 
   const providerClass = isSingle ? "IcuTranslationProviderSingle" : "IcuTranslationProviderMulti";
   const typesModule = toModuleBasename(typesOutputPath);
   const dictionaryModule = toModuleBasename(dictionaryOutputPath);
+  const typesImport = toRelativeModuleImport(typesModule, importExtension);
+  const dictionaryImport = toRelativeModuleImport(dictionaryModule, importExtension);
   const initialDictionaryType = hasLazy ? "InitialSchema" : schemaTypeName;
   const initialDictionaryImport = hasLazy
-    ? `import type { ${paramsTypeName}, ${schemaTypeName}, InitialSchema } from './${typesModule}.js';\n`
-    : `import type { ${paramsTypeName}, ${schemaTypeName} } from './${typesModule}.js';\n`;
+    ? `import type { ${paramsTypeName}, ${schemaTypeName}, InitialSchema } from '${typesImport}';\n`
+    : `import type { ${paramsTypeName}, ${schemaTypeName} } from '${typesImport}';\n`;
   const providerTypeArgs = hasLocaleFallback
     ? `${schemaTypeName}, ${paramsTypeName}, ${localeTypeName}, typeof ${localeFallbackConstName}`
     : `${schemaTypeName}, ${paramsTypeName}`;
   const providerOptions = hasLocaleFallback
     ? `, {\n    localeFallback: ${localeFallbackConstName},\n  }`
     : "";
-  const fallbackImport = hasLocaleFallback
-    ? `import { ${localeFallbackConstName}, type ${localeTypeName} } from './${typesModule}.js';\n`
+  const typesImportLine = hasLocaleType
+    ? hasLocaleFallback
+      ? `import { ${localeFallbackConstName}, type ${localeTypeName} } from '${typesImport}';\n`
+      : `import type { ${localeTypeName} } from '${typesImport}';\n`
     : "";
+  const localesParamType = hasLocaleType ? `readonly ${localeTypeName}[]` : "readonly string[]";
+  const projectLocalesFallbackArg = hasLocaleFallback ? `, ${localeFallbackConstName}` : "";
 
   return (
     `${GENERATED_FILE_BANNER}` +
-    `import { ${providerClass} } from '@xndrjs/i18n';\n` +
-    `import { dictionary } from './${dictionaryModule}.js';\n` +
+    `import { ${providerClass}, projectLocales as projectLocalesCore, type KeyDictionary } from '@xndrjs/i18n';\n` +
+    `import { dictionary } from '${dictionaryImport}';\n` +
     initialDictionaryImport +
-    fallbackImport +
+    typesImportLine +
     `\n` +
     `export function ${factoryName}(\n` +
     `  initialDictionary: ${initialDictionaryType} = dictionary,\n` +
     `) {\n` +
     `  return new ${providerClass}<${providerTypeArgs}>(initialDictionary${providerOptions});\n` +
+    `}\n` +
+    `\n` +
+    `export function projectLocales(\n` +
+    `  dictionary: KeyDictionary,\n` +
+    `  locales: ${localesParamType},\n` +
+    `): KeyDictionary {\n` +
+    `  return projectLocalesCore(dictionary, locales${projectLocalesFallbackArg});\n` +
     `}\n`
   );
 }