@llm-translate/cli 1.0.0-next.1

package/docs/zh/guide/providers.md

@@ -0,0 +1,232 @@
+# 提供商
+
+::: info 翻译说明
+所有非英文文档均使用 Claude Sonnet 4 自动翻译。
+:::
+
+llm-translate 支持多个 LLM 提供商。每个提供商都有不同的优势和权衡。
+
+## 支持的提供商
+
+| 提供商 | 缓存 | 最适用于 | 设置复杂度 |
+|----------|---------|----------|------------------|
+| Claude | 完整 | 质量 + 成本 | 简单 |
+| OpenAI | 自动 | 生态系统 | 简单 |
+| Ollama | 无 | 隐私/离线 | 中等 |
+
+## Claude（推荐）
+
+### 为什么选择 Claude？
+
+- **提示缓存**：成本降低高达 90%
+- **高质量**：出色的翻译准确性
+- **长上下文**：200K 令牌上下文窗口
+- **多层级**：Haiku（快速）、Sonnet（平衡）、Opus（最佳）
+
+### 设置
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-xxxxx
+```
+
+### 模型选择
+
+```bash
+# Fast and cheap (default)
+llm-translate file doc.md --target ko --model claude-haiku-4-5-20251001
+
+# Balanced quality/cost
+llm-translate file doc.md --target ko --model claude-sonnet-4-5-20250929
+
+# Highest quality
+llm-translate file doc.md --target ko --model claude-opus-4-5-20251101
+```
+
+### 何时使用各个模型
+
+| 模型 | 使用场景 |
+|-------|----------|
+| Haiku | README 文件、简单文档、大批量 |
+| Sonnet | 技术文档、API 参考 |
+| Opus | 法律、营销、细致入微的内容 |
+
+## OpenAI
+
+### 设置
+
+```bash
+export OPENAI_API_KEY=sk-xxxxx
+```
+
+### 使用
+
+```bash
+llm-translate file doc.md --target ko --provider openai --model gpt-4o
+```
+
+### 可用模型
+
+| 模型 | 速度 | 质量 | 成本 |
+|-------|-------|---------|------|
+| gpt-4o-mini | 快 | 良好 | 很低 |
+| gpt-4o | 中等 | 优秀 | 中等 |
+| gpt-4-turbo | 中等 | 优秀 | 高 |
+
+### 何时使用
+
+- 已经在其他服务中使用 OpenAI
+- 需要特定的 OpenAI 功能
+- 偏好 Azure OpenAI（设置自定义 baseUrl）
+
+## Ollama
+
+用于隐私或离线使用的本地自托管 LLM。无需 API 密钥。
+
+::: warning 质量因模型而异
+Ollama 翻译质量**高度依赖于模型选择**。为获得可靠的翻译结果：
+
+- **最低要求**：14B+ 参数模型（例如 `qwen2.5:14b` 、 `llama3.1:14b`）
+- **推荐**：32B+ 模型（例如 `qwen2.5:32b` 、 `llama3.3:70b`）
+- **不推荐**：7B 以下的模型会产生不一致且通常无法使用的翻译
+
+较小的模型（3B、7B）可能适用于简单内容，但在技术文档上经常失败，产生不完整的输出，或忽略格式指令。
+:::
+
+### 快速设置
+
+```bash
+# 1. Install (macOS)
+brew install ollama
+
+# 2. Pull qwen2.5:14b (recommended)
+ollama pull qwen2.5:14b
+
+# 3. Translate
+llm-translate file doc.md -s en -t ko --provider ollama --model qwen2.5:14b
+```
+
+### 推荐模型
+
+| 模型 | 内存 | 质量 | 最适用于 |
+|-------|-----|---------|----------|
+|`qwen2.5:14b`| 16GB | 很好 | **最佳平衡（推荐）** |
+|`qwen2.5:32b`| 32GB | 优秀 | 更高质量 |
+|`llama3.1:8b`| 8GB | 良好 | 轻量级 |
+|`llama3.2`| 4GB | 一般 | 仅限简单内容 |
+
+### 何时使用
+
+- 敏感/私密文档
+- 离线环境
+- 成本优化（无 API 费用）
+- 简单到中等复杂度的内容
+
+::: tip 完整指南
+查看[使用 Ollama 进行本地翻译](./ollama)获取完整的设置说明、GPU 优化、故障排除和高级配置。
+:::
+
+## 提供商比较
+
+### 质量
+
+```
+Opus > Sonnet ≈ GPT-4o > Haiku ≈ GPT-4o-mini > Qwen2.5:32b > Qwen2.5:14b
+```
+
+### 成本（每 100 万令牌）
+
+```
+Ollama ($0) < GPT-4o-mini ($0.15) < Haiku ($1) < GPT-4o ($2.5) < Sonnet ($3) < Opus ($15)
+```
+
+### 速度
+
+```
+Haiku ≈ GPT-4o-mini > Sonnet ≈ GPT-4o > Opus > Ollama (varies with hardware)
+```
+
+## 切换提供商
+
+### CLI
+
+```bash
+# Different providers
+llm-translate file doc.md -s en -t ko --provider claude
+llm-translate file doc.md -s en -t ko --provider openai
+llm-translate file doc.md -s en -t ko --provider ollama
+```
+
+### 配置文件
+
+```json
+{
+  "provider": {
+    "name": "openai",
+    "model": "gpt-4o"
+  }
+}
+```
+
+### 编程方式
+
+```typescript
+import {
+  createClaudeProvider,
+  createOpenAIProvider,
+  createOllamaProvider,
+  TranslationEngine,
+} from '@llm-translate/cli';
+
+// Switch providers easily
+const providers = {
+  claude: createClaudeProvider(),
+  openai: createOpenAIProvider(),
+  ollama: createOllamaProvider(),
+};
+
+const engine = new TranslationEngine({
+  provider: providers[selectedProvider],
+});
+```
+
+## 回退配置
+
+配置回退提供商以提高可靠性：
+
+```json
+{
+  "provider": {
+    "name": "claude",
+    "model": "claude-haiku-4-5-20251001",
+    "fallback": [
+      { "name": "openai", "model": "gpt-4o-mini" },
+      { "name": "ollama", "model": "llama3.1" }
+    ]
+  }
+}
+```
+
+## 自定义端点
+
+### Azure OpenAI
+
+```json
+{
+  "provider": {
+    "name": "openai",
+    "baseUrl": "https://your-resource.openai.azure.com",
+    "apiKey": "your-azure-key"
+  }
+}
+```
+
+### 自托管
+
+```json
+{
+  "provider": {
+    "name": "ollama",
+    "baseUrl": "https://your-server.com:11434"
+  }
+}
+```

package/docs/zh/guide/quality-control.md

@@ -0,0 +1,137 @@
+# 质量控制
+
+::: info 翻译说明
+所有非英文文档均使用 Claude Sonnet 4 自动翻译。
+:::
+
+llm-translate 使用 Self-Refine 算法来确保翻译质量满足您的要求。
+
+## Self-Refine 工作原理
+
+```
+┌─────────────────┐
+│ Initial Translate│
+└────────┬────────┘
+         ▼
+┌─────────────────┐
+│ Evaluate Quality │◀──────────────┐
+└────────┬────────┘               │
+         ▼                        │
+    Score >= Threshold?           │
+         │                        │
+    No   │   Yes                  │
+         │    │                   │
+         ▼    ▼                   │
+┌─────────┐ ┌──────┐              │
+│ Reflect │ │ Done │              │
+└────┬────┘ └──────┘              │
+     ▼                            │
+┌─────────────────┐               │
+│    Improve      │───────────────┘
+└─────────────────┘
+```
+
+### 1. 初始翻译
+
+第一次翻译生成时包含：
+- 完整术语表上下文
+- 文档结构信息
+- 前一个 chunk 的上下文（保持连续性）
+
+### 2. 质量评估
+
+每个翻译都会根据四个标准进行评分：
+
+| 标准 | 权重 | 描述 |
+|-----------|--------|-------------|
+| 语义准确性 | 40% | 是否传达了正确的含义？ |
+| 流畅度 | 25% | 在目标语言中读起来是否自然？ |
+| 术语表合规性 | 20% | 是否正确应用了所有术语表条目？ |
+| 格式保持 | 15% | 是否保持了 Markdown/HTML 结构？ |
+
+### 3. 反思
+
+如果质量低于阈值，LLM 会分析：
+- 存在哪些具体问题
+- 遗漏了哪些术语表条目
+- 哪里可以改善流畅度
+
+### 4. 改进
+
+基于反思反馈应用针对性修复，然后重复循环。
+
+## 配置
+
+### 质量阈值
+
+```bash
+# CLI
+llm-translate file doc.md -o doc.ko.md -s en -t ko --quality 90
+
+# Config file
+{
+  "translation": {
+    "qualityThreshold": 90
+  }
+}
+```
+
+### 最大迭代次数
+
+```bash
+# CLI
+llm-translate file doc.md -o doc.ko.md -s en -t ko --max-iterations 6
+
+# Config file
+{
+  "translation": {
+    "maxIterations": 6
+  }
+}
+```
+
+### 严格模式
+
+如果未达到质量阈值则失败：
+
+```bash
+llm-translate file doc.md -o doc.ko.md -s en -t ko --strict-quality
+```
+
+退出代码：
+-`0`- 成功
+-`4`- 未达到质量阈值（严格模式）
+
+## 质量分数解释
+
+| 分数 | 质量等级 | 描述 |
+|-------|--------------|-------------|
+| 95-100 | 优秀 | 可直接发布 |
+| 85-94 | 良好 | 有轻微问题，大多数用途可接受 |
+| 75-84 | 一般 | 有明显问题，可能需要审查 |
+| 60-74 | 较差 | 有重大问题，需要人工审查 |
+| < 60 | 不可接受 | 有严重问题，考虑重新翻译 |
+
+## 理解输出
+
+```
+✓ Translation complete
+  Quality: 92/85 (threshold met)
+  Breakdown:
+    - Accuracy: 38/40
+    - Fluency: 24/25
+    - Glossary: 18/20
+    - Format: 12/15
+  Iterations: 2
+```
+
+### 详细分析
+
+- **准确性 (38/40)**：翻译在语义上正确
+- **流畅度 (24/25)**：在目标语言中读起来自然
+- **术语表 (18/20)**：大部分条目已应用，有些变化
+- **格式 (12/15)**：需要轻微的格式调整
+
+## 质量调优
+
+### 提高质量

package/docs/zh/guide/vitepress-integration.md

@@ -0,0 +1,265 @@
+# VitePress 集成
+
+::: info 翻译说明
+所有非英文文档均使用 Claude Sonnet 4 自动翻译。
+:::
+
+llm-translate 提供辅助函数，可根据您翻译的文档结构自动生成 VitePress i18n 配置。
+
+## 概述
+
+使用 `llm-translate dir` 翻译文档后，您可以使用内置的 VitePress 辅助工具为每个语言环境自动生成导航和侧边栏配置。
+
+## 安装
+
+```bash
+npm install @llm-translate/cli
+```
+
+## 基本用法
+
+```typescript
+// docs/.vitepress/config.ts
+import { defineConfig } from 'vitepress';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { generateLocaleConfig } from '@llm-translate/cli';
+
+// Get docs directory path relative to this config file
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const docsDir = resolve(__dirname, '..');
+
+const locales = generateLocaleConfig(docsDir, {
+  defaultLocale: 'en',
+  locales: ['ko', 'ja'],
+});
+
+export default defineConfig({
+  title: 'My Project',
+  locales,
+});
+```
+
+::: tip 为什么使用绝对路径？
+VitePress 配置从项目根目录运行，因此像 `'./docs'` 这样的相对路径可能无法正确解析。使用 `import.meta.url` 确保路径相对于配置文件位置计算。
+:::
+
+这将：
+1. 扫描您的 `./docs` 目录结构
+2. 自动检测侧边栏目录（guide、api、cli 等）
+3. 为每个语言环境生成导航和侧边栏
+4. 为 UI 元素应用默认翻译
+
+## 配置选项
+
+```typescript
+interface GenerateOptions {
+  /** Default locale code (e.g., 'en') - defaults to 'en' */
+  defaultLocale?: string;
+
+  /** List of locale codes to generate (auto-detected if omitted) */
+  locales?: string[];
+
+  /** Locale display labels */
+  labels?: Record<string, string>;
+
+  /** Locale lang codes for HTML */
+  langCodes?: Record<string, string>;
+
+  /** Locale descriptions */
+  descriptions?: Record<string, string>;
+
+  /** Directories to include in sidebar (auto-detected if omitted) */
+  sidebarDirs?: string[];
+
+  /** Use title from file's first heading (default: true) */
+  useTitleFromHeading?: boolean;
+
+  /** Custom locale translations */
+  translations?: Record<string, LocaleTranslations>;
+}
+```
+
+## 示例
+
+### 自动检测语言环境
+
+```typescript
+import { generateLocaleConfig, detectLocales } from '@llm-translate/cli';
+
+// Automatically detect locales from directory structure
+// (looks for 2-letter directories like 'ko', 'ja', 'zh')
+const locales = generateLocaleConfig('./docs');
+```
+
+### 自定义标签和描述
+
+```typescript
+const locales = generateLocaleConfig('./docs', {
+  defaultLocale: 'en',
+  locales: ['ko', 'ja'],
+  labels: {
+    en: 'English',
+    ko: '한국어',
+    ja: '日本語',
+  },
+  descriptions: {
+    en: 'Documentation for My Project',
+    ko: 'My Project 문서',
+    ja: 'My Projectのドキュメント',
+  },
+});
+```
+
+### 指定侧边栏目录
+
+```typescript
+const locales = generateLocaleConfig('./docs', {
+  sidebarDirs: ['guide', 'api', 'examples'],
+});
+```
+
+### 自定义翻译
+
+```typescript
+const locales = generateLocaleConfig('./docs', {
+  translations: {
+    ko: {
+      editLinkText: 'GitHub에서 편집',
+      docFooter: { prev: '이전', next: '다음' },
+      outline: { label: '목차' },
+    },
+  },
+});
+```
+
+## 仅生成侧边栏
+
+如果您想手动配置导航但自动生成侧边栏：
+
+```typescript
+import { defineConfig } from 'vitepress';
+import { generateSidebarConfig } from '@llm-translate/cli';
+
+const sidebars = generateSidebarConfig('./docs', {
+  defaultLocale: 'en',
+  locales: ['ko'],
+});
+
+export default defineConfig({
+  locales: {
+    root: {
+      label: 'English',
+      themeConfig: {
+        nav: [/* custom nav */],
+        sidebar: sidebars.root,
+      },
+    },
+    ko: {
+      label: '한국어',
+      themeConfig: {
+        nav: [/* custom nav */],
+        sidebar: sidebars.ko,
+      },
+    },
+  },
+});
+```
+
+## 单一语言环境生成
+
+为单一语言环境生成配置：
+
+```typescript
+import { generateLocale } from '@llm-translate/cli';
+
+const koConfig = generateLocale('./docs', 'ko', {
+  defaultLocale: 'en',
+});
+
+// Use in your config
+export default defineConfig({
+  locales: {
+    ko: koConfig,
+  },
+});
+```
+
+## 实用函数
+
+### detectLocales
+
+通过扫描语言环境目录自动检测可用的语言环境：
+
+```typescript
+import { detectLocales } from '@llm-translate/cli';
+
+const locales = detectLocales('./docs', 'en');
+// Returns: ['ko', 'ja', 'zh'] (based on directories found)
+```
+
+### detectSidebarDirs
+
+自动检测应出现在侧边栏中的目录：
+
+```typescript
+import { detectSidebarDirs } from '@llm-translate/cli';
+
+const dirs = detectSidebarDirs('./docs');
+// Returns: ['guide', 'api', 'cli'] (excludes locale dirs, assets, etc.)
+```
+
+## 标题提取
+
+辅助工具按以下顺序提取页面标题：
+1. 前置元数据 `title` 字段
+2. 文件中的第一个 `#` 标题
+3. 转换为标题格式的文件名
+
+前置元数据示例：
+```yaml
+---
+title: Getting Started
+---
+```
+
+## 默认翻译
+
+为常见语言环境提供内置翻译：
+
+| 语言环境 | 标签 | 文档页脚 | 大纲 |
+|--------|-------|------------|---------|
+| ko | 한국어 | 이전/다음 페이지 | 목차 |
+| ja | 日本語 | 前/次のページ | 目次 |
+| zh | 中文 | 上/下一页 | 目录 |
+
+## 工作流程
+
+多语言文档的典型工作流程：
+
+```bash
+# 1. Write documentation in English
+docs/
+  guide/
+    getting-started.md
+    configuration.md
+  api/
+    index.md
+
+# 2. Translate to Korean
+llm-translate dir ./docs ./docs/ko --target-lang ko --glossary glossary.json
+
+# 3. Update VitePress config to use auto-generation
+# (see examples above)
+
+# 4. Build and preview
+npm run docs:build
+npm run docs:preview
+```
+
+## 注意事项
+
+- **使用绝对路径**：始终使用 `import.meta.url` 解析文档目录路径，如基本用法中所示。相对路径可能无法正常工作，因为 VitePress 从项目根目录运行。
+- 语言环境目录必须使用 2 字母代码（例如 `ko` 、 `ja` 、 `zh`）
+- 辅助工具假设翻译文档镜像源结构
+- 自定义导航项（外部链接、下拉菜单）需要手动配置

