@llm-translate/cli 1.0.0-next.1

package/docs/ko/cli/init.md

@@ -0,0 +1,158 @@
+# llm-translate init
+
+::: info 번역
+모든 비영어 문서는 Claude Sonnet 4를 사용하여 자동으로 번역됩니다.
+:::
+
+프로젝트를 위한 설정 파일을 초기화합니다.
+
+## 개요
+
+```bash
+llm-translate init [options]
+```
+
+## 옵션
+
+| 옵션 | 기본값 | 설명 |
+|--------|---------|-------------|
+|`--provider `,`-p`| claude | 기본 제공자 |
+|`--model `,`-m`| 다양함 | 기본 모델 |
+|`--quality`| 85 | 기본 품질 임계값 |
+|`--glossary`| 없음 | 용어집 템플릿 생성 |
+|`--force `,`-f`| false | 기존 설정 덮어쓰기 |
+
+## 예제
+
+### 기본 초기화
+
+```bash
+llm-translate init
+```
+
+`.translaterc.json` 를 생성합니다:
+
+```json
+{
+  "provider": {
+    "name": "claude",
+    "model": "claude-haiku-4-5-20251001"
+  },
+  "translation": {
+    "qualityThreshold": 85,
+    "maxIterations": 4
+  },
+  "paths": {}
+}
+```
+
+### 제공자 지정
+
+```bash
+llm-translate init --provider openai --model gpt-4o
+```
+
+### 용어집 템플릿과 함께
+
+```bash
+llm-translate init --glossary
+```
+
+또한 `glossary.json` 를 생성합니다:
+
+```json
+{
+  "sourceLanguage": "en",
+  "version": "1.0.0",
+  "terms": [
+    {
+      "source": "example",
+      "targets": {
+        "ko": "예시"
+      },
+      "context": "Replace with your terms"
+    }
+  ]
+}
+```
+
+### 사용자 정의 품질
+
+```bash
+llm-translate init --quality 95
+```
+
+## 대화형 모드
+
+옵션 없이 실행하면 init가 대화형으로 실행됩니다:
+
+```
+$ llm-translate init
+
+llm-translate Configuration Setup
+
+? Select provider: (Use arrow keys)
+❯ claude
+  openai
+  ollama
+
+? Select model: (Use arrow keys)
+❯ claude-haiku-4-5-20251001 (fast, cost-effective)
+  claude-sonnet-4-5-20250929 (balanced)
+  claude-opus-4-5-20251101 (highest quality)
+
+? Quality threshold: (85)
+? Create glossary template? (y/N)
+
+✓ Created .translaterc.json
+```
+
+## 출력 파일
+
+### .translaterc.json
+
+```json
+{
+  "$schema": "https://llm-translate.dev/schema.json",
+  "provider": {
+    "name": "claude",
+    "model": "claude-haiku-4-5-20251001"
+  },
+  "translation": {
+    "qualityThreshold": 85,
+    "maxIterations": 4,
+    "preserveFormatting": true
+  },
+  "chunking": {
+    "maxTokens": 1024,
+    "overlapTokens": 150
+  },
+  "paths": {
+    "glossary": "./glossary.json",
+    "cache": "./.translate-cache"
+  }
+}
+```
+
+### glossary.json (--glossary와 함께)
+
+```json
+{
+  "$schema": "https://llm-translate.dev/glossary-schema.json",
+  "sourceLanguage": "en",
+  "version": "1.0.0",
+  "description": "Project glossary",
+  "terms": []
+}
+```
+
+## 기존 설정 덮어쓰기
+
+```bash
+# Will fail if config exists
+llm-translate init
+# Error: .translaterc.json already exists. Use --force to overwrite.
+
+# Force overwrite
+llm-translate init --force
+```

package/docs/ko/guide/chunking.md

