docs-i18n 0.8.1 → 0.8.3

package/template/content/docs-i18n/en/getting-started.md

@@ -0,0 +1,189 @@
+---
+title: Getting Started
+description: Install docs-i18n and translate your first documentation file in minutes.
+---
+
+# Getting Started
+
+## What is docs-i18n?
+
+docs-i18n is a universal documentation translation engine. It parses markdown and MDX files into translatable AST nodes, translates them via LLM, caches results in SQLite, and assembles translated output files. It is framework-agnostic and works with any documentation site built on Next.js, Astro, TanStack Start, or similar tools.
+
+Key characteristics:
+
+- **Incremental** -- only changed or new content is sent to the LLM.
+- **AST-based** -- uses remark to parse markdown into nodes, producing stable MD5 keys for deduplication.
+- **SQLite-backed** -- concurrent-safe cache with WAL mode. No manual save steps.
+- **Multi-project** -- supports multiple documentation projects and versions in a single config.
+- **Admin dashboard** -- web UI for monitoring progress, managing jobs, and previewing translations.
+- **Runtime serve** -- optional D1-compatible translator for SSR sites on Cloudflare Workers.
+
+## How It Works
+
+```
+┌─────────────┐     ┌─────────────┐     ┌──────────────┐
+│ Your docs   │     │ docs-i18n   │     │ Translated   │
+│ (English)   │────→│ translate   │────→│ docs (cache) │
+│ .md / .mdx  │     │ via LLM     │     │ .cache/      │
+└─────────────┘     └─────────────┘     └──────┬───────┘
+                                               │
+                    ┌─────────────┐             │
+                    │ docs-i18n   │◄────────────┘
+                    │ site        │
+                    │ (dev/build) │──→ Multilingual docs site
+                    └─────────────┘
+```
+
+**Workflow:**
+1. Write docs in English (`.md` or `.mdx`)
+2. `docs-i18n translate` sends new/changed content to LLM, caches results in SQLite
+3. `docs-i18n site` serves a multilingual docs site (assembles translations at runtime)
+4. `docs-i18n admin` provides a web UI to monitor progress and manage jobs
+
+## Requirements
+
+- Node.js 20+ or Bun
+- An API key for an LLM provider (OpenRouter, OpenAI, or Anthropic)
+
+## Installation
+
+```bash
+npm install docs-i18n
+```
+
+Or with Bun:
+
+```bash
+bun add docs-i18n
+```
+
+## Quick Start
+
+### 1. Create a configuration file
+
+Create `docs-i18n.config.ts` in your project root:
+
+```ts
+import { defineConfig } from 'docs-i18n';
+
+export default defineConfig({
+  projects: {
+    mydocs: {
+      sources: {
+        latest: 'content/docs',
+      },
+    },
+  },
+  languages: ['zh-hans', 'ja', 'es'],
+  llm: {
+    provider: 'openrouter',
+    model: 'deepseek/deepseek-chat-v3-0324:free',
+    apiKey: process.env.OPENROUTER_API_KEY,
+  },
+});
+```
+
+The `projects` object maps project names to their source directories. Each project can have multiple versions (e.g., `latest`, `v1`, `v2`). The `languages` array lists the target language codes to translate into.
+
+### 2. Scan your source files
+
+Before translating, scan your English source files to build the source index:
+
+```bash
+npx docs-i18n rescan
+```
+
+This parses every markdown/MDX file in your source directories, extracts translatable nodes, and stores them in the SQLite cache.
+
+### 3. Check translation status
+
+```bash
+npx docs-i18n status
+```
+
+This displays a progress bar for each language showing how many nodes have been translated.
+
+### 4. Run your first translation
+
+```bash
+npx docs-i18n translate --lang zh-hans
+```
+
+This sends untranslated nodes to your configured LLM, receives translations, and stores them in the cache. Only new or changed content is translated -- cached translations are reused.
+
+### 5. Assemble output files
+
+```bash
+npx docs-i18n assemble
+```
+
+This produces translated markdown files by combining your English sources with cached translations. Output is written to `.cache/content/<version>/<lang>/` by default.
+
+## Minimal Working Example
+
+Given this project structure:
+
+```
+my-docs/
+  content/
+    docs/
+      getting-started.md
+      api-reference.md
+  docs-i18n.config.ts
+  package.json
+```
+
+With this config:
+
+```ts
+import { defineConfig } from 'docs-i18n';
+
+export default defineConfig({
+  projects: {
+    docs: {
+      sources: { latest: 'content/docs' },
+    },
+  },
+  languages: ['zh-hans'],
+  llm: {
+    provider: 'openrouter',
+    apiKey: process.env.OPENROUTER_API_KEY,
+    model: 'deepseek/deepseek-chat-v3-0324:free',
+    contextLength: 32768,
+    maxTokens: 16384,
+  },
+  context: 'MyProject is a TypeScript library for building web apps.',
+});
+```
+
+Run these commands:
+
+```bash
+npx docs-i18n rescan
+npx docs-i18n translate --lang zh-hans
+npx docs-i18n assemble --lang zh-hans
+```
+
+The translated files will appear at:
+
+```
+.cache/content/latest/zh-hans/getting-started.md
+.cache/content/latest/zh-hans/api-reference.md
+```
+
+## Adding npm scripts
+
+Add these convenience scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "i18n": "docs-i18n",
+    "i18n:status": "docs-i18n status",
+    "i18n:translate": "docs-i18n translate",
+    "i18n:assemble": "docs-i18n assemble",
+    "i18n:rescan": "docs-i18n rescan",
+    "i18n:admin": "docs-i18n admin"
+  }
+}
+```

package/template/content/docs.config.json

@@ -0,0 +1,25 @@
+{
+  "sections": [
+    {
+      "label": "Getting Started",
+      "children": [
+        { "label": "Introduction", "to": "getting-started" }
+      ]
+    },
+    {
+      "label": "Usage",
+      "children": [
+        { "label": "CLI Commands", "to": "cli" },
+        { "label": "Configuration", "to": "configuration" },
+        { "label": "Admin Dashboard", "to": "admin" }
+      ]
+    },
+    {
+      "label": "Advanced",
+      "children": [
+        { "label": "Architecture", "to": "architecture" },
+        { "label": "Deployment", "to": "deployment" }
+      ]
+    }
+  ]
+}

package/template/content/en/admin.md

@@ -0,0 +1,151 @@
+---
+title: Admin Dashboard
+description: Web UI for monitoring translation progress, managing translation jobs, previewing files, and browsing LLM models.
+---
+
+# Admin Dashboard
+
+The docs-i18n admin dashboard is a web-based UI for managing your translations. It is built with TanStack Start and React, and runs as a local development server.
+
+## Starting the Dashboard
+
+```bash
+npx docs-i18n admin
+```
+
+The dashboard opens at `http://localhost:3456`. Use `--port` to change the port:
+
+```bash
+npx docs-i18n admin --port 4000
+```
+
+**Prerequisites:**
+
+Your project must have `vite` and `@vitejs/plugin-react` installed:
+
+```bash
+npm install -D vite @vitejs/plugin-react
+```
+
+The dashboard reads your `docs-i18n.config.ts` to discover projects, versions, and languages.
+
+## Features
+
+### Translation Overview
+
+The main dashboard page shows a grid of all versions and languages with translation progress. For each version/language pair, you see:
+
+- Total number of source nodes (EN content units).
+- Number of translated nodes.
+- Percentage complete.
+- Breakdown by section (e.g., `docs/`, `blog/`, `learn/`), showing file counts and node counts per section.
+
+English is always shown as 100% complete since it is the source language.
+
+The overview auto-scans source files on load. If source files have not been scanned yet, the dashboard triggers a scan automatically.
+
+### File Browser
+
+Clicking on a version/language cell opens a file-level coverage list. Each file shows:
+
+- File path (relative to the source directory).
+- Total translatable nodes in that file.
+- Number of translated nodes.
+
+Files are sorted by path. You can click on any file to open the block-level preview.
+
+### File Preview
+
+The file preview shows every block (AST node) in a file side by side:
+
+- **Source** -- the original English text.
+- **Translation** -- the cached translation for the selected language, or empty if not yet translated.
+
+Each block displays its type (heading, paragraph, list, blockquote, frontmatter, code, html) and MD5 key. Non-translatable blocks (code, pure HTML tags, gaps between nodes) are shown but clearly distinguished.
+
+### Cache Management
+
+From the file preview, you can delete individual cache entries. This is useful when a translation is incorrect and you want to re-translate a specific node. After deleting, run the translate command again to get a fresh translation for that key.
+
+The dashboard also supports rescanning source files for a specific version via the UI. This rebuilds the source index and cleans orphaned entries.
+
+### Translation Jobs
+
+The dashboard includes a job management system for running translations directly from the UI instead of the command line.
+
+#### Creating a Job
+
+Click the job creation button and configure:
+
+- **Language** -- target language code.
+- **Version** -- which version to translate.
+- **Project** -- optionally filter to a specific project.
+- **Model** -- LLM model to use (can be selected from the model browser).
+- **Model rotation** -- optionally provide multiple models to rotate through.
+- **Max chunks** -- limit the number of API call chunks.
+- **Concurrency** -- number of parallel API calls (default: 3).
+- **Files** -- optionally select specific files to translate.
+
+#### Job Status
+
+Running jobs show:
+
+- Status: `running`, `completed`, `failed`, or `cancelled`.
+- Start time and finish time.
+- Number of translated chunks and total chunks.
+- Current chunk being processed.
+- Live log output (last 20 lines displayed, up to 500 lines stored).
+
+You can cancel a running job, which sends SIGTERM to the translation process. Completed or failed jobs can be removed from the list.
+
+#### How Jobs Work
+
+Under the hood, the job manager spawns a child process running the `docs-i18n translate` CLI command with the configured options. It captures stdout and stderr, parses progress information from the output, and exposes it through the dashboard API. The child process inherits the API key from your config or environment variables.
+
+### Model Browser
+
+The dashboard includes an OpenRouter model browser that fetches the list of available models from the OpenRouter API. For each model, it displays:
+
+- Model ID and name.
+- Pricing (prompt and completion per million tokens).
+- Context length and maximum output tokens.
+- Whether the model supports JSON response format and tool use.
+- Provider name.
+- Whether the model is free.
+
+The model list is cached for 5 minutes. It only shows text-to-text models (filtered by architecture modality) and excludes models with negative pricing. Models are sorted by prompt price (cheapest first).
+
+This is useful for selecting a model when creating a translation job.
+
+### Open in Editor
+
+The dashboard can open source files in your local editor. It tries the following editors in order:
+
+1. The value of the `EDITOR_CMD` environment variable (if set).
+2. `code` (VS Code)
+3. `cursor` (Cursor)
+4. `zed` (Zed)
+
+If none are found, it falls back to the system default (`open` on macOS, `xdg-open` on Linux, `start` on Windows).
+
+## Architecture
+
+The admin dashboard uses:
+
+- **TanStack Start** -- Full-stack React framework with server functions.
+- **TanStack React Query** -- For data fetching and cache management.
+- **TanStack Router** -- For client-side routing.
+- **Vite** -- Dev server and build tool.
+- **Hono** -- HTTP server (used by TanStack Start internally).
+
+Server functions are defined in `src/admin/server/functions/` and handle:
+
+- `fetchStatus` / `fetchFileCoverage` / `fetchFileBlocks` -- Read translation status from SQLite.
+- `deleteCacheEntry` -- Delete a specific translation from the cache.
+- `rescanVersion` -- Rescan source files for a version.
+- `createJob` / `fetchJobs` / `fetchJob` / `deleteJob` -- Manage translation jobs.
+- `fetchModels` -- Fetch available models from OpenRouter.
+- `fetchVersion` / `fetchConfig` -- Get docs-i18n version and project root.
+- `openFile` -- Open a file in the local editor.
+
+The dashboard shares the same `TranslationCache` and `parseMdx` functions as the CLI, ensuring consistent behavior.