package/docs/zh/index.md

@@ -0,0 +1,58 @@
+---
+layout: home
+
+hero:
+  name: llm-translate
+  text: LLM 驱动的文档翻译
+  tagline: 通过术语表强制执行、质量控制和成本优化来翻译文档
+  actions:
+    - theme: brand
+      text: 开始使用
+      link: ./guide/getting-started
+    - theme: alt
+      text: 在 GitHub 上查看
+      link: https://github.com/selenehyun/llm-translate
+
+features:
+  - icon: 📚
+    title: 术语表强制执行
+    details: 通过强制执行的术语表条目确保翻译中术语的一致性，永远不会出现误译。
+  - icon: 🔄
+    title: Self-Refine 质量控制
+    details: 使用 AI 驱动的质量评估进行迭代翻译优化，以达到您的质量阈值。
+  - icon: 💰
+    title: 成本优化
+    details: 提示缓存通过缓存术语表和系统提示等重复内容，将 API 成本降低高达 90%。
+  - icon: 🔌
+    title: 多提供商支持
+    details: 支持 Claude、OpenAI 和 Ollama。无需更改工作流程即可切换提供商。
+  - icon: 📄
+    title: 格式保持
+    details: 在翻译过程中保持 Markdown 格式、代码块、链接和文档结构。
+  - icon: ⚡
+    title: 批量处理
+    details: 通过并行处理和进度跟踪翻译整个目录。
+---
+
+## 快速开始
+
+```bash
+# Install globally
+npm install -g @llm-translate/cli
+
+# Set your API key
+export ANTHROPIC_API_KEY=your-key-here
+
+# Translate a file
+llm-translate file README.md -o README.ko.md --target ko
+```
+
+## 为什么选择 llm-translate？
+
+传统翻译工具在处理技术文档时存在困难：
+
+- **术语不一致** - "API endpoint" 每次翻译都不同
+- **格式损坏** - 代码块和 Markdown 被破坏
+- **无质量控制** - 接受 LLM 输出的任何结果
+
+llm-translate 通过以下方式解决这些问题：