@llm-translate/cli 1.0.0-next.1

package/docs/zh/api/agent.md

@@ -0,0 +1,262 @@
+# TranslationAgent
+
+::: info 翻译说明
+所有非英文文档均使用 Claude Sonnet 4 自动翻译。
+:::
+
+实现 Self-Refine 算法的底层翻译代理。
+
+## 构造函数
+
+```typescript
+import { TranslationAgent } from '@llm-translate/cli';
+
+const agent = new TranslationAgent(options: TranslationAgentOptions);
+```
+
+### 选项
+
+```typescript
+interface TranslationAgentOptions {
+  provider: LLMProvider;
+  qualityThreshold?: number;  // Default: 85
+  maxIterations?: number;     // Default: 4
+  verbose?: boolean;          // Default: false
+  strictQuality?: boolean;    // Default: false
+  enableCaching?: boolean;    // Default: true for Claude
+}
+```
+
+## 方法
+
+### translate
+
+使用 Self-Refine 循环翻译内容。
+
+```typescript
+const result = await agent.translate(request: TranslationRequest);
+```
+
+#### 请求
+
+```typescript
+interface TranslationRequest {
+  content: string;           // Source text to translate
+  sourceLang: string;        // Source language code
+  targetLang: string;        // Target language code
+  glossary?: ResolvedGlossary;  // Resolved glossary for target language
+  context?: {
+    documentPurpose?: string;
+    previousChunks?: string[];
+    documentSummary?: string;
+  };
+}
+```
+
+#### 结果
+
+```typescript
+interface TranslationResult {
+  content: string;           // Translated text
+  metadata: {
+    qualityScore: number;
+    qualityThreshold: number;
+    thresholdMet: boolean;
+    iterations: number;
+    tokensUsed: {
+      input: number;
+      output: number;
+      cacheRead?: number;
+      cacheWrite?: number;
+    };
+    duration: number;
+    provider: string;
+    model: string;
+  };
+  glossaryCompliance?: {
+    applied: string[];       // Terms successfully applied
+    missed: string[];        // Terms not found in translation
+  };
+}
+```
+
+## Self-Refine 算法
+
+代理实现了这个迭代优化过程：
+
+```typescript
+// Pseudocode
+async translate(request) {
+  // 1. Initial translation with glossary
+  let translation = await generateInitialTranslation(request);
+  let iterations = 1;
+
+  while (iterations < maxIterations) {
+    // 2. Evaluate quality
+    const evaluation = await evaluateQuality(translation);
+
+    if (evaluation.score >= qualityThreshold) {
+      break;  // Quality met
+    }
+
+    // 3. Generate improvement suggestions
+    const suggestions = await generateReflection(translation);
+
+    // 4. Apply improvements
+    translation = await improveTranslation(translation, suggestions);
+    iterations++;
+  }
+
+  return { content: translation, metadata: { ... } };
+}
+```
+
+## 使用示例
+
+### 基础翻译
+
+```typescript
+import { TranslationAgent, createClaudeProvider } from '@llm-translate/cli';
+
+const provider = createClaudeProvider();
+const agent = new TranslationAgent({
+  provider,
+  qualityThreshold: 85,
+});
+
+const result = await agent.translate({
+  content: 'Hello, world!',
+  sourceLang: 'en',
+  targetLang: 'ko',
+});
+
+console.log(result.content);  // 안녕하세요, 세계!
+console.log(result.metadata.qualityScore);  // 92
+```
+
+### 使用术语表
+
+```typescript
+import { loadGlossary, resolveGlossary } from '@llm-translate/cli';
+
+const glossary = await loadGlossary('./glossary.json');
+const resolved = resolveGlossary(glossary, 'ko');
+
+const result = await agent.translate({
+  content: 'The component renders a prop.',
+  sourceLang: 'en',
+  targetLang: 'ko',
+  glossary: resolved,
+});
+
+console.log(result.glossaryCompliance);
+// { applied: ['component', 'prop'], missed: [] }
+```
+
+### 使用上下文
+
+```typescript
+const result = await agent.translate({
+  content: 'Click the button to continue.',
+  sourceLang: 'en',
+  targetLang: 'ko',
+  context: {
+    documentPurpose: 'User interface instructions',
+    previousChunks: [
+      '이전 단계에서 설정을 완료했습니다.',  // Previous translation
+    ],
+  },
+});
+```
+
+### 严格质量模式
+
+```typescript
+import { TranslationError, ErrorCode } from '@llm-translate/cli';
+
+const agent = new TranslationAgent({
+  provider,
+  qualityThreshold: 95,
+  strictQuality: true,  // Throw if threshold not met
+});
+
+try {
+  const result = await agent.translate(request);
+} catch (error) {
+  if (error instanceof TranslationError &&
+      error.code === ErrorCode.QUALITY_THRESHOLD_NOT_MET) {
+    console.log(`Quality: ${error.details.score}/${error.details.threshold}`);
+    console.log(`Issues: ${error.details.issues.join(', ')}`);
+  }
+}
+```
+
+## 质量评估
+
+代理根据四个标准评估翻译：
+
+| 标准 | 权重 | 描述 |
+|-----------|--------|-------------|
+| 语义准确性 | 40% | 意义保持 |
+| 流畅性 | 25% | 自然语言流 |
+| 术语表合规性 | 20% | 术语一致性 |
+| 格式保持 | 15% | 结构维护 |
+
+### 评估结果
+
+```typescript
+interface QualityEvaluation {
+  score: number;           // 0-100
+  breakdown: {
+    accuracy: number;      // 0-40
+    fluency: number;       // 0-25
+    glossary: number;      // 0-20
+    format: number;        // 0-15
+  };
+  issues: string[];        // Specific problems identified
+}
+```
+
+## 提示缓存
+
+当 `enableCaching` 为 true（Claude 的默认值）时，代理会为缓存构建提示：
+
+```
+┌─────────────────────────────────┐
+│ System Instructions (CACHED)    │  ← Reused across chunks
+├─────────────────────────────────┤
+│ Glossary (CACHED)              │  ← Reused across chunks
+├─────────────────────────────────┤
+│ Source Text (NOT cached)       │  ← Changes per chunk
+└─────────────────────────────────┘
+```
+
+这可以为多分块文档减少 40-50% 的成本。
+
+## 高级：自定义评估
+
+覆盖默认评估逻辑：
+
+```typescript
+class CustomAgent extends TranslationAgent {
+  protected async evaluateQuality(
+    source: string,
+    translation: string,
+    sourceLang: string,
+    targetLang: string
+  ): Promise<QualityEvaluation> {
+    // Custom evaluation logic
+    const baseEval = await super.evaluateQuality(
+      source, translation, sourceLang, targetLang
+    );
+
+    // Add custom checks
+    if (translation.length < source.length * 0.5) {
+      baseEval.score -= 10;
+      baseEval.issues.push('Translation suspiciously short');
+    }
+
+    return baseEval;
+  }
+}
+```

