docs-i18n 0.4.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # docs-i18n
 
-Universal documentation translation engine. Parse markdown/MDX into translatable nodes, translate via LLM, cache in SQLite/D1, assemble translated files.
+Universal documentation translation engine. Parse markdown/MDX into translatable nodes, translate via LLM, cache in SQLite, manage with admin dashboard.
 
 ## Features
 
@@ -8,17 +8,20 @@ Universal documentation translation engine. Parse markdown/MDX into translatable
 - **Incremental translation** — only translates changed/new content
 - **Smart chunking** — respects LLM context window and output token limits
 - **YAML-aware frontmatter** — translates title/description fields individually
-- **SQLite cache** — concurrent-safe with WAL mode, portable to Cloudflare D1
+- **SQLite cache** — concurrent-safe with WAL mode
 - **Admin dashboard** — web UI for managing translation progress and jobs
+- **Runtime serve** — D1-compatible translator for SSR sites
 - **Framework-agnostic** — works with any docs site (Next.js, Astro, TanStack Start, etc.)
 
 ## Quick Start
 
 ```bash
 npm install docs-i18n
+# or
+bun add docs-i18n
 ```
 
-Create `docs-i18n.config.ts`:
+Create `docs-i18n.config.ts` in your project root:
 
 ```ts
 import { defineConfig } from 'docs-i18n';
@@ -26,34 +29,133 @@ import { defineConfig } from 'docs-i18n';
 export default defineConfig({
   projects: {
     mydocs: {
-      sources: { latest: 'content/latest' },
+      sources: {
+        latest: 'content/latest',
+        v1: 'content/v1',
+      },
     },
   },
   languages: ['zh-hans', 'ja', 'es'],
+  cacheDir: '.cache',
+  translatableFields: ['title', 'description', 'nav_title'],
+  llm: {
+    provider: 'openrouter', // or 'openai', 'anthropic'
+    model: 'qwen/qwen3.5-flash-02-23',
+    apiKey: process.env.OPENROUTER_API_KEY,
+    contextLength: 1_000_000,
+    maxTokens: 65536,
+  },
   context: 'MyProject is a TypeScript library for building web apps.',
 });
 ```
 
+## CLI
+
 ```bash
+# Check translation progress
+docs-i18n status
+
 # Translate
 docs-i18n translate --lang zh-hans
+docs-i18n translate --lang zh-hans --version latest --dry-run
+docs-i18n translate --lang zh-hans --files docs/intro.mdx,docs/guide.mdx
 
-# Check status
-docs-i18n status
+# Assemble translated files (EN source + cache → output)
+docs-i18n assemble
+docs-i18n assemble --lang zh-hans --version latest
+
+# Rescan source files and clean orphans
+docs-i18n rescan
 
-# Start admin dashboard
+# Start admin dashboard (http://localhost:3456)
 docs-i18n admin
+docs-i18n admin --port 4000
+```
+
+### npm scripts
+
+```json
+{
+  "scripts": {
+    "i18n": "docs-i18n",
+    "i18n:status": "docs-i18n status",
+    "i18n:admin": "docs-i18n admin",
+    "i18n:translate": "docs-i18n translate",
+    "i18n:assemble": "docs-i18n assemble",
+    "i18n:rescan": "docs-i18n rescan"
+  }
+}
 ```
 
-## Runtime Translation (for SSR sites)
+## Multi-Project Support
+
+For projects with multiple libraries (e.g., TanStack), use compound version keys:
+
+```ts
+export default defineConfig({
+  projects: {
+    query: {
+      sources: { latest: 'content/query/latest', v4: 'content/query/v4' },
+    },
+    table: {
+      sources: { latest: 'content/table/latest' },
+    },
+    blog: {
+      sources: { latest: 'content/blog' },
+    },
+  },
+  languages: ['zh-hans'],
+});
+```
+
+The admin dashboard automatically groups by project.
+
+## Runtime Translation (for SSR)
+
+For SSR sites that fetch markdown at runtime (e.g., TanStack Start), use the serve module with Cloudflare D1:
 
 ```ts
 import { createTranslator } from 'docs-i18n/serve';
 
 const translator = createTranslator();
+
+// In your request handler:
+const enMarkdown = await fetchFromGitHub(repo, branch, filePath);
 const translated = await translator.translate(enMarkdown, 'zh-hans', env.DB);
 ```
 
