@llm-translate/cli 1.0.0-next.1

package/docs/ko/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/ko/api/engine.md

@@ -0,0 +1,274 @@
+# TranslationEngine
+
+::: info 번역
+모든 비영어 문서는 Claude Sonnet 4를 사용하여 자동으로 번역됩니다.
+:::
+
+번역 작업의 주요 진입점입니다.
+
+## Constructor
+
+```typescript
+import { TranslationEngine } from '@llm-translate/cli';
+
+const engine = new TranslationEngine(options: TranslationEngineOptions);
+```
+
+### Options
+
+```typescript
+interface TranslationEngineOptions {
+  provider: LLMProvider;
+  qualityThreshold?: number;      // Default: 85
+  maxIterations?: number;         // Default: 4
+  chunkingConfig?: ChunkingConfig;
+  verbose?: boolean;              // Default: false
+}
+```
+
+## Methods
+
+### translateFile
+
+단일 파일을 번역합니다.
+
+```typescript
+const result = await engine.translateFile(options: TranslateFileOptions);
+```
+
+#### Options
+
+```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;
+  };
+}
+```
+
+#### Returns
+
+```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;
+  };
+}
+```
+
+#### Example
+
+```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
+);
+```
+
+#### Options
+
+```typescript
+interface TranslateContentOptions {
+  sourceLang?: string;
+  targetLang: string;
+  glossary?: ResolvedGlossary;
+  format?: 'markdown' | 'html' | 'text';
+  context?: {
+    documentPurpose?: string;
+    previousChunks?: string[];
+  };
+}
+```
+
+#### Example
+
+```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);
+```
+
+#### Options
+
+```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;
+}
+```
+
+#### Returns
+
+```typescript
+interface TranslateDirectoryResult {
+  successful: TranslateFileResult[];
+  failed: Array<{
+    file: string;
+    error: Error;
+  }>;
+  summary: {
+    total: number;
+    successful: number;
+    failed: number;
+    totalDuration: number;
+    averageQuality: number;
+  };
+}
+```
+
+#### Example
+
+```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}`);
+```
+
+## Events
+
+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})`);
+});
+```
+
+## Full Example
+
+```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/ko/api/index.md

@@ -0,0 +1,171 @@
+# API Reference
+
+::: 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`| 문서 파싱에 실패했습니다 |