@llm-translate/cli 1.0.0-next.1

package/docs/zh/cli/init.md

@@ -0,0 +1,158 @@
+# llm-translate init
+
+::: info 翻译说明
+所有非英文文档均使用 Claude Sonnet 4 自动翻译。
+:::
+
+为您的项目初始化配置文件。
+
+## 概要
+
+```bash
+llm-translate init [options]
+```
+
+## 选项
+
+| 选项 | 默认值 | 描述 |
+|--------|---------|-------------|
+|`--provider `,`-p`| claude | 默认提供商 |
+|`--model `,`-m`| 不定 | 默认模型 |
+|`--quality`| 85 | 默认质量阈值 |
+|`--glossary`| none | 创建术语表模板 |
+|`--force `,`-f`| false | 覆盖现有配置 |
+
+## 示例
+
+### 基本初始化
+
+```bash
+llm-translate init
+```
+
+创建 `.translaterc.json`：
+
+```json
+{
+  "provider": {
+    "name": "claude",
+    "model": "claude-haiku-4-5-20251001"
+  },
+  "translation": {
+    "qualityThreshold": 85,
+    "maxIterations": 4
+  },
+  "paths": {}
+}
+```
+
+### 指定提供商
+
+```bash
+llm-translate init --provider openai --model gpt-4o
+```
+
+### 使用术语表模板
+
+```bash
+llm-translate init --glossary
+```
+
+同时创建 `glossary.json`：
+
+```json
+{
+  "sourceLanguage": "en",
+  "version": "1.0.0",
+  "terms": [
+    {
+      "source": "example",
+      "targets": {
+        "ko": "예시"
+      },
+      "context": "Replace with your terms"
+    }
+  ]
+}
+```
+
+### 自定义质量
+
+```bash
+llm-translate init --quality 95
+```
+
+## 交互模式
+
+不带选项时，init 以交互方式运行：
+
+```
+$ llm-translate init
+
+llm-translate Configuration Setup
+
+? Select provider: (Use arrow keys)
+❯ claude
+  openai
+  ollama
+
+? Select model: (Use arrow keys)
+❯ claude-haiku-4-5-20251001 (fast, cost-effective)
+  claude-sonnet-4-5-20250929 (balanced)
+  claude-opus-4-5-20251101 (highest quality)
+
+? Quality threshold: (85)
+? Create glossary template? (y/N)
+
+✓ Created .translaterc.json
+```
+
+## 输出文件
+
+### .translaterc.json
+
+```json
+{
+  "$schema": "https://llm-translate.dev/schema.json",
+  "provider": {
+    "name": "claude",
+    "model": "claude-haiku-4-5-20251001"
+  },
+  "translation": {
+    "qualityThreshold": 85,
+    "maxIterations": 4,
+    "preserveFormatting": true
+  },
+  "chunking": {
+    "maxTokens": 1024,
+    "overlapTokens": 150
+  },
+  "paths": {
+    "glossary": "./glossary.json",
+    "cache": "./.translate-cache"
+  }
+}
+```
+
+### glossary.json（使用 --glossary）
+
+```json
+{
+  "$schema": "https://llm-translate.dev/glossary-schema.json",
+  "sourceLanguage": "en",
+  "version": "1.0.0",
+  "description": "Project glossary",
+  "terms": []
+}
+```
+
+## 覆盖现有配置
+
+```bash
+# Will fail if config exists
+llm-translate init
+# Error: .translaterc.json already exists. Use --force to overwrite.
+
+# Force overwrite
+llm-translate init --force
+```

package/docs/zh/guide/chunking.md