+## Config Reference
+
+```ts
+interface DocsI18nConfig {
+  projects: Record<string, {
+    sources: Record<string, string>; // version → source directory
+  }>;
+  languages: string[];               // target languages
+  cacheDir?: string;                  // default: '.cache'
+  translatableFields?: string[];     // default: ['title', 'description', 'nav_title']
+  include?: string[];                // default: ['**/*.mdx', '**/*.md']
+  context?: string;                  // injected into LLM prompt
+  llm?: {
+    provider?: 'openrouter' | 'openai' | 'anthropic';
+    model?: string;
+    apiKey?: string;
+    contextLength?: number;          // default: 32768
+    maxTokens?: number;              // default: 16384
+  };
+  onTranslated?: (info: {
+    project: string;
+    version: string;
+    lang: string;
+  }) => Promise<void>;
+}
+```
+
+## Requirements
+
+- Node.js 20+ or Bun
+- Admin dashboard requires `vite` and `@vitejs/plugin-react` as dev dependencies
+
 ## License
 
 MIT

package/dist/cli.js

@@ -4,7 +4,14 @@ import {
 } from "./chunk-SKKZIV3L.js";
 
 // src/cli.ts
+import { createRequire } from "module";
 var args = process.argv.slice(2);
+if (args[0] === "--version" || args[0] === "-v") {
+  const require2 = createRequire(import.meta.url);
+  const pkg = require2("../package.json");
+  console.log(pkg.version);
+  process.exit(0);
+}
 var command = args[0];
 function getOpt(name, def = "") {
   const idx = args.indexOf(`--${name}`);
@@ -88,7 +95,7 @@ Options:
     }
     case "admin": {
       const port = Number(getOpt("port", "3456"));
-      const { startAdmin } = await import("./server-2FW3TPYF.js");
+      const { startAdmin } = await import("./server-2WJM3QBQ.js");
       await startAdmin(config, port);
       break;
     }

package/dist/{server-2FW3TPYF.js → server-2WJM3QBQ.js}

@@ -189,7 +189,6 @@ var JobManager = class {
     };
     this.jobs.set(id, job);
     const args = [
-      CLI_BIN,
       "translate",
       "--lang",
       opts.lang,
@@ -203,7 +202,7 @@ var JobManager = class {
     if (opts.project) args.push("--project", opts.project);
     if (opts.model) args.push("--model", opts.model);
     if (opts.files?.length) args.push("--files", opts.files.join(","));
-    const proc = spawn("node", args, {
+    const proc = spawn(CLI_BIN, args, {
       cwd: PROJECT_ROOT,
       stdio: ["ignore", "pipe", "pipe"],
       env: { ...process.env, NO_TTY: "1", FORCE_COLOR: "0" }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docs-i18n",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Universal documentation translation engine — parse, translate, cache, assemble, manage.",
   "type": "module",
   "bin": {

package/src/admin/server/services/job-manager.ts

@@ -67,7 +67,6 @@ export class JobManager {
     this.jobs.set(id, job);
 
     const args = [
-      CLI_BIN,
       'translate',
       '--lang', opts.lang,
       '--version', opts.version,
@@ -79,7 +78,7 @@ export class JobManager {
     if (opts.model) args.push('--model', opts.model);
     if (opts.files?.length) args.push('--files', opts.files.join(','));
 
-    const proc = spawn('node', args, {
+    const proc = spawn(CLI_BIN, args, {
       cwd: PROJECT_ROOT,
       stdio: ['ignore', 'pipe', 'pipe'],
       env: { ...process.env, NO_TTY: '1', FORCE_COLOR: '0' },