docs-i18n 0.6.3 → 0.7.0

package/README.md

@@ -1,161 +0,0 @@
-# docs-i18n
-
-Universal documentation translation engine. Parse markdown/MDX into translatable nodes, translate via LLM, cache in SQLite, manage with admin dashboard.
-
-## Features
-
-- **AST-based parsing** — splits markdown into translatable nodes with MD5 keys
-- **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
-- **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` in your project root:
-
-```ts
-import { defineConfig } from 'docs-i18n';
-
-export default defineConfig({
-  projects: {
-    mydocs: {
-      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
-
-# 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 (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"
-  }
-}
-```
-
-## 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