package/template/content/en/architecture.md

@@ -0,0 +1,222 @@
+---
+title: Architecture
+description: How docs-i18n works internally -- the translation pipeline, AST parsing, caching, and chunking strategies.
+---
+
+# Architecture
+
+This document explains how docs-i18n works internally. Understanding the pipeline helps you tune configuration, debug issues, and contribute to the project.
+
+## Translation Pipeline
+
+The end-to-end flow is:
+
+```
+Source files (EN)
+    |
+    v
+[1. Normalize] -- Ensure JSX tags are separated by blank lines
+    |
+    v
+[2. Parse] -- remark AST -> flat list of typed nodes
+    |
+    v
+[3. Hash] -- MD5 of each translatable node's text
+    |
+    v
+[4. Chunk] -- Group nodes into chunks that fit the LLM context window
+    |
+    v
+[5. Translate] -- Send JSON to LLM, receive JSON translations
+    |
+    v
+[6. Cache] -- Store translations in SQLite keyed by (lang, md5)
+    |
+    v
+[7. Assemble] -- EN source + cache -> translated output files
+```
+
+## Step 1: Normalization
+
+The `normalize()` function (`src/core/normalize.ts`) preprocesses MDX content to ensure that JSX tags like `<AppOnly>`, `<PagesOnly>`, `<details>`, and `<div>` are separated from surrounding content by blank lines. This ensures remark parses them as independent HTML nodes rather than merging them with adjacent text.
+
+For example, this input:
+
+```
+<AppOnly>
+Some text here
+</AppOnly>
+```
+
+Becomes:
+
+```
+<AppOnly>
+
+Some text here
+
+</AppOnly>
+```
+
+## Step 2: AST Parsing
+
+The `parseMdx()` function (`src/core/parser.ts`) uses remark to parse markdown into a flat list of `ParsedNode` objects. Each node has:
+
+- `type` -- The AST node type: `paragraph`, `heading`, `list`, `blockquote`, `code`, `html`, `thematicBreak`, or `frontmatter`.
+- `rawText` -- The raw text content from the normalized source.
+- `needsTranslation` -- Whether this node contains human-readable text.
+- `md5` -- MD5 hash of the raw text (only for translatable nodes).
+- `startOffset` / `endOffset` -- Character offsets in the normalized content.
+
+**Translatable node types:** `paragraph`, `heading`, `list`, `blockquote`, and `html` nodes that contain non-tag text (e.g., `<summary>Examples</summary>`).
+
+**Non-translatable:** `code` blocks, `thematicBreak`, and pure HTML/JSX tags (self-closing tags like `<Check size={18} />`, opening/closing tags like `<AppOnly></AppOnly>`).
+
+**Frontmatter handling:** If the content starts with `---`, the parser detects YAML frontmatter and emits it as a single `frontmatter` node spanning from the opening `---` to the closing `---`. The frontmatter module (`src/core/frontmatter.ts`) then extracts only the configured translatable fields (e.g., `title`, `description`) using the `yaml` library, sends them to the LLM as plain text, and reconstructs the YAML with translated values while preserving all other fields and formatting.
+
+## Step 3: MD5 Hashing
+
+Each translatable node's raw text is hashed with MD5 to produce a stable key. This key is used for:
+
+- **Deduplication** -- identical content appearing in multiple files (or even multiple projects) shares a single translation.
+- **Incremental updates** -- when source content changes, only the nodes with new MD5 hashes need translation. Unchanged nodes reuse their cached translations.
+- **Heading differentiation** -- heading nodes include their level markers (`##`, `###`) in the hash, so "## Installation" and "### Installation" produce different keys.
+
+## Step 4: Smart Chunking
+
+The translate command groups untranslated nodes into chunks that fit within the LLM's context window. The chunking algorithm (`src/commands/translate.ts`) accounts for:
+
+- **Input budget** -- system prompt tokens + source text tokens. Estimated at `text.length / 4 + 80` tokens per node (accounting for JSON structure overhead).
+- **Output budget** -- translated text tokens. Scaled by a per-language multiplier since different languages use tokens differently:
+
+| Language | Multiplier | Reason |
+| --- | --- | --- |
+| Japanese, Korean, Hindi, Thai | 2.5x | CJK/Indic tokenization |
+| Russian, Arabic, Ukrainian, Hebrew | 2.0x | Cyrillic/Arabic scripts |
+| Chinese (Simplified/Traditional) | 1.5x | CJK but more concise |
+| German, French, Portuguese | 1.3x | Slightly longer than English |
+| Spanish, Vietnamese | 1.2x | Close to English length |
+| Other languages | 2.0x | Safe default |
+
+- **System prompt overhead** -- approximately 700 tokens for the translation prompt.
+- **JSON structure overhead** -- approximately 80 tokens per key for JSON schema properties.
+- **Safety margin** -- 85% of input budget and 75% of output budget are used to leave room for estimation errors.
+
+When a chunk reaches its budget, a new chunk is started. This prevents context window overflow and output truncation.
+
+## Step 5: LLM Translation
+
+The translator (`src/core/translator.ts`) uses structured JSON mode for translations:
+
+**Input format:** A JSON object with a `nodes` array. Each node has a `key` (MD5), `type` (heading/paragraph/list/etc.), and `text` (content to translate).
+
+```json
+{
+  "nodes": [
+    { "key": "a1b2c3...", "type": "heading", "text": "## Installation" },
+    { "key": "d4e5f6...", "type": "paragraph", "text": "Run the following command:" }
+  ]
+}
+```
+
+**Output format:** A flat JSON object mapping each key to its translation.
+
+```json
+{
+  "a1b2c3...": "## \u5b89\u88c5",
+  "d4e5f6...": "\u8fd0\u884c\u4ee5\u4e0b\u547d\u4ee4\uff1a"
+}
+```
+
+**Robustness features:**
+
+- **JSON repair** -- Handles common LLM JSON errors: unescaped newlines in strings, trailing commas, missing closing braces.
+- **Thinking block stripping** -- Removes `<think>...</think>` blocks from reasoning models.
+- **Unwrapping** -- If the model wraps output in `{"nodes": {...}}` or `{"translations": {...}}`, it is automatically unwrapped.
+- **Key recovery** -- If the model corrupts an MD5 key (e.g., truncates it), the translator attempts fuzzy matching to recover the translation (up to 3 character differences).
+- **Garbage detection** -- If more than 50% of translation values are identical, the model output is rejected.
+- **Retry with backoff** -- Retries on 429 (rate limit), 503, 405, timeout, and connection errors. Uses exponential backoff starting at 2 seconds.
+- **Model rotation** -- Supports a list of models to rotate through. Dead models (400/404 errors) are skipped. Rate-limited models (429) are deprioritized.
+- **Truncation detection** -- If `finish_reason` is `'length'`, the output was truncated and the request is retried.
+
+**Frontmatter translation:**
+
+Frontmatter nodes are handled specially. Instead of sending the entire YAML block, the translator extracts individual translatable fields (e.g., `title`, `description`) and sends them as plain `paragraph` type nodes with virtual keys like `fm:<md5>:title`. After translation, the fields are reassembled into the original YAML structure using `reconstructFrontmatter()`.
+
+## Step 6: SQLite Cache
+
+The `TranslationCache` class (`src/core/cache.ts`) manages all persistent state in a single SQLite database at `<cacheDir>/translations.db`.
+
+**Schema:**
+
+```sql
+-- EN source texts (deduplicated by MD5)
+CREATE TABLE sources (
+  key   TEXT PRIMARY KEY NOT NULL,  -- MD5 hash
+  text  TEXT NOT NULL,              -- original English text
+  type  TEXT NOT NULL DEFAULT 'paragraph'
+);
+
+-- Which files use each source node
+CREATE TABLE source_files (
+  key     TEXT    NOT NULL,  -- MD5 hash
+  file    TEXT    NOT NULL,  -- relative file path
+  line    INTEGER NOT NULL,  -- line number
+  version TEXT    NOT NULL DEFAULT 'latest',
+  PRIMARY KEY (version, key, file, line)
+);
+
+-- Translated texts per language
+CREATE TABLE translations (
+  lang       TEXT    NOT NULL,  -- language code
+  key        TEXT    NOT NULL,  -- MD5 hash
+  value      TEXT    NOT NULL,  -- translated text
+  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  PRIMARY KEY (lang, key)
+);
+```
+
+**Performance configuration:**
+
+- **WAL mode** -- Write-Ahead Logging enables concurrent readers with a single writer. No locking issues during parallel translation and assembly.
+- **busy_timeout = 5000** -- Wait up to 5 seconds for a lock before failing.
+- **synchronous = NORMAL** -- Balanced between safety and performance.
+- **WITHOUT ROWID** -- Tables use the primary key directly, avoiding an extra rowid column.
+- **Immediate writes** -- All `set()` calls write directly to disk. No explicit save step needed.
+
+**Key operations:**
+
+- `get(lang, md5)` -- Look up a cached translation.
+- `set(lang, md5, translation)` -- Store or update a translation (upsert).
+- `untranslatedKeys(lang, version)` -- Find all source keys that have no translation for a given language.
+- `fileCoverage(version, lang)` -- Get per-file translation coverage (used by the admin dashboard).
+- `prune(lang, usedMd5s)` -- Remove translations whose keys are no longer referenced.
+- `exportJsonl(lang, outputPath)` / `importJsonl(lang, inputPath)` -- Export/import translations in JSONL format for backup or migration.
+
+**SQLite compatibility:**
+
+The `openDatabase()` function (`src/core/sqlite.ts`) automatically detects the runtime environment. Under Bun, it uses `bun:sqlite`. Under Node.js, it uses `better-sqlite3`. Both expose the same interface.
+
+## Step 7: Assembly
+
+The `assemble()` function (`src/core/assembler.ts`) produces a translated file from English source content and cached translations:
+
+1. Normalizes the source content.
+2. Parses it into AST nodes.
+3. For each node:
+   - **Non-translatable nodes** (code blocks, HTML tags) are kept as-is.
+   - **Translatable nodes with a cached translation** are replaced with the cached value.
+   - **Translatable nodes without a cache hit** are either wrapped in `<!-- NEEDS_TRANSLATION -->` markers (for the legacy whole-file translation mode) or fall back to the original English text (for assembled output files).
+4. Preserves all whitespace and newlines between nodes.
+
+The `AssembleResult` includes statistics: `cachedCount`, `uncachedCount`, `totalTranslatable`, and whether all nodes were cached (`allCached`).
+
+## Validation
+
+The `validate()` function (`src/core/validator.ts`) compares LLM output against the translation cache to detect and correct modifications to already-cached translations. It uses two alignment strategies:
+
+- **Fast path** -- When the number of translatable nodes in the source and output match, nodes are aligned by index.
+- **Anchor-based alignment** -- When node counts differ (the LLM merged or split paragraphs), cached translations serve as anchor points. The validator finds exact matches between output text and cached translations, then aligns nodes between anchors by type matching.
+
+Cached translations always override LLM modifications, ensuring translation consistency across runs.