@xndrjs/i18n 0.2.1 → 0.3.1

package/src/codegen/emit/namespace-loaders-file.ts

@@ -1,5 +1,5 @@
-import { GENERATED_FILE_BANNER, toImportPath } from "../paths.js";
-import type { NamespaceEntry } from "../types.js";
+import { GENERATED_FILE_BANNER, toImportPath, toRelativeModuleImport } from "../paths.js";
+import type { ImportExtension, NamespaceEntry } from "../types.js";
 
 export function formatNamespaceLoadersFile(
   loadersOutputPath: string,
@@ -8,8 +8,12 @@ export function formatNamespaceLoadersFile(
   typesModule: string,
   dictionarySchemaModule: string,
   instanceModule: string,
-  factoryName: string
+  factoryName: string,
+  importExtension: ImportExtension
 ): string {
+  const dictionarySchemaImport = toRelativeModuleImport(dictionarySchemaModule, importExtension);
+  const typesImport = toRelativeModuleImport(typesModule, importExtension);
+  const instanceImport = toRelativeModuleImport(instanceModule, importExtension);
   const loaderEntries = lazyEntries
     .map((entry) => {
       const importPath = toImportPath(loadersOutputPath, entry.absolutePath);
@@ -20,9 +24,9 @@ export function formatNamespaceLoadersFile(
   return (
     `${GENERATED_FILE_BANNER}` +
     `import { ensureNamespacesLoadedImpl } from '@xndrjs/i18n';\n` +
-    `import { validateExternalNamespace } from './${dictionarySchemaModule}.js';\n` +
-    `import type { ${schemaTypeName}, LazyNamespace } from './${typesModule}.js';\n` +
-    `import type { ${factoryName} } from './${instanceModule}.js';\n\n` +
+    `import { validateExternalNamespace } from '${dictionarySchemaImport}';\n` +
+    `import type { ${schemaTypeName}, LazyNamespace } from '${typesImport}';\n` +
+    `import type { ${factoryName} } from '${instanceImport}';\n\n` +
     `export const namespaceLoaders: Record<\n` +
     `  LazyNamespace,\n` +
     `  () => Promise<${schemaTypeName}[LazyNamespace]>\n` +

package/src/codegen/generate-i18n-types.test.ts

@@ -73,6 +73,9 @@ describe("generate-i18n-types", () => {
     expect(types).toContain("export const I18N_MODE = 'multi' as const");
     expect(types).toContain("export type AppLocale = 'en'");
     expect(factory).toContain("export function createI18n(");
+    expect(factory).toContain("export function projectLocales(");
+    expect(factory).toContain("locales: readonly AppLocale[]");
+    expect(factory).toContain("projectLocalesCore(dictionary, locales)");
     expect(factory).toContain("IcuTranslationProviderMulti");
     expect(types).toContain("login_button: never");
     expect(types).toContain("welcome: { name: string }");
@@ -289,11 +292,81 @@ describe("generate-i18n-types", () => {
     expect(types).toContain('"de-CH": "en"');
     expect(types).toContain("export type AppLocale = 'de-CH' | 'en'");
     expect(factory).toContain("localeFallback: LOCALE_FALLBACK");
+    expect(factory).toContain("projectLocalesCore(dictionary, locales, LOCALE_FALLBACK)");
     expect(factory).toContain(
       "IcuTranslationProviderSingle<AppSchema, AppParams, AppLocale, typeof LOCALE_FALLBACK>"
     );
   });
 
+  it("enriches LOCALE_FALLBACK with null for dictionary locales missing from config", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-codegen-"));
+    mkdirSync(join(tempDir, "src/i18n/translations"), { recursive: true });
+
+    writeFileSync(
+      join(tempDir, "src/i18n/translations/translations.json"),
+      JSON.stringify({
+        login_button: { en: "Login", fr: "Connexion" },
+      })
+    );
+    writeFileSync(
+      join(tempDir, "i18n.codegen.json"),
+      JSON.stringify({
+        dictionary: "src/i18n/translations/translations.json",
+        typesOutput: "src/i18n/i18n-types.generated.ts",
+        dictionaryOutput: "src/i18n/dictionary.generated.ts",
+        instanceOutput: "src/i18n/instance.generated.ts",
+        paramsTypeName: "AppParams",
+        schemaTypeName: "AppSchema",
+        localeFallback: {
+          en: null,
+          it: "en",
+        },
+      })
+    );
+
+    const result = runCodegen(tempDir);
+    expect(result.status).toBe(0);
+
+    const types = readFileSync(join(tempDir, "src/i18n/i18n-types.generated.ts"), "utf8");
+    expect(types).toContain('"fr": null');
+    expect(types).toContain('"it": "en"');
+    expect(types).toContain("export type AppLocale = 'en' | 'fr' | 'it'");
+  });
+
+  it("does not emit LOCALE_FALLBACK when localeFallback is absent from config", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-codegen-"));
+    mkdirSync(join(tempDir, "src/i18n/translations"), { recursive: true });
+
+    writeFileSync(
+      join(tempDir, "src/i18n/translations/translations.json"),
+      JSON.stringify({
+        login_button: { en: "Login", it: "Accedi" },
+      })
+    );
+    writeFileSync(
+      join(tempDir, "i18n.codegen.json"),
+      JSON.stringify({
+        dictionary: "src/i18n/translations/translations.json",
+        typesOutput: "src/i18n/i18n-types.generated.ts",
+        dictionaryOutput: "src/i18n/dictionary.generated.ts",
+        instanceOutput: "src/i18n/instance.generated.ts",
+        paramsTypeName: "AppParams",
+        schemaTypeName: "AppSchema",
+      })
+    );
+
+    const result = runCodegen(tempDir);
+    expect(result.status).toBe(0);
+
+    const types = readFileSync(join(tempDir, "src/i18n/i18n-types.generated.ts"), "utf8");
+    const factory = readFileSync(join(tempDir, "src/i18n/instance.generated.ts"), "utf8");
+    expect(types).not.toContain("export const LOCALE_FALLBACK");
+    expect(factory).not.toContain("localeFallback:");
+    expect(factory).toContain("projectLocalesCore(dictionary, locales)");
+    expect(factory).not.toContain("LOCALE_FALLBACK");
+    expect(types).toContain("export type AppLocale = 'en' | 'it'");
+  });
+
   it("fails on circular locale fallback in config", () => {
     tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-codegen-"));
     mkdirSync(join(tempDir, "src/i18n/translations"), { recursive: true });
@@ -601,4 +674,311 @@ describe("generate-i18n-types", () => {
     expect(types).toContain("default: {");
     expect(factory).toContain("IcuTranslationProviderMulti");
   });
+
+  it("omits import extension by default between generated modules", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-codegen-"));
+    mkdirSync(join(tempDir, "src/i18n/translations"), { recursive: true });
+
+    writeFileSync(
+      join(tempDir, "src/i18n/translations/translations.json"),
+      JSON.stringify({ welcome: { en: "Welcome {name}!" } })
+    );
+    writeFileSync(
+      join(tempDir, "i18n.codegen.json"),
+      JSON.stringify({
+        dictionary: "src/i18n/translations/translations.json",
+        typesOutput: "src/i18n/i18n-types.generated.ts",
+        dictionaryOutput: "src/i18n/dictionary.generated.ts",
+        instanceOutput: "src/i18n/instance.generated.ts",
+        paramsTypeName: "AppParams",
+        schemaTypeName: "AppSchema",
+      })
+    );
+
+    const result = runCodegen(tempDir);
+    expect(result.status).toBe(0);
+
+    const dictionary = readFileSync(join(tempDir, "src/i18n/dictionary.generated.ts"), "utf8");
+    const factory = readFileSync(join(tempDir, "src/i18n/instance.generated.ts"), "utf8");
+    expect(dictionary).toContain("from './i18n-types.generated'");
+    expect(factory).toContain("from './dictionary.generated'");
+    expect(factory).toContain("from './i18n-types.generated'");
+    expect(dictionary).not.toContain(".generated.js");
+    expect(dictionary).not.toContain(".generated.ts");
+    expect(factory).not.toContain(".generated.js");
+    expect(factory).not.toContain(".generated.ts");
+  });
+
+  it("supports importExtension .ts", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-codegen-"));
+    mkdirSync(join(tempDir, "src/i18n/translations"), { recursive: true });
+
+    writeFileSync(
+      join(tempDir, "src/i18n/translations/translations.json"),
+      JSON.stringify({ welcome: { en: "Welcome {name}!" } })
+    );
+    writeFileSync(
+      join(tempDir, "i18n.codegen.json"),
+      JSON.stringify({
+        dictionary: "src/i18n/translations/translations.json",
+        typesOutput: "src/i18n/i18n-types.generated.ts",
+        dictionaryOutput: "src/i18n/dictionary.generated.ts",
+        instanceOutput: "src/i18n/instance.generated.ts",
+        importExtension: ".ts",
+        paramsTypeName: "AppParams",
+        schemaTypeName: "AppSchema",
+      })
+    );
+
+    const result = runCodegen(tempDir);
+    expect(result.status).toBe(0);
+
+    const factory = readFileSync(join(tempDir, "src/i18n/instance.generated.ts"), "utf8");
+    expect(factory).toContain("from './dictionary.generated.ts'");
+    expect(factory).toContain("from './i18n-types.generated.ts'");
+  });
+
+  it("supports importExtension .js for NodeNext ESM projects", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-codegen-"));
+    mkdirSync(join(tempDir, "src/i18n/translations"), { recursive: true });
+
+    writeFileSync(
+      join(tempDir, "src/i18n/translations/translations.json"),
+      JSON.stringify({ welcome: { en: "Welcome {name}!" } })
+    );
+    writeFileSync(
+      join(tempDir, "i18n.codegen.json"),
+      JSON.stringify({
+        dictionary: "src/i18n/translations/translations.json",
+        typesOutput: "src/i18n/i18n-types.generated.ts",
+        dictionaryOutput: "src/i18n/dictionary.generated.ts",
+        instanceOutput: "src/i18n/instance.generated.ts",
+        importExtension: ".js",
+        paramsTypeName: "AppParams",
+        schemaTypeName: "AppSchema",
+      })
+    );
+
+    const result = runCodegen(tempDir);
+    expect(result.status).toBe(0);
+
+    const factory = readFileSync(join(tempDir, "src/i18n/instance.generated.ts"), "utf8");
+    expect(factory).toContain("from './dictionary.generated.js'");
+    expect(factory).toContain("from './i18n-types.generated.js'");
+  });
+
+  it("fails when importExtension is invalid", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-codegen-"));
+    mkdirSync(join(tempDir, "src/i18n/translations"), { recursive: true });
+
+    writeFileSync(
+      join(tempDir, "src/i18n/translations/translations.json"),
+      JSON.stringify({ welcome: { en: "Welcome {name}!" } })
+    );
+    writeFileSync(
+      join(tempDir, "i18n.codegen.json"),
+      JSON.stringify({
+        dictionary: "src/i18n/translations/translations.json",
+        typesOutput: "src/i18n/i18n-types.generated.ts",
+        dictionaryOutput: "src/i18n/dictionary.generated.ts",
+        instanceOutput: "src/i18n/instance.generated.ts",
+        importExtension: ".mjs",
+        paramsTypeName: "AppParams",
+        schemaTypeName: "AppSchema",
+      })
+    );
+
+    const result = runCodegen(tempDir);
+    expect(result.status).not.toBe(0);
+    expect(result.stderr).toContain('importExtension must be "none", ".ts", or ".js"');
+  });
+
+  it("compiles yaml dictionaries to json and generates json imports", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-codegen-"));
+    mkdirSync(join(tempDir, "src/i18n/translations"), { recursive: true });
+    mkdirSync(join(tempDir, "src/i18n/generated"), { recursive: true });
+
+    writeFileSync(
+      join(tempDir, "src/i18n/translations/translations.yaml"),
+      `welcome:
+  en: |
+    Line one
+    Line two
+  it: |
+    Riga uno
+    Riga due
+`
+    );
+    writeFileSync(
+      join(tempDir, "i18n.codegen.json"),
+      JSON.stringify({
+        dictionary: "src/i18n/translations/translations.yaml",
+        typesOutput: "src/i18n/generated/i18n-types.generated.ts",
+        dictionaryOutput: "src/i18n/generated/dictionary.generated.ts",
+        instanceOutput: "src/i18n/generated/instance.generated.ts",
+        paramsTypeName: "AppParams",
+        schemaTypeName: "AppSchema",
+      })
+    );
+
+    const result = runCodegen(tempDir);
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain(
+      "Compiled: src/i18n/translations/translations.yaml → src/i18n/generated/translations/translations.json"
+    );
+
+    const compiled = JSON.parse(
+      readFileSync(join(tempDir, "src/i18n/generated/translations/translations.json"), "utf8")
+    ) as Record<string, Record<string, string>>;
+    expect(compiled.welcome?.en).toBe("Line one\nLine two\n");
+
+    const dictionary = readFileSync(
+      join(tempDir, "src/i18n/generated/dictionary.generated.ts"),
+      "utf8"
+    );
+    const types = readFileSync(join(tempDir, "src/i18n/generated/i18n-types.generated.ts"), "utf8");
+    expect(dictionary).toContain("from './translations/translations.json'");
+    expect(types).toContain("typeof import('./translations/translations.json')");
+  });
+
+  it("supports mixed json and yaml namespaces", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-codegen-"));
+    mkdirSync(join(tempDir, "src/i18n/translations"), { recursive: true });
+    mkdirSync(join(tempDir, "src/i18n/generated"), { recursive: true });
+
+    writeFileSync(
+      join(tempDir, "src/i18n/translations/default.json"),
+      JSON.stringify({
+        login_button: { en: "Login", it: "Accedi" },
+      })
+    );
+    writeFileSync(
+      join(tempDir, "src/i18n/translations/billing.yaml"),
+      `invoice_summary:
+  en: You have {count} invoices
+`
+    );
+    writeFileSync(
+      join(tempDir, "i18n.codegen.json"),
+      JSON.stringify({
+        namespaces: {
+          default: "src/i18n/translations/default.json",
+          billing: "src/i18n/translations/billing.yaml",
+        },
+        typesOutput: "src/i18n/generated/i18n-types.generated.ts",
+        dictionaryOutput: "src/i18n/generated/dictionary.generated.ts",
+        instanceOutput: "src/i18n/generated/instance.generated.ts",
+        paramsTypeName: "AppParams",
+        schemaTypeName: "AppSchema",
+      })
+    );
+
+    const result = runCodegen(tempDir);
+    expect(result.status).toBe(0);
+
+    const dictionary = readFileSync(
+      join(tempDir, "src/i18n/generated/dictionary.generated.ts"),
+      "utf8"
+    );
+    const types = readFileSync(join(tempDir, "src/i18n/generated/i18n-types.generated.ts"), "utf8");
+    expect(dictionary).toContain("from '../translations/default.json'");
+    expect(dictionary).toContain("from './translations/billing.json'");
+    expect(types).toContain("default: typeof import('../translations/default.json')");
+    expect(types).toContain("billing: typeof import('./translations/billing.json')");
+  });
+
+  it("generates lazy loaders that import compiled json for yaml namespaces", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-codegen-"));
+    mkdirSync(join(tempDir, "src/i18n/translations"), { recursive: true });
+    mkdirSync(join(tempDir, "src/i18n/generated"), { recursive: true });
+
+    writeFileSync(
+      join(tempDir, "src/i18n/translations/default.json"),
+      JSON.stringify({
+        login_button: { en: "Login" },
+      })
+    );
+    writeFileSync(
+      join(tempDir, "src/i18n/translations/billing.yaml"),
+      `invoice_summary:
+  en: You have {count} invoices
+`
+    );
+    writeFileSync(
+      join(tempDir, "i18n.codegen.json"),
+      JSON.stringify({
+        namespaces: {
+          default: "src/i18n/translations/default.json",
+          billing: "src/i18n/translations/billing.yaml",
+        },
+        loadOnInit: ["default"],
+        typesOutput: "src/i18n/generated/i18n-types.generated.ts",
+        dictionaryOutput: "src/i18n/generated/dictionary.generated.ts",
+        instanceOutput: "src/i18n/generated/instance.generated.ts",
+        dictionarySchemaOutput: "src/i18n/generated/dictionary-schema.generated.ts",
+        namespaceLoadersOutput: "src/i18n/generated/namespace-loaders.generated.ts",
+        paramsTypeName: "AppParams",
+        schemaTypeName: "AppSchema",
+      })
+    );
+
+    const result = runCodegen(tempDir);
+    expect(result.status).toBe(0);
+
+    const loaders = readFileSync(
+      join(tempDir, "src/i18n/generated/namespace-loaders.generated.ts"),
+      "utf8"
+    );
+    expect(loaders).toContain("import('./translations/billing.json')");
+    expect(loaders).not.toContain("billing.yaml");
+  });
+
+  it("fails when dictionary extension is unsupported", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-codegen-"));
+    mkdirSync(join(tempDir, "src/i18n/translations"), { recursive: true });
+
+    writeFileSync(join(tempDir, "src/i18n/translations/translations.toml"), "welcome = {}");
+    writeFileSync(
+      join(tempDir, "i18n.codegen.json"),
+      JSON.stringify({
+        dictionary: "src/i18n/translations/translations.toml",
+        typesOutput: "src/i18n/i18n-types.generated.ts",
+        dictionaryOutput: "src/i18n/dictionary.generated.ts",
+        instanceOutput: "src/i18n/instance.generated.ts",
+        paramsTypeName: "AppParams",
+        schemaTypeName: "AppSchema",
+      })
+    );
+
+    const result = runCodegen(tempDir);
+    expect(result.status).not.toBe(0);
+    expect(result.stderr).toContain("unsupported dictionary extension");
+  });
+
+  it("fails when yaml dictionary has invalid shape", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-codegen-"));
+    mkdirSync(join(tempDir, "src/i18n/translations"), { recursive: true });
+
+    writeFileSync(
+      join(tempDir, "src/i18n/translations/translations.yaml"),
+      `welcome:
+  en: 123
+`
+    );
+    writeFileSync(
+      join(tempDir, "i18n.codegen.json"),
+      JSON.stringify({
+        dictionary: "src/i18n/translations/translations.yaml",
+        typesOutput: "src/i18n/i18n-types.generated.ts",
+        dictionaryOutput: "src/i18n/dictionary.generated.ts",
+        instanceOutput: "src/i18n/instance.generated.ts",
+        paramsTypeName: "AppParams",
+        schemaTypeName: "AppSchema",
+      })
+    );
+
+    const result = runCodegen(tempDir);
+    expect(result.status).not.toBe(0);
+    expect(result.stderr).toContain("must be a string");
+  });
 });