package/docs/zh/api/engine.md

@@ -0,0 +1,274 @@
+# TranslationEngine
+
+::: info 翻译说明
+所有非英文文档均使用 Claude Sonnet 4 自动翻译。
+:::
+
+翻译操作的主要入口点。
+
+## 构造函数
+
+```typescript
+import { TranslationEngine } from '@llm-translate/cli';
+
+const engine = new TranslationEngine(options: TranslationEngineOptions);
+```
+
+### 选项
+
+```typescript
+interface TranslationEngineOptions {
+  provider: LLMProvider;
+  qualityThreshold?: number;      // Default: 85
+  maxIterations?: number;         // Default: 4
+  chunkingConfig?: ChunkingConfig;
+  verbose?: boolean;              // Default: false
+}
+```
+
+## 方法
+
+### translateFile
+
+翻译单个文件。
+
+```typescript
+const result = await engine.translateFile(options: TranslateFileOptions);
+```
+
+#### 选项
+
+```typescript
+interface TranslateFileOptions {
+  input: string;           // Input file path
+  output?: string;         // Output file path (optional)
+  sourceLang?: string;     // Source language (auto-detect if omitted)
+  targetLang: string;      // Target language (required)
+  glossary?: string | Glossary;  // Glossary path or object
+  context?: {
+    documentPurpose?: string;
+    preserveFormatting?: boolean;
+  };
+}
+```
+
+#### 返回值
+
+```typescript
+interface TranslateFileResult {
+  content: string;
+  outputPath?: string;
+  metadata: {
+    qualityScore: number;
+    qualityThreshold: number;
+    thresholdMet: boolean;
+    iterations: number;
+    tokensUsed: {
+      input: number;
+      output: number;
+      cacheRead?: number;
+      cacheWrite?: number;
+    };
+    duration: number;
+    chunks: number;
+  };
+}
+```
+
+#### 示例
+
+```typescript
+const result = await engine.translateFile({
+  input: 'docs/guide.md',
+  output: 'docs/guide.ko.md',
+  targetLang: 'ko',
+  glossary: './glossary.json',
+  context: {
+    documentPurpose: 'Technical documentation for developers',
+  },
+});
+
+console.log(`Quality: ${result.metadata.qualityScore}`);
+console.log(`Output: ${result.outputPath}`);
+```
+
+### translateContent
+
+直接翻译内容（无需文件 I/O）。
+
+```typescript
+const result = await engine.translateContent(
+  content: string,
+  options: TranslateContentOptions
+);
+```
+
+#### 选项
+
+```typescript
+interface TranslateContentOptions {
+  sourceLang?: string;
+  targetLang: string;
+  glossary?: ResolvedGlossary;
+  format?: 'markdown' | 'html' | 'text';
+  context?: {
+    documentPurpose?: string;
+    previousChunks?: string[];
+  };
+}
+```
+
+#### 示例
+
+```typescript
+const content = `
+# Hello World
+
+This is a **markdown** document.
+`;
+
+const result = await engine.translateContent(content, {
+  targetLang: 'ko',
+  format: 'markdown',
+});
+
+console.log(result.content);
+// # 안녕하세요
+//
+// 이것은 **마크다운** 문서입니다.
+```
+
+### translateDirectory
+
+翻译目录中的所有文件。
+
+```typescript
+const results = await engine.translateDirectory(options: TranslateDirectoryOptions);
+```
+
+#### 选项
+
+```typescript
+interface TranslateDirectoryOptions {
+  input: string;           // Input directory
+  output: string;          // Output directory
+  targetLang: string;
+  glossary?: string | Glossary;
+  pattern?: string;        // Glob pattern (default: '**/*.md')
+  exclude?: string[];      // Patterns to exclude
+  concurrency?: number;    // Parallel processing (default: 3)
+  continueOnError?: boolean;
+}
+```
+
+#### 返回值
+
+```typescript
+interface TranslateDirectoryResult {
+  successful: TranslateFileResult[];
+  failed: Array<{
+    file: string;
+    error: Error;
+  }>;
+  summary: {
+    total: number;
+    successful: number;
+    failed: number;
+    totalDuration: number;
+    averageQuality: number;
+  };
+}
+```
+
+#### 示例
+
+```typescript
+const results = await engine.translateDirectory({
+  input: './docs',
+  output: './docs-ko',
+  targetLang: 'ko',
+  glossary: './glossary.json',
+  concurrency: 5,
+  continueOnError: true,
+});
+
+console.log(`Translated: ${results.summary.successful}/${results.summary.total}`);
+console.log(`Average quality: ${results.summary.averageQuality}`);
+```
+
+## 事件
+
+TranslationEngine 继承自 EventEmitter：
+
+```typescript
+engine.on('chunk:start', (data) => {
+  console.log(`Starting chunk ${data.index}/${data.total}`);
+});
+
+engine.on('chunk:complete', (data) => {
+  console.log(`Chunk ${data.index}: quality ${data.quality}`);
+});
+
+engine.on('file:start', (data) => {
+  console.log(`Translating: ${data.file}`);
+});
+
+engine.on('file:complete', (data) => {
+  console.log(`Completed: ${data.file} (${data.quality})`);
+});
+```
+
+## 完整示例
+
+```typescript
+import {
+  TranslationEngine,
+  createClaudeProvider,
+  loadGlossary,
+  resolveGlossary,
+} from '@llm-translate/cli';
+
+async function translateDocs() {
+  // Setup provider
+  const provider = createClaudeProvider({
+    apiKey: process.env.ANTHROPIC_API_KEY,
+    defaultModel: 'claude-sonnet-4-5-20250929',
+  });
+
+  // Load and resolve glossary
+  const glossary = await loadGlossary('./glossary.json');
+
+  // Create engine
+  const engine = new TranslationEngine({
+    provider,
+    qualityThreshold: 90,
+    maxIterations: 5,
+    verbose: true,
+  });
+
+  // Track progress
+  engine.on('chunk:complete', ({ index, total, quality }) => {
+    console.log(`Progress: ${index}/${total} (quality: ${quality})`);
+  });
+
+  // Translate
+  try {
+    const result = await engine.translateFile({
+      input: 'README.md',
+      output: 'README.ko.md',
+      targetLang: 'ko',
+      glossary,
+    });
+
+    console.log('Translation complete!');
+    console.log(`Quality: ${result.metadata.qualityScore}`);
+    console.log(`Tokens: ${result.metadata.tokensUsed.input} in / ${result.metadata.tokensUsed.output} out`);
+
+    if (result.metadata.tokensUsed.cacheRead) {
+      console.log(`Cache hit: ${result.metadata.tokensUsed.cacheRead} tokens`);
+    }
+  } catch (error) {
+    console.error('Translation failed:', error.message);
+  }
+}
+```

