@llm-translate/cli 1.0.0-next.1

package/docs/zh/api/providers.md

@@ -0,0 +1,304 @@
+# 提供商
+
+::: info 翻译说明
+所有非英文文档均使用 Claude Sonnet 4 自动翻译。
+:::
+
+不同 AI 服务的 LLM 提供商实现。
+
+## 概述
+
+所有提供商都实现了 `LLMProvider` 接口：
+
+```typescript
+interface LLMProvider {
+  readonly name: ProviderName;
+  readonly defaultModel: string;
+
+  chat(request: ChatRequest): Promise<ChatResponse>;
+  stream(request: ChatRequest): AsyncIterable<string>;
+  countTokens(text: string): number;
+  getModelInfo(model?: string): ModelInfo;
+}
+```
+
+## Claude 提供商
+
+推荐的提供商，完全支持提示缓存。
+
+### 设置
+
+```typescript
+import { createClaudeProvider } from '@llm-translate/cli';
+
+const provider = createClaudeProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  defaultModel: 'claude-haiku-4-5-20251001',
+});
+```
+
+### 配置
+
+```typescript
+interface ClaudeProviderConfig {
+  apiKey?: string;          // Defaults to ANTHROPIC_API_KEY env
+  baseUrl?: string;         // Custom API endpoint
+  defaultModel?: string;    // Default: claude-haiku-4-5-20251001
+}
+```
+
+### 可用模型
+
+| 模型 | 上下文 | 输入成本 | 输出成本 |
+|-------|---------|------------|-------------|
+|`claude-haiku-4-5-20251001`| 200K | $0.001/1K | $0.005/1K |
+|`claude-sonnet-4-5-20250929`| 200K | $0.003/1K | $0.015/1K |
+|`claude-opus-4-5-20251101`| 200K | $0.015/1K | $0.075/1K |
+
+### 提示缓存
+
+Claude 提供商自动支持提示缓存：
+
+```typescript
+const response = await provider.chat({
+  messages: [
+    {
+      role: 'user',
+      content: [
+        {
+          type: 'text',
+          text: 'System instructions...',
+          cacheControl: { type: 'ephemeral' },  // Cache this
+        },
+        {
+          type: 'text',
+          text: 'User content...',  // Don't cache
+        },
+      ],
+    },
+  ],
+});
+
+console.log(response.usage);
+// {
+//   inputTokens: 100,
+//   outputTokens: 200,
+//   cacheReadTokens: 500,    // Tokens read from cache
+//   cacheWriteTokens: 0,     // Tokens written to cache
+// }
+```
+
+## OpenAI 提供商
+
+### 设置
+
+```typescript
+import { createOpenAIProvider } from '@llm-translate/cli';
+
+const provider = createOpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY,
+  defaultModel: 'gpt-4o-mini',
+});
+```
+
+### 配置
+
+```typescript
+interface OpenAIProviderConfig {
+  apiKey?: string;          // Defaults to OPENAI_API_KEY env
+  baseUrl?: string;         // Custom API endpoint
+  defaultModel?: string;    // Default: gpt-4o-mini
+  organization?: string;    // OpenAI organization ID
+}
+```
+
+### 可用模型
+
+| 模型 | 上下文 | 输入成本 | 输出成本 |
+|-------|---------|------------|-------------|
+|`gpt-4o-mini`| 128K | $0.00015/1K | $0.0006/1K |
+|`gpt-4o`| 128K | $0.0025/1K | $0.01/1K |
+|`gpt-4-turbo`| 128K | $0.01/1K | $0.03/1K |
+
+### 自动缓存
+
+OpenAI 对超过 1024 个令牌的提示自动处理缓存。
+
+## Ollama 提供商
+
+用于本地自托管模型。
+
+### 设置
+
+```typescript
+import { createOllamaProvider } from '@llm-translate/cli';
+
+const provider = createOllamaProvider({
+  baseUrl: 'http://localhost:11434',
+  defaultModel: 'llama3.1',
+});
+```
+
+### 配置
+
+```typescript
+interface OllamaProviderConfig {
+  baseUrl?: string;         // Default: http://localhost:11434
+  defaultModel?: string;    // Default: llama3.1
+}
+```
+
+### 可用模型
+
+Ollama 安装中可用的任何模型：
+
+```bash
+# List available models
+ollama list
+
+# Pull a model
+ollama pull llama3.1
+ollama pull mistral
+ollama pull codellama
+```
+
+### 限制
+
+- 不支持提示缓存
+- 质量因模型而异
+- 上下文窗口有限（取决于模型）
+
+## 提供商接口
+
+### ChatRequest
+
+```typescript
+interface ChatRequest {
+  messages: ChatMessage[];
+  model?: string;
+  temperature?: number;    // Default: 0.3
+  maxTokens?: number;      // Default: 4096
+}
+
+interface ChatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string | CacheableTextPart[];
+}
+
+interface CacheableTextPart {
+  type: 'text';
+  text: string;
+  cacheControl?: { type: 'ephemeral' };
+}
+```
+
+### ChatResponse
+
+```typescript
+interface ChatResponse {
+  content: string;
+  usage: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+  };
+  model: string;
+  finishReason: 'stop' | 'length' | 'error';
+}
+```
+
+### ModelInfo
+
+```typescript
+interface ModelInfo {
+  maxContextTokens: number;
+  supportsStreaming: boolean;
+  costPer1kInput?: number;
+  costPer1kOutput?: number;
+}
+```
+
+## 自定义提供商
+
+实现您自己的提供商：
+
+```typescript
+import type { LLMProvider, ChatRequest, ChatResponse } from '@llm-translate/cli';
+
+class CustomProvider implements LLMProvider {
+  readonly name = 'custom' as const;
+  readonly defaultModel = 'custom-model';
+
+  async chat(request: ChatRequest): Promise<ChatResponse> {
+    // Your implementation
+    const response = await callYourAPI(request);
+
+    return {
+      content: response.text,
+      usage: {
+        inputTokens: response.promptTokens,
+        outputTokens: response.completionTokens,
+      },
+      model: request.model ?? this.defaultModel,
+      finishReason: 'stop',
+    };
+  }
+
+  async *stream(request: ChatRequest): AsyncIterable<string> {
+    // Streaming implementation
+    for await (const chunk of streamYourAPI(request)) {
+      yield chunk.text;
+    }
+  }
+
+  countTokens(text: string): number {
+    // Token estimation
+    return Math.ceil(text.length / 4);
+  }
+
+  getModelInfo(model?: string): ModelInfo {
+    return {
+      maxContextTokens: 100000,
+      supportsStreaming: true,
+    };
+  }
+}
+```
+
+## 提供商选择指南
+
+| 使用场景 | 推荐提供商 | 模型 |
+|----------|---------------------|-------|
+| 成本效益 | Claude | Haiku 4.5 |
+| 高质量 | Claude | Sonnet 4.5 |
+| OpenAI 生态系统 | OpenAI | GPT-4o |
+| 预算受限 | OpenAI | GPT-4o-mini |
+| 隐私/离线 | Ollama | Llama 3.1 |
+| 企业级 | Claude/OpenAI | 视情况而定 |
+
+## 错误处理
+
+所有提供商都会抛出 `TranslationError`：
+
+```typescript
+import { TranslationError, ErrorCode } from '@llm-translate/cli';
+
+try {
+  await provider.chat(request);
+} catch (error) {
+  if (error instanceof TranslationError) {
+    switch (error.code) {
+      case ErrorCode.PROVIDER_AUTH_FAILED:
+        console.error('Invalid API key');
+        break;
+      case ErrorCode.PROVIDER_RATE_LIMITED:
+        console.error('Rate limited, retry later');
+        break;
+      case ErrorCode.PROVIDER_ERROR:
+        console.error('Provider error:', error.message);
+        break;
+    }
+  }
+}
+```

