@xndrjs/i18n 0.2.1 → 0.3.0

package/src/codegen/read-dictionary.test.ts

@@ -0,0 +1,104 @@
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it, afterEach } from "vitest";
+import {
+  getDictionaryFormat,
+  prepareDictionaryEntries,
+  readDictionaryFile,
+  resolveCompiledJsonPath,
+} from "./read-dictionary.js";
+
+describe("read-dictionary", () => {
+  let tempDir: string;
+
+  afterEach(() => {
+    if (tempDir) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("detects dictionary formats from file extension", () => {
+    expect(getDictionaryFormat("translations/default.json")).toBe("json");
+    expect(getDictionaryFormat("translations/default.yaml")).toBe("yaml");
+    expect(getDictionaryFormat("translations/default.yml")).toBe("yaml");
+    expect(getDictionaryFormat("translations/default.toml")).toBeNull();
+  });
+
+  it("resolves compiled json path under the generated output directory", () => {
+    expect(
+      resolveCompiledJsonPath("src/i18n/translations/billing.yaml", "src/i18n/generated")
+    ).toBe("src/i18n/generated/translations/billing.json");
+    expect(resolveCompiledJsonPath("translations/billing.yml", "generated")).toBe(
+      "generated/translations/billing.json"
+    );
+  });
+
+  it("reads multiline yaml dictionaries", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-read-dict-"));
+    const yamlPath = join(tempDir, "welcome.yaml");
+    writeFileSync(
+      yamlPath,
+      `welcome:
+  en: |
+    Line one
+    Line two
+  it: Ciao {name}
+`
+    );
+
+    const dictionary = readDictionaryFile(yamlPath);
+    expect(dictionary.welcome?.en).toBe("Line one\nLine two\n");
+    expect(dictionary.welcome?.it).toBe("Ciao {name}");
+  });
+
+  it("compiles yaml sources to json under the generated output directory", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-read-dict-"));
+    mkdirSync(join(tempDir, "src/i18n/translations"), { recursive: true });
+    mkdirSync(join(tempDir, "src/i18n/generated"), { recursive: true });
+    writeFileSync(
+      join(tempDir, "src/i18n/translations/billing.yaml"),
+      `invoice_summary:
+  en: You have {count} invoices
+`
+    );
+
+    const result = prepareDictionaryEntries(
+      tempDir,
+      [{ namespace: "billing", filePath: "src/i18n/translations/billing.yaml" }],
+      "src/i18n/generated"
+    );
+
+    expect(result.resolvedEntries).toEqual([
+      { namespace: "billing", filePath: "src/i18n/generated/translations/billing.json" },
+    ]);
+    expect(result.compiledFiles).toEqual([
+      "src/i18n/translations/billing.yaml → src/i18n/generated/translations/billing.json",
+    ]);
+
+    const compiled = JSON.parse(
+      readFileSync(join(tempDir, "src/i18n/generated/translations/billing.json"), "utf8")
+    ) as Record<string, Record<string, string>>;
+    expect(compiled.invoice_summary?.en).toBe("You have {count} invoices");
+  });
+
+  it("keeps json sources unchanged", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-read-dict-"));
+    mkdirSync(join(tempDir, "translations"), { recursive: true });
+    writeFileSync(
+      join(tempDir, "translations/default.json"),
+      JSON.stringify({ welcome: { en: "Welcome {name}!" } })
+    );
+
+    const result = prepareDictionaryEntries(
+      tempDir,
+      [{ namespace: "default", filePath: "translations/default.json" }],
+      "generated"
+    );
+
+    expect(result.resolvedEntries).toEqual([
+      { namespace: "default", filePath: "translations/default.json" },
+    ]);
+    expect(result.compiledFiles).toEqual([]);
+  });
+});

package/src/codegen/read-dictionary.ts