@@ -0,0 +1,271 @@
+# Chunking策略
+
+::: info 翻译说明
+所有非英文文档均使用Claude Sonnet 4自动翻译。
+:::
+
+大型文档会被分割成分块进行翻译。了解Chunking有助于优化质量和成本。
+
+## 为什么需要Chunking？
+
+LLM有上下文限制，在专注内容上表现更好：
+
+| 原因 | 描述 |
+|--------|-------------|
+| **上下文限制** | 模型有最大输入大小限制 |
+| **质量** | 较小的分块能获得更专注的处理 |
+| **成本** | 允许缓存重复内容 |
+| **进度** | 支持进度跟踪和恢复 |
+
+## 默认配置
+
+```json
+{
+  "chunking": {
+    "maxTokens": 1024,
+    "overlapTokens": 150
+  }
+}
+```
+
+## 分块大小选项
+
+### maxTokens
+
+每个分块的最大令牌数（不包括提示开销）。
+
+| 大小 | 最适用于 | 权衡 |
+|------|----------|-----------|
+| 512 | 高质量要求 | 更多API调用 |
+| **1024** | 一般使用（默认） | 平衡 |
+| 2048 | 成本优化 | 可能降低质量 |
+
+### overlapTokens
+
+来自前一个分块的上下文确保跨边界的连续性。
+
+```
+Chunk 1: [Content A                    ]
+Chunk 2:            [overlap][Content B                    ]
+Chunk 3:                              [overlap][Content C  ]
+```
+
+::: tip 推荐重叠
+使用 `maxTokens` 值的10-15%。对于1024令牌，100-150重叠令牌效果良好。
+:::
+
+## Markdown感知Chunking
+
+llm-translate使用基于AST的Chunking，尊重文档结构。
+
+### 保留的边界
+
+Chunking器永远不会分割这些元素：
+
+| 元素 | 行为 |
+|---------|----------|
+| 标题 | 保留章节边界 |
+| 代码块 | 始终保持完整 |
+| 列表 | 尽可能将项目分组 |
+| 表格 | 永不跨分块分割 |
+| 段落 | 在自然边界处分割 |
+
+### 示例
+
+::: details 点击查看Chunking示例
+
+**输入文档：**
+
+```markdown
+# Introduction
+
+This is the introduction paragraph that explains
+the purpose of the document.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 20+
+- npm or yarn
+
+### Installation
+
+npm install @llm-translate/cli
+```
+
+**结果：**
+
+```
+Chunk 1: # Introduction + paragraph
+Chunk 2: ## Getting Started + ### Prerequisites + list
+Chunk 3: ### Installation + code block
+```
+
+:::
+
+## 配置
+
+::: code-group
+
+```bash [CLI]
+llm-translate file doc.md --target ko --chunk-size 2048
+```
+
+```json [.translaterc.json]
+{
+  "chunking": {
+    "maxTokens": 2048,
+    "overlapTokens": 200,
+    "preservePatterns": [
+      "```[\\s\\S]*?```",
+      "\\|[^\\n]+\\|"
+    ]
+  }
+}
+```
+
+```typescript [Programmatic]
+import { chunkContent } from '@llm-translate/cli';
+
+const chunks = chunkContent(content, {
+  maxTokens: 1024,
+  overlapTokens: 150,
+});
+```
+
+:::
+
+## 优化预设
+
+根据您的优先级选择：
+
+::: code-group
+
+```json [Quality Focus]
+{
+  "chunking": {
+    "maxTokens": 512,
+    "overlapTokens": 100
+  }
+}
+```
+
+```json [Cost Focus]
+{
+  "chunking": {
+    "maxTokens": 2048,
+    "overlapTokens": 50
+  }
+}
+```
+
+```json [Long Documents]
+{
+  "chunking": {
+    "maxTokens": 1500,
+    "overlapTokens": 150
+  },
+  "translation": {
+    "maxIterations": 3
+  }
+}
+```
+
+:::
+
+::: info 何时使用各预设
+- **质量优先**：技术文档、法律内容
+- **成本优先**：博客文章、一般内容
+- **长文档**：书籍、综合指南
+:::
+
+## 内容保护
+
+### 受保护的内容
+
+llm-translate自动保护某些内容不被翻译：
+
+| 内容类型 | 示例 | 行为 |
+|--------------|---------|----------|
+| 代码块 |` __INLINE_CODE_16__ `| 永不翻译 |
+| 内联代码 |`` ` variable ` ``| 保留 |
+| URL |`https://...`| 保留 |
+| 文件路径 |`./path/to/file`| 保留 |
+
+### 链接处理
+
+链接URL被保留，但链接文本会被翻译：
+
+```markdown
+[Getting Started](./getting-started.md)
+↓
+[시작하기](./getting-started.md)
+```
+
+## 调试
+
+### 预览分块
+
+使用 `--dry-run` 查看您的文档将如何被分块：
+
+```bash
+llm-translate file doc.md --target ko --dry-run --verbose
+```
+
+输出：
+```
+Document Analysis:
+  Total tokens: ~5,200
+  Chunks: 6
+  Average chunk size: ~867 tokens
+
+Chunk breakdown:
+  [1] Lines 1-45 (Introduction) - 823 tokens
+  [2] Lines 46-89 (Getting Started) - 912 tokens
+  [3] Lines 90-134 (Configuration) - 878 tokens
+  ...
+```
+
+### 程序化检查
+
+```typescript
+import { chunkContent, getChunkStats } from '@llm-translate/cli';
+
+const chunks = chunkContent(content, { maxTokens: 1024 });
+const stats = getChunkStats(chunks);
+
+console.log(`Total chunks: ${stats.count}`);
+console.log(`Average size: ${stats.avgTokens} tokens`);
+```
+
+## 故障排除
+
+::: warning 分块过小
+**症状**：许多小分块，过多API调用
+
+**解决方案**：增加 `maxTokens`
+```json
+{ "chunking": { "maxTokens": 2048 } }
+```
+:::
+
+::: warning 分块间上下文丢失
+**症状**：各章节间术语不一致
+
+**解决方案**：增加重叠或使用术语表
+```json
+{ "chunking": { "overlapTokens": 300 } }
+```
+:::
+
+::: danger 代码块被分割
+**症状**：输出中出现语法错误
+
+**原因**：这种情况永远不应该发生。如果发生，请[报告问题](https://github.com/selenehyun/llm-translate/issues)。
+:::
+
+::: warning 表格被破坏
+**症状**：表格格式损坏
+
+**解决方案**：表格应该自动保持完整。对于非常大的表格（100+行），考虑手动分割。

package/docs/zh/guide/configuration.md

@@ -0,0 +1,139 @@
+# 配置
+
+::: info 翻译
+所有非英文文档均使用 Claude Sonnet 4 自动翻译。
+:::
+
+llm-translate 使用分层配置系统。设置按以下顺序应用（后者覆盖前者）：
+
+1. 内置默认值
+2. 配置文件 (`.translaterc.json`)
+3. 环境变量
+4. CLI 参数
+
+## 配置文件
+
+在项目根目录创建 `.translaterc.json`：
+
+```json
+{
+  "provider": {
+    "name": "claude",
+    "model": "claude-haiku-4-5-20251001",
+    "apiKey": null
+  },
+  "translation": {
+    "qualityThreshold": 85,
+    "maxIterations": 4,
+    "preserveFormatting": true
+  },
+  "chunking": {
+    "maxTokens": 1024,
+    "overlapTokens": 150
+  },
+  "paths": {
+    "glossary": "./glossary.json",
+    "cache": "./.translate-cache"
+  }
+}
+```
+
+### 提供商设置
+
+| 选项 | 类型 | 默认值 | 描述 |
+|--------|------|---------|-------------|
+|`name `| string |`"claude"`| 提供商名称：` claude `、` openai `、` ollama`|
+|`model`| string | 不定 | 模型标识符 |
+|`apiKey`| string | null | API 密钥（建议使用环境变量） |
+|`baseUrl`| string | null | 自定义 API 端点 |
+
+### 翻译设置
+
+| 选项 | 类型 | 默认值 | 描述 |
+|--------|------|---------|-------------|
+|`qualityThreshold `| number |` 85`| 最低质量阈值（0-100） |
+|`maxIterations `| number |` 4`| 最大优化迭代次数 |
+|`preserveFormatting `| boolean |` true`| 保留 Markdown/HTML 结构 |
+
+### Chunking 设置
+
+| 选项 | 类型 | 默认值 | 描述 |
+|--------|------|---------|-------------|
+|`maxTokens `| number |` 1024`| 每个分块的最大令牌数 |
+|`overlapTokens `| number |` 150`| 分块间的上下文重叠 |
+
+### 路径设置
+
+| 选项 | 类型 | 默认值 | 描述 |
+|--------|------|---------|-------------|
+|`glossary`| string | null | 术语表文件路径 |
+|`cache`| string | null | 翻译缓存路径 |
+
+## 环境变量
+
+```bash
+# API Keys
+ANTHROPIC_API_KEY=sk-ant-xxxxx
+OPENAI_API_KEY=sk-xxxxx
+OLLAMA_BASE_URL=http://localhost:11434
+
+# Default Settings
+LLM_TRANSLATE_PROVIDER=claude
+LLM_TRANSLATE_MODEL=claude-haiku-4-5-20251001
+LLM_TRANSLATE_QUALITY_THRESHOLD=85
+```
+
+## CLI 覆盖示例
+
+```bash
+# Override provider
+llm-translate file doc.md -o doc.ko.md --target ko --provider openai
+
+# Override model
+llm-translate file doc.md -o doc.ko.md --target ko --model claude-sonnet-4-5-20250929
+
+# Override quality threshold
+llm-translate file doc.md -o doc.ko.md --target ko --quality 90
+
+# Override max iterations
+llm-translate file doc.md -o doc.ko.md --target ko --max-iterations 6
+```
+
+## 项目级配置
+
+对于 monorepo 或多项目设置，在每个项目目录中放置 `.translaterc.json`：
+
+```
+my-monorepo/
+├── packages/
+│   ├── frontend/
+│   │   ├── .translaterc.json  # Frontend-specific terms
+│   │   └── docs/
+│   └── backend/
+│       ├── .translaterc.json  # Backend-specific terms
+│       └── docs/
+└── .translaterc.json          # Shared defaults
+```
+
+llm-translate 从当前目录向上搜索配置文件。
+
+## 模型选择指南
+
+| 模型 | 速度 | 质量 | 成本 | 最适用于 |
+|-------|-------|---------|------|----------|
+|`claude-haiku-4-5-20251001`| 快 | 良好 | 低 | 通用文档，大批量 |
+|`claude-sonnet-4-5-20250929`| 中等 | 优秀 | 中等 | 技术文档，质量关键 |
+|`claude-opus-4-5-20251101`| 慢 | 最佳 | 高 | 复杂内容，细致文本 |
+|`gpt-4o-mini`| 快 | 良好 | 低 | Haiku 的替代方案 |
+|`gpt-4o`| 中等 | 优秀 | 中等 | Sonnet 的替代方案 |
+
+## 质量阈值指南
+
+| 阈值 | 使用场景 |
+|-----------|----------|
+| 70-75 | 草稿翻译，内部文档 |
+| 80-85 | 标准文档（默认） |
+| 90-95 | 面向公众，营销内容 |
+| 95+ | 法律，医疗，受监管内容 |
+
+更高的阈值需要更多迭代，成本也更高。

package/docs/zh/guide/cost-optimization.md

@@ -0,0 +1,30 @@
+# 成本优化
+
+::: info 翻译说明
+所有非英文文档均使用 Claude Sonnet 4 自动翻译。
+:::
+
+本指南介绍在保持翻译质量的同时最小化 API 成本的策略。
+
+## 成本结构
+
+### 令牌定价（截至 2025 年）
+
+| 模型 | 输入（1K） | 输出（1K） | 缓存读取 | 缓存写入 |
+|-------|-----------|-------------|------------|-------------|
+| Claude Haiku 4.5 | $0.001 | $0.005 | $0.0001 | $0.00125 |
+| Claude Sonnet 4.5 | $0.003 | $0.015 | $0.0003 | $0.00375 |
+| Claude Opus 4.5 | $0.015 | $0.075 | $0.0015 | $0.01875 |
+| GPT-4o-mini | $0.00015 | $0.0006 | 自动 | 自动 |
+| GPT-4o | $0.0025 | $0.01 | 自动 | 自动 |
+
+### 成本因素
+
+- [ ] 对标准文档使用 Haiku
+- [ ] 适当设置质量阈值（不要高于所需）
+- [ ] 启用并最大化提示缓存
+- [ ] 批量处理文件
+- [ ] 保持术语表精简
+- [ ] 对增量更新使用翻译缓存
+- [ ] 使用详细输出监控成本
+- [ ] 大型任务前先进行估算