@llm-translate/cli 1.0.0-next.1

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

@@ -0,0 +1,64 @@
+# 변경 로그
+
+::: info 번역
+모든 비영어 문서는 Claude Sonnet 4를 사용하여 자동으로 번역됩니다.
+:::
+
+llm-translate의 모든 주목할 만한 변경 사항이 이 파일에 문서화됩니다.
+
+형식은 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)를 기반으로 하며,
+이 프로젝트는 [Semantic Versioning](https://semver.org/spec/v2.0.0.html)을 준수합니다.
+
+## [Unreleased]
+
+### 추가됨
+
+- Claude 모델에 대한 프롬프트 캐싱 지원 (40-50% 비용 절감)
+- 번역 결과에서 캐시 토큰 사용량 추적
+- TranslationAgent의 `enableCaching` 옵션
+- 토큰 사용량 메타데이터의 `cacheRead` 및 `cacheWrite` 필드
+- MQM (Multidimensional Quality Metrics) 기반 품질 평가 시스템
+- 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/ko/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
+```