@@ -0,0 +1,271 @@
+# Chunking 전략
+
+::: info 번역
+모든 비영어 문서는 Claude Sonnet 4를 사용하여 자동으로 번역됩니다.
+:::
+
+대용량 문서는 번역을 위해 청크로 분할됩니다. Chunking을 이해하면 품질과 비용을 최적화하는 데 도움이 됩니다.
+
+## 왜 Chunking인가?
+
+LLM은 컨텍스트 제한이 있으며 집중된 콘텐츠에서 더 나은 성능을 발휘합니다:
+
+| 이유 | 설명 |
+|--------|-------------|
+| **컨텍스트 제한** | 모델에는 최대 입력 크기가 있습니다 |
+| **품질** | 작은 청크는 더 집중된 주의를 받습니다 |
+| **비용** | 반복되는 콘텐츠의 캐싱을 허용합니다 |
+| **진행률** | 진행률 추적 및 재개를 가능하게 합니다 |
+
+## 기본 구성
+
+```json
+{
+  "chunking": {
+    "maxTokens": 1024,
+    "overlapTokens": 150
+  }
+}
+```
+
+## 청크 크기 옵션
+
+### maxTokens
+
+청크당 최대 토큰 수(프롬프트 오버헤드 제외).
+
+| 크기 | 최적 용도 | 트레이드오프 |
+|------|----------|-----------|
+| 512 | 높은 품질 요구사항 | 더 많은 API 호출 |
+| **1024** | 일반 사용 (기본값) | 균형 잡힌 |
+| 2048 | 비용 최적화 | 품질이 저하될 수 있음 |
+
+### overlapTokens
+
+이전 청크의 컨텍스트가 경계 간 연속성을 보장합니다.
+
+```
+Chunk 1: [Content A                    ]
+Chunk 2:            [overlap][Content B                    ]
+Chunk 3:                              [overlap][Content C  ]
+```
+
+::: tip 권장 오버랩
+`maxTokens` 값의 10-15%를 사용하세요. 1024 토큰의 경우 100-150 오버랩 토큰이 잘 작동합니다.
+:::
+
+## Markdown 인식 Chunking
+
+llm-translate는 문서 구조를 존중하는 AST 기반 chunking을 사용합니다.
+
+### 보존되는 경계
+
+청크 분할기는 다음 요소들을 절대 분할하지 않습니다:
+
+| 요소 | 동작 |
+|---------|----------|
+| 헤더 | 섹션 경계가 보존됨 |
+| 코드 블록 | 항상 온전하게 유지됨 |
+| 목록 | 가능한 경우 항목들이 그룹화됨 |
+| 테이블 | 청크 간에 절대 분할되지 않음 |
+| 단락 | 자연스러운 경계에서 분할됨 |
+
+### 예시
+
+::: details 클릭하여 chunking 예시 보기
+
+**입력 문서:**
+
+```markdown
+# Introduction
+
+This is the introduction paragraph that explains
+the purpose of the document.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 20+
+- npm or yarn
+
+### Installation
+
+npm install @llm-translate/cli
+```
+
+**결과:**
+
+```
+Chunk 1: # Introduction + paragraph
+Chunk 2: ## Getting Started + ### Prerequisites + list
+Chunk 3: ### Installation + code block
+```
+
+:::
+
+## 구성
+
+::: code-group
+
+```bash [CLI]
+llm-translate file doc.md --target ko --chunk-size 2048
+```
+
+```json [.translaterc.json]
+{
+  "chunking": {
+    "maxTokens": 2048,
+    "overlapTokens": 200,
+    "preservePatterns": [
+      "```[\\s\\S]*?```",
+      "\\|[^\\n]+\\|"
+    ]
+  }
+}
+```
+
+```typescript [Programmatic]
+import { chunkContent } from '@llm-translate/cli';
+
+const chunks = chunkContent(content, {
+  maxTokens: 1024,
+  overlapTokens: 150,
+});
+```
+
+:::
+
+## 최적화 프리셋
+
+우선순위에 따라 선택하세요:
+
+::: code-group
+
+```json [Quality Focus]
+{
+  "chunking": {
+    "maxTokens": 512,
+    "overlapTokens": 100
+  }
+}
+```
+
+```json [Cost Focus]
+{
+  "chunking": {
+    "maxTokens": 2048,
+    "overlapTokens": 50
+  }
+}
+```
+
+```json [Long Documents]
+{
+  "chunking": {
+    "maxTokens": 1500,
+    "overlapTokens": 150
+  },
+  "translation": {
+    "maxIterations": 3
+  }
+}
+```
+
+:::
+
+::: info 각 프리셋을 언제 사용할지
+- **품질 중심**: 기술 문서, 법적 콘텐츠
+- **비용 중심**: 블로그 포스트, 일반 콘텐츠
+- **긴 문서**: 책, 포괄적인 가이드
+:::
+
+## 콘텐츠 보존
+
+### 보호되는 것
+
+llm-translate는 특정 콘텐츠를 번역에서 자동으로 보호합니다:
+
+| 콘텐츠 유형 | 예시 | 동작 |
+|--------------|---------|----------|
+| 코드 블록 |` __INLINE_CODE_16__ `| 절대 번역되지 않음 |
+| 인라인 코드 |`` ` variable ` ``| 보존됨 |
+| URL |`https://...`| 보존됨 |
+| 파일 경로 |`./path/to/file`| 보존됨 |
+
+### 링크 처리
+
+링크 URL은 보존되지만 링크 텍스트는 번역됩니다:
+
+```markdown
+[Getting Started](./getting-started.md)
+↓
+[시작하기](./getting-started.md)
+```
+
+## 디버깅
+
+### 청크 미리보기
+
+`--dry-run` 를 사용하여 문서가 어떻게 청크로 나뉠지 확인하세요:
+
+```bash
+llm-translate file doc.md --target ko --dry-run --verbose
+```
+
+출력:
+```
+Document Analysis:
+  Total tokens: ~5,200
+  Chunks: 6
+  Average chunk size: ~867 tokens
+
+Chunk breakdown:
+  [1] Lines 1-45 (Introduction) - 823 tokens
+  [2] Lines 46-89 (Getting Started) - 912 tokens
+  [3] Lines 90-134 (Configuration) - 878 tokens
+  ...
+```
+
+### 프로그래밍 방식 검사
+
+```typescript
+import { chunkContent, getChunkStats } from '@llm-translate/cli';
+
+const chunks = chunkContent(content, { maxTokens: 1024 });
+const stats = getChunkStats(chunks);
+
+console.log(`Total chunks: ${stats.count}`);
+console.log(`Average size: ${stats.avgTokens} tokens`);
+```
+
+## 문제 해결
+
+::: warning 청크가 너무 작음
+**증상**: 많은 작은 청크, 과도한 API 호출
+
+**해결책**:`maxTokens` 를 증가시키세요
+```json
+{ "chunking": { "maxTokens": 2048 } }
+```
+:::
+
+::: warning 청크 간 컨텍스트 손실
+**증상**: 섹션 간 일관성 없는 용어
+
+**해결책**: 오버랩을 증가시키거나 용어집을 사용하세요
+```json
+{ "chunking": { "overlapTokens": 300 } }
+```
+:::
+
+::: danger 코드 블록이 분할됨
+**증상**: 출력에서 구문 오류
+
+**원인**: 이는 절대 발생해서는 안 됩니다. 발생한다면 [이슈를 신고](https://github.com/selenehyun/llm-translate/issues)해 주세요.
+:::
+
+::: warning 테이블이 손상됨
+**증상**: 깨진 테이블 형식
+
+**해결책**: 테이블은 자동으로 온전하게 유지되어야 합니다. 매우 큰 테이블(100+ 행)의 경우 수동으로 분할하는 것을 고려하세요.

package/docs/ko/guide/configuration.md

@@ -0,0 +1,139 @@
+# 설정
+
+::: info 번역
+모든 비영어 문서는 Claude Sonnet 4를 사용하여 자동으로 번역됩니다.
+:::
+
+llm-translate는 계층화된 설정 시스템을 사용합니다. 설정은 다음 순서로 적용됩니다(나중 설정이 이전 설정을 덮어씁니다):
+
+1. 내장 기본값
+2. 설정 파일 (`.translaterc.json`)
+3. 환경 변수
+4. CLI 인수
+
+## 설정 파일
+
+프로젝트 루트에 `.translaterc.json` 를 생성하세요:
+
+```json
+{
+  "provider": {
+    "name": "claude",
+    "model": "claude-haiku-4-5-20251001",
+    "apiKey": null
+  },
+  "translation": {
+    "qualityThreshold": 85,
+    "maxIterations": 4,
+    "preserveFormatting": true
+  },
+  "chunking": {
+    "maxTokens": 1024,
+    "overlapTokens": 150
+  },
+  "paths": {
+    "glossary": "./glossary.json",
+    "cache": "./.translate-cache"
+  }
+}
+```
+
+### 제공자 설정
+
+| 옵션 | 타입 | 기본값 | 설명 |
+|--------|------|---------|-------------|
+|`name `| string |`"claude"`| 제공자 이름:` claude `,` openai `,` ollama`|
+|`model`| string | 다양함 | 모델 식별자 |
+|`apiKey`| string | null | API 키 (환경 변수 권장) |
+|`baseUrl`| string | null | 사용자 정의 API 엔드포인트 |
+
+### 번역 설정
+
+| 옵션 | 타입 | 기본값 | 설명 |
+|--------|------|---------|-------------|
+|`qualityThreshold `| number |` 85`| 최소 품질 점수 (0-100) |
+|`maxIterations `| number |` 4`| 최대 개선 반복 횟수 |
+|`preserveFormatting `| boolean |` true`| Markdown/HTML 구조 보존 |
+
+### Chunking 설정
+
+| 옵션 | 타입 | 기본값 | 설명 |
+|--------|------|---------|-------------|
+|`maxTokens `| number |` 1024`| 청크당 최대 토큰 수 |
+|`overlapTokens `| number |` 150`| 청크 간 컨텍스트 중복 |
+
+### 경로 설정
+
+| 옵션 | 타입 | 기본값 | 설명 |
+|--------|------|---------|-------------|
+|`glossary`| string | null | 용어집 파일 경로 |
+|`cache`| string | null | 번역 캐시 경로 |
+
+## 환경 변수
+
+```bash
+# API Keys
+ANTHROPIC_API_KEY=sk-ant-xxxxx
+OPENAI_API_KEY=sk-xxxxx
+OLLAMA_BASE_URL=http://localhost:11434
+
+# Default Settings
+LLM_TRANSLATE_PROVIDER=claude
+LLM_TRANSLATE_MODEL=claude-haiku-4-5-20251001
+LLM_TRANSLATE_QUALITY_THRESHOLD=85
+```
+
+## CLI 재정의 예시
+
+```bash
+# Override provider
+llm-translate file doc.md -o doc.ko.md --target ko --provider openai
+
+# Override model
+llm-translate file doc.md -o doc.ko.md --target ko --model claude-sonnet-4-5-20250929
+
+# Override quality threshold
+llm-translate file doc.md -o doc.ko.md --target ko --quality 90
+
+# Override max iterations
+llm-translate file doc.md -o doc.ko.md --target ko --max-iterations 6
+```
+
+## 프로젝트별 설정
+
+모노레포나 다중 프로젝트 설정의 경우, 각 프로젝트 디렉토리에 `.translaterc.json` 을 배치하세요:
+
+```
+my-monorepo/
+├── packages/
+│   ├── frontend/
+│   │   ├── .translaterc.json  # Frontend-specific terms
+│   │   └── docs/
+│   └── backend/
+│       ├── .translaterc.json  # Backend-specific terms
+│       └── docs/
+└── .translaterc.json          # Shared defaults
+```
+
+llm-translate는 현재 디렉토리부터 상위로 설정 파일을 검색합니다.
+
+## 모델 선택 가이드
+
+| 모델 | 속도 | 품질 | 비용 | 최적 용도 |
+|-------|-------|---------|------|----------|
+|`claude-haiku-4-5-20251001`| 빠름 | 좋음 | 낮음 | 일반 문서, 대용량 |
+|`claude-sonnet-4-5-20250929`| 보통 | 우수 | 보통 | 기술 문서, 품질 중요 |
+|`claude-opus-4-5-20251101`| 느림 | 최고 | 높음 | 복잡한 내용, 미묘한 텍스트 |
+|`gpt-4o-mini`| 빠름 | 좋음 | 낮음 | Haiku 대안 |
+|`gpt-4o`| 보통 | 우수 | 보통 | Sonnet 대안 |
+
+## 품질 임계값 가이드라인
+
+| 임계값 | 사용 사례 |
+|-----------|----------|
+| 70-75 | 초안 번역, 내부 문서 |
+| 80-85 | 표준 문서 (기본값) |
+| 90-95 | 공개용, 마케팅 콘텐츠 |
+| 95+ | 법률, 의료, 규제 콘텐츠 |
+
+높은 임계값은 더 많은 반복이 필요하며 비용이 더 많이 듭니다.

package/docs/ko/guide/cost-optimization.md

@@ -0,0 +1,30 @@
+# 비용 최적화
+
+::: info 번역
+모든 비영어 문서는 Claude Sonnet 4.5를 사용하여 자동으로 번역됩니다.
+:::
+
+이 가이드는 번역 품질을 유지하면서 API 비용을 최소화하는 전략을 다룹니다.
+
+## 비용 구조
+
+### 토큰 가격 (2025년 기준)
+
+| 모델 | 입력 (1K) | 출력 (1K) | 캐시 읽기 | 캐시 쓰기 |
+|-------|-----------|-------------|------------|-------------|
+| Claude Haiku 4.5 | $0.001 | $0.005 | $0.0001 | $0.00125 |
+| Claude Sonnet 4.5 | $0.003 | $0.015 | $0.0003 | $0.00375 |
+| Claude Opus 4.5 | $0.015 | $0.075 | $0.0015 | $0.01875 |
+| GPT-4o-mini | $0.00015 | $0.0006 | 자동 | 자동 |
+| GPT-4o | $0.0025 | $0.01 | 자동 | 자동 |
+
+### 비용 요소
+
+- [ ] 표준 문서에는 Haiku를 사용합니다
+- [ ] 품질 임계값을 적절히 설정합니다 (필요 이상으로 높게 설정하지 않습니다)
+- [ ] 프롬프트 캐싱을 활성화하고 최대화합니다
+- [ ] 파일을 배치로 처리합니다
+- [ ] 용어집을 간결하게 유지합니다
+- [ ] 증분 업데이트를 위해 번역 캐시를 사용합니다
+- [ ] 상세 출력으로 비용을 모니터링합니다
+- [ ] 대규모 작업 전에 비용을 추정합니다