@@ -0,0 +1,133 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import type { DictionaryJson, NamespaceEntry } from "./types.js";
+
+export const SUPPORTED_DICTIONARY_EXTENSIONS = [".json", ".yaml", ".yml"] as const;
+export type DictionaryFormat = "json" | "yaml";
+
+export function getDictionaryFormat(filePath: string): DictionaryFormat | null {
+  const extension = path.extname(filePath).toLowerCase();
+  if (extension === ".json") {
+    return "json";
+  }
+  if (extension === ".yaml" || extension === ".yml") {
+    return "yaml";
+  }
+  return null;
+}
+
+export function resolveCompiledJsonPath(sourcePath: string, generatedDirRelative: string): string {
+  const baseName = `${path.basename(sourcePath, path.extname(sourcePath))}.json`;
+  return path.join(generatedDirRelative, "translations", baseName).replace(/\\/g, "/");
+}
+
+function assertDictionaryShape(value: unknown, context: string): asserts value is DictionaryJson {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`[Codegen Error] ${context} must be a plain object.`);
+  }
+
+  for (const [key, localesByKey] of Object.entries(value)) {
+    if (localesByKey === null || typeof localesByKey !== "object" || Array.isArray(localesByKey)) {
+      throw new Error(`[Codegen Error] ${context}: key "${key}" must map locales to strings.`);
+    }
+
+    for (const [locale, template] of Object.entries(localesByKey)) {
+      if (typeof template !== "string") {
+        throw new Error(
+          `[Codegen Error] ${context}: key "${key}", locale "${locale}" must be a string.`
+        );
+      }
+    }
+  }
+}
+
+export function readDictionaryFile(absolutePath: string): DictionaryJson {
+  const format = getDictionaryFormat(absolutePath);
+  if (!format) {
+    throw new Error(
+      `[Codegen Error] Unsupported dictionary format "${path.extname(absolutePath)}" for ${absolutePath}. Use .json, .yaml, or .yml.`
+    );
+  }
+
+  const source = fs.readFileSync(absolutePath, "utf8");
+  let parsed: unknown;
+
+  try {
+    parsed = format === "json" ? JSON.parse(source) : parseYaml(source);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`[Codegen Error] Failed to parse dictionary ${absolutePath}: ${message}`);
+  }
+
+  assertDictionaryShape(parsed, `Dictionary file ${absolutePath}`);
+  return parsed;
+}
+
+function writeCompiledJson(absoluteJsonPath: string, dictionary: DictionaryJson): boolean {
+  const nextContent = `${JSON.stringify(dictionary, null, 2)}\n`;
+  if (fs.existsSync(absoluteJsonPath)) {
+    const currentContent = fs.readFileSync(absoluteJsonPath, "utf8");
+    if (currentContent === nextContent) {
+      return false;
+    }
+  }
+
+  fs.mkdirSync(path.dirname(absoluteJsonPath), { recursive: true });
+  fs.writeFileSync(absoluteJsonPath, nextContent);
+  return true;
+}
+
+export interface PrepareDictionariesResult {
+  resolvedEntries: NamespaceEntry[];
+  compiledFiles: string[];
+}
+
+export function prepareDictionaryEntries(
+  projectRoot: string,
+  entries: NamespaceEntry[],
+  generatedDirRelative: string
+): PrepareDictionariesResult {
+  const resolvedEntries: NamespaceEntry[] = [];
+  const compiledFiles: string[] = [];
+
+  for (const entry of entries) {
+    const sourceAbsolutePath = path.resolve(projectRoot, entry.filePath);
+    const format = getDictionaryFormat(entry.filePath);
+
+    if (!format) {
+      throw new Error(
+        `[Codegen Error] Namespace "${entry.namespace}" uses unsupported dictionary extension in "${entry.filePath}". Use .json, .yaml, or .yml.`
+      );
+    }
+
+    if (!fs.existsSync(sourceAbsolutePath)) {
+      throw new Error(
+        `[Codegen Error] Dictionary file not found for namespace "${entry.namespace}": ${sourceAbsolutePath}`
+      );
+    }
+
+    const dictionary = readDictionaryFile(sourceAbsolutePath);
+
+    if (format === "yaml") {
+      const compiledRelativePath = resolveCompiledJsonPath(entry.filePath, generatedDirRelative);
+      const compiledAbsolutePath = path.resolve(projectRoot, compiledRelativePath);
+      const wroteFile = writeCompiledJson(compiledAbsolutePath, dictionary);
+
+      if (wroteFile) {
+        compiledFiles.push(
+          `${path.relative(projectRoot, sourceAbsolutePath)} → ${compiledRelativePath}`
+        );
+      }
+      resolvedEntries.push({
+        namespace: entry.namespace,
+        filePath: compiledRelativePath,
+      });
+      continue;
+    }
+
+    resolvedEntries.push(entry);
+  }
+
+  return { resolvedEntries, compiledFiles };
+}

package/src/codegen/types.ts

@@ -1,3 +1,6 @@
+export const SUPPORTED_IMPORT_EXTENSIONS = ["none", ".ts", ".js"] as const;
+export type ImportExtension = (typeof SUPPORTED_IMPORT_EXTENSIONS)[number];
+
 export interface CodegenConfig {
   dictionary?: string;
   namespaces?: Record<string, string>;
@@ -8,6 +11,8 @@ export interface CodegenConfig {
   dictionarySchemaOutput?: string;
   loadOnInit?: string[];
   namespaceLoadersOutput?: string;
+  /** Extension used in relative imports between generated modules. Default: "none" */
+  importExtension?: ImportExtension;
   paramsTypeName: string;
   schemaTypeName: string;
   localeTypeName?: string;

package/src/setup/setup-i18n.ts

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { DEFAULT_IMPORT_EXTENSION, importExtensionSuffix } from "../codegen/paths.js";
 import { inferProjectName, typeNamesForProject } from "./type-names.js";
 
 export type SetupMode = "single" | "multi";
@@ -28,11 +29,13 @@ const DEFAULT_STARTER = {
   welcome: { en: "Welcome {name}!" },
 };
 
+const DEFAULT_IMPORT_SUFFIX = importExtensionSuffix(DEFAULT_IMPORT_EXTENSION);
+
 const INDEX_TS =
-  `import { createI18n } from "./generated/instance.generated.js";\n\n` +
-  `export * from "./generated/instance.generated.js";\n` +
-  `export * from "./generated/dictionary.generated.js";\n` +
-  `export * from "./generated/i18n-types.generated.js";\n\n` +
+  `import { createI18n } from "./generated/instance.generated${DEFAULT_IMPORT_SUFFIX}";\n\n` +
+  `export * from "./generated/instance.generated${DEFAULT_IMPORT_SUFFIX}";\n` +
+  `export * from "./generated/dictionary.generated${DEFAULT_IMPORT_SUFFIX}";\n` +
+  `export * from "./generated/i18n-types.generated${DEFAULT_IMPORT_SUFFIX}";\n\n` +
   `export const i18n = createI18n();\n`;
 
 function writeJson(filePath: string, value: unknown): void {