@llm-translate/cli 1.0.0-next.1

package/docs/index.md

@@ -0,0 +1,63 @@
+---
+layout: home
+
+hero:
+  name: llm-translate
+  text: LLM-Powered Document Translation
+  tagline: Translate documents with glossary enforcement, quality control, and cost optimization
+  actions:
+    - theme: brand
+      text: Get Started
+      link: ./guide/getting-started
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/selenehyun/llm-translate
+
+features:
+  - icon: 📚
+    title: Glossary Enforcement
+    details: Ensure consistent terminology across your translations with enforced glossary terms that never get mistranslated.
+  - icon: 🔄
+    title: Self-Refine Quality Control
+    details: Iterative translation refinement using AI-powered quality evaluation to meet your quality threshold.
+  - icon: 💰
+    title: Cost Optimization
+    details: Prompt caching reduces API costs by up to 90% for repeated content like glossaries and system prompts.
+  - icon: 🔌
+    title: Multi-Provider Support
+    details: Works with Claude, OpenAI, and Ollama. Switch providers without changing your workflow.
+  - icon: 📄
+    title: Format Preservation
+    details: Maintains markdown formatting, code blocks, links, and document structure during translation.
+  - icon: ⚡
+    title: Batch Processing
+    details: Translate entire directories with parallel processing and progress tracking.
+---
+
+## Quick Start
+
+```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
+```
+
+## Why llm-translate?
+
+Traditional translation tools struggle with technical documentation:
+
+- **Inconsistent terminology** - "API endpoint" translated differently each time
+- **Broken formatting** - Code blocks and markdown get mangled
+- **No quality control** - Accept whatever the LLM outputs
+
+llm-translate solves these problems with:
+
+1. **Glossary enforcement** - Define terms once, apply everywhere
+2. **AST-based chunking** - Preserves document structure
+3. **Quality-aware refinement** - Iterates until quality threshold is met
+4. **Prompt caching** - Reduces costs for large documents

package/docs/ja/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(', ')}`);
+  }
+}
+```
+
+## 品質評価
+
+エージェントは4つの基準で翻訳を評価します：
+
+| 基準 | 重み | 説明 |
+|-----------|--------|-------------|
+| 意味の正確性 | 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/ja/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);
+  }
+}
+```