package/src/codegen/generate-i18n-types.ts

@@ -11,7 +11,9 @@ import { formatNamespaceLoadersFile } from "./emit/namespace-loaders-file.js";
 import { formatTypesFile } from "./emit/types-file.js";
 import { analyzeDictionaries } from "./icu-analysis.js";
 import { collectRequestLocales, validateCodegenLocaleFallback } from "./locale-fallback.js";
-import { fail, toModuleBasename } from "./paths.js";
+import { enrichLocaleFallback } from "./locale-policy.js";
+import { fail, resolveImportExtension, toModuleBasename } from "./paths.js";
+import { prepareDictionaryEntries } from "./read-dictionary.js";
 
 function main() {
   const configArgIndex = process.argv.indexOf("--config");
@@ -26,7 +28,21 @@ function main() {
   }
 
   const config = loadConfig(configPath);
-  const entries = resolveNamespaces(config);
+  const sourceEntries = resolveNamespaces(config);
+  const generatedDirRelative = path.dirname(config.typesOutput);
+  let resolvedEntries;
+  let compiledFiles: string[];
+
+  try {
+    const prepared = prepareDictionaryEntries(projectRoot, sourceEntries, generatedDirRelative);
+    resolvedEntries = prepared.resolvedEntries;
+    compiledFiles = prepared.compiledFiles;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    fail(message);
+  }
+
+  const entries = resolvedEntries;
   const isSingle = Boolean(config.dictionary);
   const { loadOnInitSet, lazyEntries, hasLazy } = resolveLoadOnInit(config, entries, isSingle);
 
@@ -57,6 +73,7 @@ function main() {
   const localeFallbackConstName = config.localeFallbackConstName ?? "LOCALE_FALLBACK";
   const localeFallbackTypeName = `${localeTypeName}Fallback`;
   const factoryName = config.factoryName ?? "createI18n";
+  const importExtension = resolveImportExtension(config);
   const typesModule = toModuleBasename(typesOutputPath);
 
   const requestLocales = collectRequestLocales(locales, config.localeFallback);
@@ -69,6 +86,10 @@ function main() {
     ? entries.filter((entry) => loadOnInitSet.has(entry.namespace))
     : entries;
 
+  const localeFallbackForEmit = config.localeFallback
+    ? enrichLocaleFallback(locales, config.localeFallback)
+    : undefined;
+
   const typesContent = formatTypesFile({
     isSingle,
     entries,
@@ -79,7 +100,7 @@ function main() {
     localeTypeName,
     localeFallbackConstName,
     localeFallbackTypeName,
-    localeFallback: config.localeFallback,
+    localeFallback: localeFallbackForEmit,
     paramsByNamespace,
     requestLocaleUnion,
     hasLazy,
@@ -96,6 +117,7 @@ function main() {
     dictionaryOutputPath,
     typesOutputPath,
     schemaTypeName,
+    importExtension,
   });
 
   const instanceContent = formatInstanceFile({
@@ -109,6 +131,8 @@ function main() {
     localeFallbackConstName,
     factoryName,
     hasLocaleFallback: Boolean(config.localeFallback),
+    hasLocaleType: Boolean(requestLocaleUnion),
+    importExtension,
   });
 
   fs.mkdirSync(path.dirname(typesOutputPath), { recursive: true });
@@ -133,7 +157,8 @@ function main() {
       schemaTypeName,
       typesModule,
       isSingle,
-      dictionarySpecBlock
+      dictionarySpecBlock,
+      importExtension
     );
 
     fs.mkdirSync(path.dirname(dictionarySchemaOutputPath), { recursive: true });
@@ -159,7 +184,8 @@ function main() {
       typesModule,
       toModuleBasename(dictionarySchemaOutputPath),
       toModuleBasename(instanceOutputPath),
-      factoryName
+      factoryName,
+      importExtension
     );
 
     fs.mkdirSync(path.dirname(namespaceLoadersOutputPath), { recursive: true });
@@ -168,6 +194,9 @@ function main() {
   }
 
   console.log(`✅ Generated: ${generatedFiles.join(", ")}`);
+  if (compiledFiles.length > 0) {
+    console.log(`✅ Compiled: ${compiledFiles.join(", ")}`);
+  }
 }
 
 main();

package/src/codegen/icu-analysis.ts

@@ -6,7 +6,8 @@ import {
   mergeVariableMetaAcrossLocales,
   type VariableSpec,
 } from "../icu/extract-variables.js";
-import type { DictionaryJson, NamespaceEntry } from "./types.js";
+import type { NamespaceEntry } from "./types.js";
+import { readDictionaryFile } from "./read-dictionary.js";
 
 export function paramsTypeForVariables(variables: VariableSpec): string {
   const keys = Object.keys(variables);
@@ -47,7 +48,7 @@ export function analyzeDictionaries(
       continue;
     }
 
-    const dictionary = JSON.parse(fs.readFileSync(absolutePath, "utf8")) as DictionaryJson;
+    const dictionary = readDictionaryFile(absolutePath);
     paramsByNamespace[entry.namespace] = {};
     argsSpecByNamespace[entry.namespace] = {};
 

package/src/codegen/locale-policy.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { buildRequiredLocales, enrichLocaleFallback } from "./locale-policy.js";
+
+describe("locale-policy", () => {
+  it("buildRequiredLocales unions dictionary locales with fallback keys and targets", () => {
+    const locales = new Set(["en", "it"]);
+    const fallback = { en: null, "de-CH": "de-DE", "de-DE": "en", it: "en" };
+
+    expect(buildRequiredLocales(locales, fallback)).toEqual(["de-CH", "de-DE", "en", "it"]);
+    expect(buildRequiredLocales(locales)).toEqual(["en", "it"]);
+  });
+
+  it("enrichLocaleFallback adds null for required locales missing from config", () => {
+    const locales = new Set(["en", "fr"]);
+    const fallback = { en: null, it: "en" };
+
+    expect(enrichLocaleFallback(locales, fallback)).toEqual({
+      en: null,
+      fr: null,
+      it: "en",
+    });
+  });
+
+  it("enrichLocaleFallback is a no-op when all required locales are already configured", () => {
+    const locales = new Set(["en", "it"]);
+    const fallback = {
+      en: null,
+      "de-DE": "en",
+      "de-CH": "de-DE",
+      it: "en",
+    };
+
+    expect(enrichLocaleFallback(locales, fallback)).toEqual(fallback);
+  });
+});

package/src/codegen/locale-policy.ts

@@ -0,0 +1,26 @@
+import { collectRequestLocales } from "./locale-fallback.js";
+
+export function buildRequiredLocales(
+  dictionaryLocales: Set<string>,
+  configFallback?: Record<string, string | null>
+): string[] {
+  return [...collectRequestLocales(dictionaryLocales, configFallback)].sort();
+}
+
+export function enrichLocaleFallback(
+  dictionaryLocales: Set<string>,
+  configFallback: Record<string, string | null>
+): Record<string, string | null> {
+  const enriched: Record<string, string | null> = { ...configFallback };
+
+  for (const locale of buildRequiredLocales(dictionaryLocales, configFallback)) {
+    if (!(locale in enriched)) {
+      enriched[locale] = null;
+    }
+  }
+
+  const sortedEntries = Object.entries(enriched).sort(([left], [right]) =>
+    left.localeCompare(right)
+  );
+  return Object.fromEntries(sortedEntries);
+}

package/src/codegen/paths.ts

@@ -1,6 +1,9 @@
 import path from "node:path";
+import type { CodegenConfig, ImportExtension } from "./types.js";
+import { SUPPORTED_IMPORT_EXTENSIONS } from "./types.js";
 
 export const GENERATED_FILE_BANNER = "// Automatically generated code. Do not edit manually.\n";
+export const DEFAULT_IMPORT_EXTENSION: ImportExtension = "none";
 
 export function fail(message: string): never {
   console.error(message);
@@ -10,7 +13,7 @@ export function fail(message: string): never {
 
 export function toImportPath(fromFile: string, toFile: string): string {
   const relative = path.relative(path.dirname(fromFile), toFile).replace(/\\/g, "/");
-  const withoutExt = relative.replace(/\.json$/, "");
+  const withoutExt = relative.replace(/\.(json|ya?ml)$/i, "");
   return withoutExt.startsWith(".") ? withoutExt : `./${withoutExt}`;
 }
 
@@ -18,6 +21,29 @@ export function toModuleBasename(filePath: string): string {
   return path.basename(filePath).replace(/\.ts$/, "");
 }
 
+export function resolveImportExtension(
+  config: Pick<CodegenConfig, "importExtension">
+): ImportExtension {
+  const extension = config.importExtension ?? DEFAULT_IMPORT_EXTENSION;
+  if (!SUPPORTED_IMPORT_EXTENSIONS.includes(extension)) {
+    fail(
+      `[Codegen Error] importExtension must be "none", ".ts", or ".js", got ${JSON.stringify(extension)}.`
+    );
+  }
+  return extension;
+}
+
+export function importExtensionSuffix(importExtension: ImportExtension): string {
+  return importExtension === "none" ? "" : importExtension;
+}
+
+export function toRelativeModuleImport(
+  moduleBasename: string,
+  importExtension: ImportExtension
+): string {
+  return `./${moduleBasename}${importExtensionSuffix(importExtension)}`;
+}
+
 export function toImportIdentifier(namespace: string): string {
   const safe = namespace.replace(/[^a-zA-Z0-9_$]/g, "_");
   if (/^[0-9]/.test(safe)) {