@xndrjs/i18n 0.5.0 → 0.6.0-alpha.1

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

@@ -1,4 +1,12 @@
-import { mkdtempSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import {
+  mkdtempSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
@@ -168,6 +176,7 @@ describe("generate-i18n-types", () => {
     expect(schema).toContain("mode: 'multi' as const");
     expect(schema).toContain("validateExternalDictionary");
     expect(schema).toContain("validateExternalNamespace");
+    expect(schema).toContain("validateExternalNamespaceCore");
     expect(schema).toContain('"name": "string"');
   });
 
@@ -228,6 +237,7 @@ describe("generate-i18n-types", () => {
     expect(schema).toContain("mode: 'single' as const");
     expect(schema).toContain("validateExternalDictionary");
     expect(schema).not.toContain("validateExternalNamespaceImpl");
+    expect(schema).not.toContain("validateExternalNamespaceCore");
   });
 
   it("generates flat types for single-file config", () => {
@@ -1038,7 +1048,6 @@ describe("generate-i18n-types", () => {
           user: "src/i18n/translations/user.json",
           billing: "src/i18n/translations/billing.json",
         },
-        loadOnInit: ["default"],
         delivery: "split-by-locale",
         typesOutput: "src/i18n/generated/i18n-types.generated.ts",
         dictionaryOutput: "src/i18n/generated/dictionary.generated.ts",
@@ -1070,34 +1079,28 @@ describe("generate-i18n-types", () => {
     ).toThrow();
 
     const types = readFileSync(join(tempDir, "src/i18n/generated/i18n-types.generated.ts"), "utf8");
-    const dictionary = readFileSync(
-      join(tempDir, "src/i18n/generated/dictionary.generated.ts"),
-      "utf8"
-    );
     const loaders = readFileSync(
       join(tempDir, "src/i18n/generated/namespace-loaders.generated.ts"),
       "utf8"
     );
 
+    expect(existsSync(join(tempDir, "src/i18n/generated/dictionary.generated.ts"))).toBe(false);
+    expect(result.stdout).not.toContain("dictionary.generated.ts");
+
     expect(types).toContain("welcome: Partial<Record<AppLocale, string>>;");
     expect(types).toContain("invoice_summary: Partial<Record<AppLocale, string>>;");
     expect(types).not.toContain("typeof import");
     expect(types).toContain("export type AppLocale = 'en' | 'it'");
     expect(types).toContain("invoice_summary: { count: number }");
 
-    expect(dictionary).toContain("import defaultEn from './translations/default.en.json';");
-    expect(dictionary).toContain("import defaultIt from './translations/default.it.json';");
-    expect(dictionary).toContain(
-      "export function defaultDictionaryFor(locale: AppLocale): InitialSchema"
-    );
-    expect(dictionary).toContain("default: defaultByLocale[locale],");
-    expect(dictionary).not.toContain("as unknown as");
-    expect(dictionary).not.toContain("export const defaultDictionary");
-    expect(dictionary).not.toContain("billingEn");
+    expect(types).toContain("export type LoadOnInitNamespace = never;");
+    expect(types).toContain("export type LazyNamespace = 'default' | 'user' | 'billing';");
 
     expect(loaders).toContain(
       "[K in LazyNamespace]: (locale: AppLocale) => Promise<AppSchema[K]>;"
     );
+    expect(loaders).toContain("export async function ensureNamespacesLoadedForLocale(");
+    expect(loaders).toContain("default: (locale) => {");
     expect(loaders).toContain("billing: (locale) => {");
     expect(loaders).toContain('case "it":');
     expect(loaders).toContain(
@@ -1111,6 +1114,42 @@ describe("generate-i18n-types", () => {
     expect(loaders).not.toContain("import('./translations/billing.json')");
   });
 
+  it("omits dictionaryOutput in split mode and removes stale dictionary at the default path", () => {
+    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({
+        welcome: { en: "Welcome {name}!", it: "Benvenuto {name}!" },
+      })
+    );
+    writeFileSync(
+      join(tempDir, "src/i18n/generated/dictionary.generated.ts"),
+      "// stale dictionary manifest\n"
+    );
+    writeFileSync(
+      join(tempDir, "i18n.codegen.json"),
+      JSON.stringify({
+        namespaces: {
+          default: "src/i18n/translations/default.json",
+        },
+        delivery: "split-by-locale",
+        typesOutput: "src/i18n/generated/i18n-types.generated.ts",
+        instanceOutput: "src/i18n/generated/instance.generated.ts",
+        namespaceLoadersOutput: "src/i18n/generated/namespace-loaders.generated.ts",
+        paramsTypeName: "AppParams",
+        schemaTypeName: "AppSchema",
+      })
+    );
+
+    const result = runCodegen(tempDir);
+    expect(result.status).toBe(0);
+    expect(existsSync(join(tempDir, "src/i18n/generated/dictionary.generated.ts"))).toBe(false);
+    expect(result.stdout).not.toContain("dictionary.generated.ts");
+  });
+
   it("writes delivery json under deliveryOutput when it differs from typesOutput directory", () => {
     tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-codegen-"));
     mkdirSync(join(tempDir, "src/i18n/translations"), { recursive: true });
@@ -1136,7 +1175,6 @@ describe("generate-i18n-types", () => {
           default: "src/i18n/translations/default.json",
           billing: "src/i18n/translations/billing.yaml",
         },
-        loadOnInit: ["default"],
         delivery: "split-by-locale",
         deliveryOutput: "public/i18n",
         typesOutput: "src/i18n/generated/i18n-types.generated.ts",
@@ -1162,20 +1200,15 @@ describe("generate-i18n-types", () => {
     ) as Record<string, Record<string, string>>;
     expect(billingEn.invoice_summary).toEqual({ en: "You have {count} invoices" });
 
-    const dictionary = readFileSync(
-      join(tempDir, "src/i18n/generated/dictionary.generated.ts"),
-      "utf8"
-    );
     const loaders = readFileSync(
       join(tempDir, "src/i18n/generated/namespace-loaders.generated.ts"),
       "utf8"
     );
 
-    expect(dictionary).toContain(
-      "import defaultEn from '../../../public/i18n/translations/default.en.json';"
-    );
-    expect(dictionary).toContain(
-      "import defaultIt from '../../../public/i18n/translations/default.it.json';"
+    expect(existsSync(join(tempDir, "src/i18n/generated/dictionary.generated.ts"))).toBe(false);
+    expect(loaders).toContain("export async function ensureNamespacesLoadedForLocale(");
+    expect(loaders).toContain(
+      "return import('../../../public/i18n/translations/default.en.json').then((m) => m.default);"
     );
     expect(loaders).toContain(
       "return import('../../../public/i18n/translations/billing.en.json').then((m) => m.default);"
@@ -1274,17 +1307,15 @@ describe("generate-i18n-types", () => {
     expect(enSplit.invoice_summary).toEqual({ en: "You have {count} invoices" });
 
     const types = readFileSync(join(tempDir, "src/i18n/generated/i18n-types.generated.ts"), "utf8");
-    const dictionary = readFileSync(
-      join(tempDir, "src/i18n/generated/dictionary.generated.ts"),
-      "utf8"
-    );
     expect(types).toContain("invoice_summary: Partial<Record<AppLocale, string>>;");
     expect(types).not.toContain("typeof import");
-    expect(dictionary).toContain("import billingEn from './translations/billing.en.json';");
-    expect(dictionary).toContain(
-      "export function defaultDictionaryFor(locale: AppLocale): AppSchema"
+    expect(types).toContain("export type LazyNamespace = 'billing';");
+    expect(existsSync(join(tempDir, "src/i18n/generated/dictionary.generated.ts"))).toBe(false);
+    const loaders = readFileSync(
+      join(tempDir, "src/i18n/generated/namespace-loaders.generated.ts"),
+      "utf8"
     );
-    expect(dictionary).toContain("billing: billingByLocale[locale],");
+    expect(loaders).toContain("export async function ensureNamespacesLoadedForLocale(");
   });
 
   it("emits defaultDictionaryFor in single mode with split-by-locale delivery", () => {
@@ -1413,7 +1444,6 @@ describe("generate-i18n-types", () => {
           default: "src/i18n/translations/default.json",
           billing: "src/i18n/translations/billing.json",
         },
-        loadOnInit: ["default"],
         delivery: "custom",
         deliveryArtifacts: {
           eu: ["it", "fr"],
@@ -1461,10 +1491,6 @@ describe("generate-i18n-types", () => {
     ).toThrow();
 
     const types = readFileSync(join(tempDir, "src/i18n/generated/i18n-types.generated.ts"), "utf8");
-    const dictionary = readFileSync(
-      join(tempDir, "src/i18n/generated/dictionary.generated.ts"),
-      "utf8"
-    );
     const loaders = readFileSync(
       join(tempDir, "src/i18n/generated/namespace-loaders.generated.ts"),
       "utf8"
@@ -1488,6 +1514,11 @@ describe("generate-i18n-types", () => {
     ).toThrow();
 
     expect(types).toContain("export type AppDeliveryArea = 'eu' | 'us';");
+    expect(types).toContain("export const DELIVERY_ARTIFACTS = {");
+    expect(types).toContain('"eu": ["fr", "it"] as const');
+    expect(types).toContain('"us": ["en-US"] as const');
+    expect(types).toContain("} as const satisfies Record<AppDeliveryArea, readonly AppLocale[]>;");
+    expect(types).toContain("export type AppDeliveryArtifacts = typeof DELIVERY_ARTIFACTS;");
     expect(types).toContain("export const LOCALE_DELIVERY_AREA = {");
     expect(types).toContain('"it": "eu"');
     expect(types).toContain('"fr": "eu"');
@@ -1501,19 +1532,17 @@ describe("generate-i18n-types", () => {
     expect(types).not.toContain("typeof import");
     expect(types).toContain("invoice_summary: { count: number }");
 
-    expect(dictionary).toContain("import defaultEu from './translations/default.eu.json';");
-    expect(dictionary).toContain("import defaultUs from './translations/default.us.json';");
-    expect(dictionary).toContain(
-      "export function defaultDictionaryFor(area: AppDeliveryArea): InitialSchema"
-    );
-    expect(dictionary).toContain("default: defaultByArea[area],");
-    expect(dictionary).not.toContain("as unknown as");
-    expect(dictionary).not.toContain("export const defaultDictionary");
-    expect(dictionary).not.toContain("billingEu");
+    expect(existsSync(join(tempDir, "src/i18n/generated/dictionary.generated.ts"))).toBe(false);
+    expect(result.stdout).not.toContain("dictionary.generated.ts");
+
+    expect(types).toContain("export type LoadOnInitNamespace = never;");
+    expect(types).toContain("export type LazyNamespace = 'default' | 'billing';");
 
     expect(loaders).toContain(
       "[K in LazyNamespace]: (area: AppDeliveryArea) => Promise<AppSchema[K]>;"
     );
+    expect(loaders).toContain("export async function ensureNamespacesLoadedForArea(");
+    expect(loaders).toContain("default: (area) => {");
     expect(loaders).toContain("billing: (area) => {");
     expect(loaders).toContain('case "eu":');
     expect(loaders).toContain('case "us":');
@@ -1630,19 +1659,16 @@ describe("generate-i18n-types", () => {
     expect(usSplit.invoice_summary).toEqual({ "en-US": "You have {count} invoices" });
 
     const types = readFileSync(join(tempDir, "src/i18n/generated/i18n-types.generated.ts"), "utf8");
-    const dictionary = readFileSync(
-      join(tempDir, "src/i18n/generated/dictionary.generated.ts"),
-      "utf8"
-    );
     expect(types).toContain("export type AppDeliveryArea = 'eu' | 'us';");
     expect(types).toContain("invoice_summary: Partial<Record<AppLocale, string>>;");
     expect(types).not.toContain("typeof import");
-    expect(dictionary).toContain("import billingEu from './translations/billing.eu.json';");
-    expect(dictionary).toContain("import billingUs from './translations/billing.us.json';");
-    expect(dictionary).toContain(
-      "export function defaultDictionaryFor(area: AppDeliveryArea): AppSchema"
+    expect(types).toContain("export type LazyNamespace = 'billing';");
+    expect(existsSync(join(tempDir, "src/i18n/generated/dictionary.generated.ts"))).toBe(false);
+    const loaders = readFileSync(
+      join(tempDir, "src/i18n/generated/namespace-loaders.generated.ts"),
+      "utf8"
     );
-    expect(dictionary).toContain("billing: billingByArea[area],");
+    expect(loaders).toContain("export async function ensureNamespacesLoadedForArea(");
   });
 
   it("emits defaultDictionaryFor in single mode with custom delivery", () => {

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

@@ -3,6 +3,7 @@ import path from "node:path";
 import {
   loadConfig,
   resolveDeliveryOutputDir,
+  resolveDictionaryOutputPath,
   resolveLoadOnInit,
   resolveNamespaces,
 } from "./config.js";
@@ -98,7 +99,7 @@ function main() {
   const { loadOnInitSet, lazyEntries, hasLazy } = resolveLoadOnInit(config, entries, isSingle);
 
   const typesOutputPath = path.resolve(projectRoot, config.typesOutput);
-  const dictionaryOutputPath = path.resolve(projectRoot, config.dictionaryOutput);
+  const dictionaryOutputPath = path.resolve(projectRoot, resolveDictionaryOutputPath(config));
   const instanceOutputPath = path.resolve(projectRoot, config.instanceOutput);
   const typesModule = toModuleBasename(typesOutputPath);
 
@@ -188,15 +189,21 @@ function main() {
   });
 
   writeFileIfChanged(typesOutputPath, typesContent);
-  writeFileIfChanged(dictionaryOutputPath, dictionaryContent);
-  writeFileIfChanged(instanceOutputPath, instanceContent);
 
   const generatedFiles = [
     path.relative(projectRoot, typesOutputPath),
-    path.relative(projectRoot, dictionaryOutputPath),
     path.relative(projectRoot, instanceOutputPath),
   ];
 
+  if (dictionaryContent !== null) {
+    writeFileIfChanged(dictionaryOutputPath, dictionaryContent);
+    generatedFiles.splice(1, 0, path.relative(projectRoot, dictionaryOutputPath));
+  } else if (fs.existsSync(dictionaryOutputPath)) {
+    fs.unlinkSync(dictionaryOutputPath);
+  }
+
+  writeFileIfChanged(instanceOutputPath, instanceContent);
+
   if (config.dictionarySchemaOutput) {
     const dictionarySchemaOutputPath = path.resolve(projectRoot, config.dictionarySchemaOutput);
     const dictionarySpecBlock = formatDictionarySpecBlock(isSingle, entries, argsSpecByNamespace);
@@ -226,10 +233,14 @@ function main() {
       loadersOutputPath: namespaceLoadersOutputPath,
       lazyEntries: lazyEntriesWithPaths,
       schemaTypeName,
+      paramsTypeName,
       localeTypeName,
+      localeFallbackConstName,
+      hasLocaleFallback: Boolean(config.localeFallback),
       typesModule,
       importExtension,
       projectRoot,
+      isSingle,
       delivery,
       splitPathsByNamespace,
       ...(delivery === "split-by-locale" ? { requestLocales: requestLocalesList } : {}),

package/src/codegen-config/index.ts

@@ -7,6 +7,7 @@ export {
   codegenConfigKeys,
   DELIVERY_MODES,
   resolveDeliveryOutputDir,
+  resolveDictionaryOutputPath,
 } from "../codegen/codegen-config-schema.js";
 
 export type { DeliveryArtifactsMap } from "../codegen/delivery-artifacts.js";