docs-i18n 0.1.0

package/dist/index.js

@@ -0,0 +1,545 @@
+import {
+  FRONTMATTER_TRANSLATABLE_FIELDS,
+  normalize,
+  parseMdx
+} from "./chunk-7HWWVRNS.js";
+
+// src/config.ts
+function defineConfig(config) {
+  return config;
+}
+async function loadConfig(path2) {
+  const configPath = path2 ?? "docs-i18n.config.ts";
+  try {
+    const mod = await import(
+      /* @vite-ignore */
+      `${process.cwd()}/${configPath}`
+    );
+    return mod.default ?? mod;
+  } catch {
+    throw new Error(`Cannot load config from ${configPath}. Create a docs-i18n.config.ts file.`);
+  }
+}
+function flattenSources(config) {
+  const projects = Object.entries(config.projects);
+  const singleProject = projects.length === 1;
+  return projects.flatMap(
+    ([projectId, project]) => Object.entries(project.sources).map(([version, sourcePath]) => ({
+      project: projectId,
+      version,
+      sourcePath,
+      versionKey: singleProject ? version : `${projectId}/${version}`
+    }))
+  );
+}
+
+// src/core/assembler.ts
+var NEEDS_TRANSLATION_START = "<!-- NEEDS_TRANSLATION -->";
+var NEEDS_TRANSLATION_END = "<!-- /NEEDS_TRANSLATION -->";
+function assemble(rawContent, lang, cache, sourceFilePath, fallbackToSource = false) {
+  const normalizedContent = normalize(rawContent);
+  const nodes = parseMdx(rawContent);
+  let result = "";
+  let lastEnd = 0;
+  let cachedCount = 0;
+  let uncachedCount = 0;
+  let totalTranslatable = 0;
+  for (const node of nodes) {
+    result += normalizedContent.substring(lastEnd, node.startOffset);
+    if (node.needsTranslation) {
+      totalTranslatable++;
+      const cached = node.md5 ? cache.get(lang, node.md5) : void 0;
+      if (node.md5 && sourceFilePath) {
+        const line = normalizedContent.substring(0, node.startOffset).split("\n").length;
+        cache.updateSource(lang, node.md5, sourceFilePath, line);
+      }
+      if (cached) {
+        result += cached;
+        cachedCount++;
+      } else if (fallbackToSource) {
+        result += node.rawText;
+        uncachedCount++;
+      } else {
+        result += `${NEEDS_TRANSLATION_START}
+${node.rawText}
+${NEEDS_TRANSLATION_END}`;
+        uncachedCount++;
+      }
+    } else {
+      result += node.rawText;
+    }
+    lastEnd = node.endOffset;
+  }
+  result += normalizedContent.substring(lastEnd);
+  return {
+    content: result,
+    allCached: uncachedCount === 0,
+    cachedCount,
+    uncachedCount,
+    totalTranslatable,
+    parsedNodes: nodes
+  };
+}
+
+// src/core/cache.ts
+import fs from "fs";
+import path from "path";
+
+// src/core/sqlite.ts
+import { createRequire } from "module";
+var isBun = typeof globalThis.Bun !== "undefined";
+function openDatabase(filepath) {
+  if (isBun) {
+    const req2 = createRequire(import.meta.url);
+    const mod = req2("bun:sqlite");
+    const Database2 = mod.Database ?? mod.default ?? mod;
+    const raw = new Database2(filepath);
+    return {
+      prepare: (sql) => {
+        const stmt = raw.query(sql);
+        return {
+          run: (...params) => stmt.run(...params),
+          get: (...params) => stmt.get(...params),
+          all: (...params) => stmt.all(...params)
+        };
+      },
+      exec: (sql) => raw.run(sql),
+      pragma: (p) => raw.run(`PRAGMA ${p}`),
+      transaction: (fn) => raw.transaction(fn),
+      close: () => raw.close()
+    };
+  }
+  const req = createRequire(import.meta.url);
+  const Database = req("better-sqlite3");
+  return new Database(filepath);
+}
+
+// src/core/cache.ts
+var TranslationCache = class {
+  db;
+  cacheDir;
+  // Prepared statements (lazily initialized)
+  _stmts;
+  constructor(cacheDir) {
+    this.cacheDir = cacheDir;
+    fs.mkdirSync(cacheDir, { recursive: true });
+    const dbPath = path.join(cacheDir, "translations.db");
+    this.db = openDatabase(dbPath);
+    this.db.pragma("journal_mode = WAL");
+    this.db.pragma("busy_timeout = 5000");
+    this.db.pragma("synchronous = NORMAL");
+    this.db.pragma("foreign_keys = ON");
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS sources (
+        key   TEXT PRIMARY KEY NOT NULL,
+        text  TEXT NOT NULL,
+        type  TEXT NOT NULL DEFAULT 'paragraph'
+      ) WITHOUT ROWID;
+
+      CREATE TABLE IF NOT EXISTS source_files (
+        key     TEXT    NOT NULL,
+        file    TEXT    NOT NULL,
+        line    INTEGER NOT NULL,
+        version TEXT    NOT NULL DEFAULT 'latest',
+        PRIMARY KEY (version, key, file, line)
+      ) WITHOUT ROWID;
+
+      CREATE TABLE IF NOT EXISTS translations (
+        lang       TEXT    NOT NULL,
+        key        TEXT    NOT NULL,
+        value      TEXT    NOT NULL,
+        created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+        updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+        PRIMARY KEY (lang, key)
+      ) WITHOUT ROWID;
+
+      CREATE INDEX IF NOT EXISTS idx_translations_lang ON translations(lang);
+      CREATE INDEX IF NOT EXISTS idx_source_files_version ON source_files(version);
+      CREATE INDEX IF NOT EXISTS idx_source_files_file ON source_files(version, file);
+    `);
+  }
+  get stmts() {
+    if (!this._stmts) {
+      this._stmts = {
+        getTranslation: this.db.prepare(
+          "SELECT value FROM translations WHERE lang = ? AND key = ?"
+        ),
+        setTranslation: this.db.prepare(`
+          INSERT INTO translations (lang, key, value)
+          VALUES (?, ?, ?)
+          ON CONFLICT(lang, key) DO UPDATE SET value = excluded.value, updated_at = unixepoch()
+        `),
+        deleteTranslation: this.db.prepare(
+          "DELETE FROM translations WHERE lang = ? AND key = ?"
+        ),
+        countByLang: this.db.prepare(
+          "SELECT COUNT(*) as count FROM translations WHERE lang = ?"
+        ),
+        allByLang: this.db.prepare(
+          "SELECT key, value FROM translations WHERE lang = ?"
+        ),
+        keysByLang: this.db.prepare(
+          "SELECT key FROM translations WHERE lang = ?"
+        ),
+        setSource: this.db.prepare(`
+          INSERT INTO sources (key, text, type) VALUES (?, ?, ?)
+          ON CONFLICT(key) DO UPDATE SET text = excluded.text, type = excluded.type
+        `),
+        getSource: this.db.prepare(
+          "SELECT text, type FROM sources WHERE key = ?"
+        ),
+        clearSourceFiles: this.db.prepare(
+          "DELETE FROM source_files WHERE version = ?"
+        ),
+        upsertSourceFile: this.db.prepare(`
+          INSERT OR IGNORE INTO source_files (key, file, line, version) VALUES (?, ?, ?, ?)
+        `),
+        deleteSourceFilesByLang: this.db.prepare(
+          "DELETE FROM source_files WHERE version = ?"
+        )
+      };
+    }
+    return this._stmts;
+  }
+  // ── Public API (backward-compatible with JSONL version) ──
+  /**
+   * Load cache for a language. No-op for SQLite (data is always available).
+   * Kept for API compatibility.
+   */
+  load(_lang) {
+  }
+  /**
+   * Save cache for a language. No-op for SQLite (writes are immediate).
+   * Kept for API compatibility.
+   */
+  save(_lang) {
+  }
+  /** Get a cached translation */
+  get(lang, md5) {
+    const row = this.stmts.getTranslation.get(lang, md5);
+    return row?.value;
+  }
+  /** Set a cached translation (writes immediately to disk) */
+  set(lang, md5, translation) {
+    this.stmts.setTranslation.run(lang, md5, translation);
+  }
+  /**
+   * Set a cached translation with its EN source text.
+   * This also stores the source in the `sources` table for dashboard use.
+   */
+  setWithSource(lang, md5, translation, sourceText, sourceType = "paragraph") {
+    this.db.transaction(() => {
+      this.stmts.setSource.run(md5, sourceText, sourceType);
+      this.stmts.setTranslation.run(lang, md5, translation);
+    })();
+  }
+  /** Delete a cached translation */
+  delete(lang, md5) {
+    const result = this.stmts.deleteTranslation.run(lang, md5);
+    return result.changes > 0;
+  }
+  /** Iterate all entries for a language */
+  *entries(lang) {
+    const rows = this.stmts.allByLang.all(lang);
+    for (const row of rows) {
+      yield [row.key, { v: row.value, src: [] }];
+    }
+  }
+  /** Get all cached keys for a language as a Set (fast for coverage checks) */
+  keys(lang) {
+    const rows = this.stmts.keysByLang.all(lang);
+    return new Set(rows.map((r) => r.key));
+  }
+  /** Remove entries not in the provided set of md5s */
+  prune(lang, usedMd5s) {
+    const allKeys = this.keys(lang);
+    let removed = 0;
+    const deleteStmt = this.stmts.deleteTranslation;
+    this.db.transaction(() => {
+      for (const md5 of allKeys) {
+        if (!usedMd5s.has(md5)) {
+          deleteStmt.run(lang, md5);
+          removed++;
+        }
+      }
+    })();
+    return removed;
+  }
+  /** Get cache stats for a language */
+  stats(lang) {
+    const row = this.stmts.countByLang.get(lang);
+    return { size: row?.count ?? 0 };
+  }
+  // ── Source tracking ──
+  /**
+   * Update source locations for a md5 hash.
+   * In SQLite mode, this inserts into source_files table.
+   */
+  updateSource(_lang, md5, filePath, line, version = "latest") {
+    this.stmts.upsertSourceFile.run(md5, filePath, line, version);
+  }
+  /** Clear all source file mappings for a version (call before a full rebuild) */
+  clearSources(_lang, version = "latest") {
+    this.stmts.clearSourceFiles.run(version);
+  }
+  /** Store an EN source text in the sources table */
+  setSource(md5, text, type = "paragraph") {
+    this.stmts.setSource.run(md5, text, type);
+  }
+  /** Get an EN source text from the sources table */
+  getSource(md5) {
+    const row = this.stmts.getSource.get(md5);
+    return row ?? void 0;
+  }
+  /**
+   * Get all untranslated source keys for a language and version.
+   * Returns keys with their EN source text and type.
+   */
+  untranslatedKeys(lang, version = "latest", limit = 0, files) {
+    let fileFilter = "";
+    const params = [lang, version];
+    if (files && files.length > 0) {
+      fileFilter = ` AND sf.file IN (${files.map(() => "?").join(",")})`;
+      params.push(...files);
+    }
+    const sql = `
+      SELECT DISTINCT s.key, s.text, s.type
+      FROM source_files sf
+      JOIN sources s ON s.key = sf.key
+      LEFT JOIN translations t ON t.key = sf.key AND t.lang = ?
+      WHERE sf.version = ? AND t.key IS NULL${fileFilter}
+      ${limit > 0 ? `LIMIT ${limit}` : ""}
+    `;
+    return this.db.prepare(sql).all(...params);
+  }
+  // ── Dashboard queries ──
+  /** Get translation stats for all languages */
+  allLangStats() {
+    return this.db.prepare("SELECT lang, COUNT(*) as count FROM translations GROUP BY lang").all();
+  }
+  /**
+   * Get file-level coverage for a version and language.
+   * Returns how many source nodes each file has and how many are translated.
+   */
+  fileCoverage(version, lang) {
+    return this.db.prepare(
+      `
+      SELECT
+        sf.file,
+        COUNT(DISTINCT sf.key) as total,
+        COUNT(DISTINCT t.key) as translated
+      FROM source_files sf
+      LEFT JOIN translations t ON t.key = sf.key AND t.lang = ?
+      WHERE sf.version = ?
+      GROUP BY sf.file
+      ORDER BY sf.file
+    `
+    ).all(lang, version);
+  }
+  /**
+   * Get node-level detail for a specific file: EN source + translation side by side.
+   */
+  fileDetail(version, lang, file) {
+    return this.db.prepare(
+      `
+      SELECT
+        s.key,
+        s.text as source,
+        s.type,
+        t.value as translation,
+        sf.line
+      FROM source_files sf
+      JOIN sources s ON s.key = sf.key
+      LEFT JOIN translations t ON t.key = sf.key AND t.lang = ?
+      WHERE sf.version = ? AND sf.file = ?
+      ORDER BY sf.line
+    `
+    ).all(lang, version, file);
+  }
+  /** Get total source node count for a version */
+  sourceCount(version) {
+    const row = this.db.prepare(
+      "SELECT COUNT(DISTINCT key) as count FROM source_files WHERE version = ?"
+    ).get(version);
+    return row?.count ?? 0;
+  }
+  /**
+   * Get section-level stats for a version and language.
+   * Section is derived from file path prefix (docs/, blog/, learn/).
+   */
+  sectionStats(version, lang) {
+    return this.db.prepare(
+      `
+      WITH file_coverage AS (
+        SELECT
+          sf.file,
+          CASE
+            WHEN sf.file LIKE 'docs/%' THEN 'docs'
+            WHEN sf.file LIKE 'blog/%' THEN 'blog'
+            WHEN sf.file LIKE 'learn/%' THEN 'learn'
+            ELSE 'other'
+          END as section,
+          COUNT(DISTINCT sf.key) as total_nodes,
+          COUNT(DISTINCT t.key) as translated_nodes
+        FROM source_files sf
+        LEFT JOIN translations t ON t.key = sf.key AND t.lang = ?
+        WHERE sf.version = ?
+        GROUP BY sf.file
+      )
+      SELECT
+        section,
+        COUNT(*) as totalFiles,
+        SUM(CASE WHEN translated_nodes = total_nodes THEN 1 ELSE 0 END) as translatedFiles,
+        SUM(total_nodes) as totalNodes,
+        SUM(translated_nodes) as translatedNodes
+      FROM file_coverage
+      GROUP BY section
+      ORDER BY section
+    `
+    ).all(lang, version);
+  }
+  // ── Export / Import ──
+  /** Export cache to JSONL format (for backward compatibility / git tracking) */
+  exportJsonl(lang, outputPath) {
+    const rows = this.db.prepare(
+      "SELECT key, value FROM translations WHERE lang = ? ORDER BY key"
+    ).all(lang);
+    const lines = [];
+    for (const row of rows) {
+      const srcs = this.db.prepare(
+        "SELECT file || ':' || line as loc FROM source_files WHERE key = ? ORDER BY file, line"
+      ).all(row.key);
+      const entry = { k: row.key, v: row.value };
+      if (srcs.length > 0) {
+        entry.src = srcs.map((s) => s.loc);
+      }
+      lines.push(JSON.stringify(entry));
+    }
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, `${lines.join("\n")}
+`, "utf8");
+    return rows.length;
+  }
+  /** Import translations from a JSONL file */
+  importJsonl(lang, inputPath) {
+    if (!fs.existsSync(inputPath)) return 0;
+    const lines = fs.readFileSync(inputPath, "utf8").split("\n");
+    let count = 0;
+    this.db.transaction(() => {
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        const entry = JSON.parse(trimmed);
+        this.stmts.setTranslation.run(lang, entry.k, entry.v);
+        count++;
+      }
+    })();
+    return count;
+  }
+  /** Export a readable markdown index for IDE navigation */
+  exportIndex(lang) {
+    const indexPath = path.join(this.cacheDir, `${lang}.index.md`);
+    const rows = this.db.prepare(
+      `
+      SELECT t.key, t.value,
+             GROUP_CONCAT(sf.file || ':' || sf.line, char(10)) as sources
+      FROM translations t
+      LEFT JOIN source_files sf ON sf.key = t.key
+      WHERE t.lang = ?
+      GROUP BY t.key
+      HAVING sources IS NOT NULL
+      ORDER BY t.key
+    `
+    ).all(lang);
+    const lines = [`# Translation Index (${lang})`, ""];
+    for (const row of rows) {
+      if (!row.sources) continue;
+      const preview = row.value.split("\n")[0].substring(0, 80);
+      lines.push(`## \`${row.key}\` ${preview}`);
+      lines.push("");
+      for (const src of row.sources.split("\n")) {
+        const [filePath] = src.split(":");
+        lines.push(
+          `- [${src}](../content/en/${filePath}#L${src.split(":")[1]})`
+        );
+      }
+      lines.push("");
+    }
+    fs.writeFileSync(indexPath, lines.join("\n"), "utf8");
+  }
+  /** Close the database connection */
+  close() {
+    this._stmts = void 0;
+    this.db.close();
+  }
+};
+
+// src/core/frontmatter.ts
+import { parseDocument } from "yaml";
+function getNestedValue(doc, path2) {
+  const parts = path2.split(".");
+  let current = doc;
+  for (const part of parts) {
+    if (current == null) return void 0;
+    if (typeof current.get === "function") {
+      current = current.get(part);
+    } else if (typeof current === "object") {
+      current = current[part];
+    } else {
+      return void 0;
+    }
+  }
+  return current;
+}
+function setNestedValue(doc, path2, value) {
+  const parts = path2.split(".");
+  if (parts.length === 1) {
+    if (doc.has(parts[0])) doc.set(parts[0], value);
+    return;
+  }
+  let current = doc;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (typeof current.get === "function") {
+      current = current.get(parts[i]);
+    } else {
+      return;
+    }
+  }
+  const lastKey = parts[parts.length - 1];
+  if (typeof current.set === "function") {
+    current.set(lastKey, value);
+  }
+}
+function extractTranslatableFields(frontmatterText) {
+  const yaml = frontmatterText.replace(/^---\n/, "").replace(/\n---$/, "");
+  const doc = parseDocument(yaml);
+  const fields = {};
+  for (const field of FRONTMATTER_TRANSLATABLE_FIELDS) {
+    const value = getNestedValue(doc, field);
+    if (typeof value === "string" && value.trim()) {
+      fields[field] = value;
+    }
+  }
+  return fields;
+}
+function reconstructFrontmatter(frontmatterText, translatedFields) {
+  const yaml = frontmatterText.replace(/^---\n/, "").replace(/\n---$/, "");
+  const doc = parseDocument(yaml);
+  for (const [field, value] of Object.entries(translatedFields)) {
+    setNestedValue(doc, field, value);
+  }
+  return `---
+${doc.toString().trimEnd()}
+---`;
+}
+export {
+  TranslationCache,
+  assemble,
+  defineConfig,
+  extractTranslatableFields,
+  flattenSources,
+  loadConfig,
+  normalize,
+  parseMdx,
+  reconstructFrontmatter
+};