package/docs/zh/api/index.md

@@ -0,0 +1,171 @@
+# API 参考
+
+::: info 翻译说明
+所有非英文文档均使用 Claude Sonnet 4 自动翻译。
+:::
+
+llm-translate 可以在您的 Node.js 应用程序中以编程方式使用。
+
+## 安装
+
+```bash
+npm install @llm-translate/cli
+```
+
+## 快速开始
+
+```typescript
+import { TranslationEngine, createClaudeProvider } from '@llm-translate/cli';
+
+// Create provider
+const provider = createClaudeProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+});
+
+// Create engine
+const engine = new TranslationEngine({
+  provider,
+  qualityThreshold: 85,
+});
+
+// Translate
+const result = await engine.translateFile({
+  input: 'README.md',
+  output: 'README.ko.md',
+  sourceLang: 'en',
+  targetLang: 'ko',
+});
+
+console.log(result.metadata);
+```
+
+## 核心类
+
+### [TranslationEngine](./engine)
+
+翻译操作的主要入口点。
+
+```typescript
+const engine = new TranslationEngine(options);
+await engine.translateFile({ input, output, targetLang });
+await engine.translateContent(content, options);
+```
+
+### [TranslationAgent](./agent)
+
+带有 Self-Refine 循环的低级翻译代理。
+
+```typescript
+const agent = new TranslationAgent({ provider, qualityThreshold });
+const result = await agent.translate(request);
+```
+
+### [Providers](./providers)
+
+LLM 提供商实现。
+
+```typescript
+import {
+  createClaudeProvider,
+  createOpenAIProvider,
+  createOllamaProvider,
+} from '@llm-translate/cli';
+```
+
+## 类型导出
+
+```typescript
+import type {
+  // Configuration
+  TranslationConfig,
+  ProviderConfig,
+
+  // Requests/Results
+  TranslationRequest,
+  TranslationResult,
+
+  // Glossary
+  Glossary,
+  GlossaryTerm,
+  ResolvedGlossary,
+
+  // Quality
+  QualityEvaluation,
+
+  // Provider
+  LLMProvider,
+  ChatMessage,
+  ChatResponse,
+} from '@llm-translate/cli';
+```
+
+## 实用函数
+
+### Chunking
+
+```typescript
+import { chunkContent, chunkMarkdown } from '@llm-translate/cli';
+
+const chunks = chunkContent(text, { maxTokens: 1024 });
+const mdChunks = chunkMarkdown(markdown, { maxTokens: 1024 });
+```
+
+### 术语表
+
+```typescript
+import { loadGlossary, resolveGlossary, createGlossaryLookup } from '@llm-translate/cli';
+
+const glossary = await loadGlossary('./glossary.json');
+const resolved = resolveGlossary(glossary, 'ko');
+const lookup = createGlossaryLookup(resolved);
+
+const terms = lookup.findAll(sourceText);
+```
+
+### 令牌估算
+
+```typescript
+import { estimateTokens, calculateTokenBudget } from '@llm-translate/cli';
+
+const tokens = estimateTokens(text);
+const budget = calculateTokenBudget(text, { glossaryTokens: 500 });
+```
+
+## 错误处理
+
+```typescript
+import { TranslationError, ErrorCode } from '@llm-translate/cli';
+
+try {
+  await engine.translateFile(options);
+} catch (error) {
+  if (error instanceof TranslationError) {
+    switch (error.code) {
+      case ErrorCode.FILE_NOT_FOUND:
+        // Handle missing file
+        break;
+      case ErrorCode.QUALITY_THRESHOLD_NOT_MET:
+        // Handle quality issue
+        console.log('Score:', error.details.score);
+        break;
+      case ErrorCode.PROVIDER_RATE_LIMITED:
+        // Handle rate limit
+        break;
+    }
+  }
+}
+```
+
+## 错误代码
+
+| 代码 | 描述 |
+|------|-------------|
+|`FILE_NOT_FOUND`| 输入文件不存在 |
+|`INVALID_CONFIG`| 配置验证失败 |
+|`GLOSSARY_NOT_FOUND`| 术语表文件未找到 |
+|`GLOSSARY_INVALID`| 术语表验证失败 |
+|`PROVIDER_AUTH_FAILED`| API 密钥无效 |
+|`PROVIDER_RATE_LIMITED`| 超出速率限制 |
+|`PROVIDER_ERROR`| 一般提供商错误 |
+|`QUALITY_THRESHOLD_NOT_MET`| 翻译质量低于阈值 |
+|`PARSE_ERROR`| 文档解析失败 |