package/docs/zh/changelog.md

@@ -0,0 +1,64 @@
+# 更新日志
+
+::: info 翻译说明
+所有非英文文档均使用 Claude Sonnet 4 自动翻译。
+:::
+
+llm-translate 的所有重要更改都将记录在此文件中。
+
+格式基于 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)，
+此项目遵循 [语义化版本控制](https://semver.org/spec/v2.0.0.html)。
+
+## [未发布]
+
+### 新增
+
+- Claude 模型的提示缓存支持（成本降低 40-50%）
+- 翻译结果中的缓存令牌使用情况跟踪
+- TranslationAgent 中的 `enableCaching` 选项
+- 令牌使用元数据中的 `cacheRead` 和 `cacheWrite` 字段
+- 基于 MQM（多维质量指标）的质量评估系统
+- MAPS 风格的预翻译分析步骤
+- 翻译模式支持（`--mode fast|balanced|quality`）
+
+### 更改
+
+-`ChatMessage.content` 现在支持可缓存的文本部分
+-`ChatResponse.usage` 包含缓存令牌指标
+- 默认模型更新为 `claude-haiku-4-5-20251001`
+
+### 文档
+
+- 添加 Ollama 质量警告：需要 14B+ 模型才能进行可靠翻译
+
+## [0.1.0] - 2025-12-12
+
+### 新增
+
+- 初始版本发布
+- 单文件翻译（`llm-translate file`）
+- 目录批量翻译（`llm-translate dir`）
+- 配置初始化（`llm-translate init`）
+- 术语表管理（`llm-translate glossary`）
+- Claude、OpenAI 和 Ollama 提供商支持
+- Self-Refine 质量控制循环
+- 基于 Markdown AST 的 Chunking
+- 术语表强制执行
+- 质量阈值配置
+- 详细输出模式
+
+### 提供商
+
+- Claude（claude-haiku-4-5、claude-sonnet-4-5、claude-opus-4-5）
+- OpenAI（gpt-4o-mini、gpt-4o、gpt-4-turbo）
+- Ollama（任何本地模型）
+
+### 文档
+
+- CLI 参考文档
+- API 参考文档
+- 入门指南
+- 配置指南
+- 术语表指南
+- 质量控制指南
+- 成本优化指南

package/docs/zh/cli/dir.md

@@ -0,0 +1,243 @@
+# llm-translate dir
+
+::: info 翻译说明
+所有非英文文档均使用 Claude Sonnet 4 自动翻译。
+:::
+
+翻译目录中的所有文件。
+
+## 语法
+
+```bash
+llm-translate dir <input> <output> [options]
+```
+
+## 参数
+
+| 参数 | 描述 |
+|----------|-------------|
+|`<input>`| 输入目录路径（必需） |
+|`<output>`| 输出目录路径（必需） |
+
+## 选项
+
+### 语言选项
+
+| 选项 | 默认值 | 描述 |
+|--------|---------|-------------|
+|`-s, --source-lang <lang>`| 配置默认值 | 源语言代码 |
+|`-t, --target-lang <lang>`| 必需 | 目标语言代码 |
+
+### 翻译选项
+
+| 选项 | 默认值 | 描述 |
+|--------|---------|-------------|
+|`-g, --glossary <path>`| 无 | 术语表文件路径 |
+|`-p, --provider <name>`|` claude`| LLM 提供商 (claude\|openai\|ollama) |
+|`-m, --model <name>`| 提供商默认值 | 模型名称 |
+|`--context <text>`| 无 | 翻译的额外上下文 |
+
+### 质量选项
+
+| 选项 | 默认值 | 描述 |
+|--------|---------|-------------|
+|`--quality <0-100>`| 85 | 质量阈值 |
+|`--max-iterations <n>`| 4 | 最大优化迭代次数 |
+
+### 文件选择
+
+| 选项 | 默认值 | 描述 |
+|--------|---------|-------------|
+|`--include <patterns>`|`*.md,*.markdown`| 要包含的文件模式（逗号分隔） |
+|`--exclude <patterns>`| 无 | 要排除的文件模式（逗号分隔） |
+
+### 处理选项
+
+| 选项 | 默认值 | 描述 |
+|--------|---------|-------------|
+|`--parallel <n>`| 3 | 并行文件处理数 |
+|`--chunk-size <tokens>`| 1024 | 每个分块的最大令牌数 |
+|`--no-cache`| false | 禁用翻译缓存 |
+
+### 输出选项
+
+| 选项 | 默认值 | 描述 |
+|--------|---------|-------------|
+|`-f, --format <fmt>`| auto | 强制输出格式 (md\|html\|txt) |
+|`--dry-run`| false | 显示将要翻译的内容 |
+|`--json`| false | 以 JSON 格式输出结果 |
+|`-v, --verbose`| false | 启用详细日志 |
+|`-q, --quiet`| false | 抑制非错误输出 |
+
+## 示例
+
+### 基本用法
+
+```bash
+# Translate all markdown files
+llm-translate dir ./docs ./docs-ko -s en -t ko
+
+# With glossary
+llm-translate dir ./docs ./docs-ko -s en -t ko -g glossary.json
+```
+
+### 文件选择
+
+```bash
+# Custom include pattern
+llm-translate dir ./docs ./docs-ko -s en -t ko --include "**/*.md"
+
+# Multiple patterns
+llm-translate dir ./docs ./docs-ko -s en -t ko --include "*.md,*.markdown,*.mdx"
+
+# Exclude certain directories
+llm-translate dir ./docs ./docs-ko -s en -t ko \
+  --exclude "node_modules/**,dist/**,drafts/**"
+```
+
+### 并行处理
+
+```bash
+# Process 5 files in parallel
+llm-translate dir ./docs ./docs-ko -s en -t ko --parallel 5
+
+# Sequential processing (for rate-limited APIs)
+llm-translate dir ./docs ./docs-ko -s en -t ko --parallel 1
+```
+
+### 质量设置
+
+```bash
+# High quality for important docs
+llm-translate dir ./docs ./docs-ko -s en -t ko --quality 95 --max-iterations 6
+
+# Faster processing with lower threshold
+llm-translate dir ./docs ./docs-ko -s en -t ko --quality 70 --max-iterations 2
+```
+
+### 预览模式
+
+```bash
+# Show what would be translated
+llm-translate dir ./docs ./docs-ko -s en -t ko --dry-run
+```
+
+输出：
+```
+Dry run mode - no translation will be performed
+
+Files to translate:
+  getting-started.md → docs-ko/getting-started.md
+  guide/setup.md → docs-ko/guide/setup.md
+  api/reference.md → docs-ko/api/reference.md
+
+Total: 3 file(s)
+```
+
+## 输出结构
+
+默认情况下保留目录结构：
+
+```
+Input:                     Output:
+docs/                      docs-ko/
+├── getting-started.md     ├── getting-started.md
+├── guide/                 ├── guide/
+│   ├── setup.md           │   ├── setup.md
+│   └── advanced.md        │   └── advanced.md
+└── api/                   └── api/
+    └── reference.md           └── reference.md
+```
+
+## 进度报告
+
+### 普通模式
+
+```
+ℹ Found 5 file(s) to translate
+ℹ Input: ./docs
+ℹ Output: ./docs-ko
+ℹ Target language: ko
+ℹ Parallel processing: 3 file(s) at a time
+[1/5] getting-started.md ✓
+[2/5] guide/setup.md ✓
+[3/5] guide/advanced.md ✓
+[4/5] api/reference.md ✓
+[5/5] api/types.md ✓
+
+────────────────────────────────────────────────────────
+  Translation Summary
+────────────────────────────────────────────────────────
+  Files:      5 succeeded, 0 failed
+  Duration:   45.2s
+  Tokens:     12,450 input / 8,320 output
+  Cache:      5,200 read / 2,100 write
+────────────────────────────────────────────────────────
+```
+
+### JSON 输出
+
+```bash
+llm-translate dir ./docs ./docs-ko -t ko --json
+```
+
+```json
+{
+  "success": true,
+  "totalFiles": 5,
+  "successCount": 5,
+  "failCount": 0,
+  "totalDuration": 45234,
+  "tokensUsed": {
+    "input": 12450,
+    "output": 8320,
+    "cacheRead": 5200,
+    "cacheWrite": 2100
+  },
+  "files": [...]
+}
+```
+
+## 最佳实践
+
+### 1. 先预览
+
+```bash
+llm-translate dir ./docs ./docs-ko -s en -t ko --dry-run
+```
+
+### 2. 使用适当的并行度
+
+- 有速率限制的 API：`--parallel 1-2`
+- 高限制：`--parallel 5-10`
+- 本地 (Ollama)：`--parallel 1`（受模型限制）
+
+### 3. 处理大型项目
+
+```bash
+# Split by subdirectory for better control
+llm-translate dir ./docs/guide ./docs-ko/guide -s en -t ko
+llm-translate dir ./docs/api ./docs-ko/api -s en -t ko
+```
+
+### 4. 利用缓存
+
+缓存允许跳过未更改的内容：
+
+```bash
+# First run: translates all
+llm-translate dir ./docs ./docs-ko -s en -t ko
+
+# Second run: uses cache for unchanged content
+llm-translate dir ./docs ./docs-ko -s en -t ko
+```
+
+### 5. 根据内容类型调整质量
+
+```bash
+# High quality for user-facing docs
+llm-translate dir ./docs/public ./docs-ko/public -s en -t ko --quality 95
+
+# Standard quality for internal docs
+llm-translate dir ./docs/internal ./docs-ko/internal -s en -t ko --quality 80
+```