@llm-translate/cli 1.0.0-next.1

package/docs/ko/guide/providers.md

@@ -0,0 +1,232 @@
+# 제공자
+
+::: info 번역
+모든 비영어 문서는 Claude Sonnet 4를 사용하여 자동으로 번역됩니다.
+:::
+
+llm-translate는 여러 LLM 제공자를 지원합니다. 각각은 서로 다른 장점과 트레이드오프를 가지고 있습니다.
+
+## 지원되는 제공자
+
+| 제공자 | 캐싱 | 최적 용도 | 설정 복잡도 |
+|----------|---------|----------|------------------|
+| Claude | 완전 지원 | 품질 + 비용 | 쉬움 |
+| OpenAI | 자동 | 생태계 | 쉬움 |
+| Ollama | 없음 | 프라이버시/오프라인 | 보통 |
+
+## Claude (권장)
+
+### Claude를 선택하는 이유?
+
+- **프롬프트 캐싱**: 최대 90% 비용 절감
+- **높은 품질**: 뛰어난 번역 정확도
+- **긴 컨텍스트**: 200K 토큰 컨텍스트 윈도우
+- **다양한 계층**: Haiku (빠름), Sonnet (균형), Opus (최고)
+
+### 설정
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-xxxxx
+```
+
+### 모델 선택
+
+```bash
+# Fast and cheap (default)
+llm-translate file doc.md --target ko --model claude-haiku-4-5-20251001
+
+# Balanced quality/cost
+llm-translate file doc.md --target ko --model claude-sonnet-4-5-20250929
+
+# Highest quality
+llm-translate file doc.md --target ko --model claude-opus-4-5-20251101
+```
+
+### 각 모델 사용 시기
+
+| 모델 | 사용 사례 |
+|-------|----------|
+| Haiku | README 파일, 간단한 문서, 대용량 |
+| Sonnet | 기술 문서, API 참조 |
+| Opus | 법률, 마케팅, 미묘한 내용 |
+
+## OpenAI
+
+### 설정
+
+```bash
+export OPENAI_API_KEY=sk-xxxxx
+```
+
+### 사용법
+
+```bash
+llm-translate file doc.md --target ko --provider openai --model gpt-4o
+```
+
+### 사용 가능한 모델
+
+| 모델 | 속도 | 품질 | 비용 |
+|-------|-------|---------|------|
+| gpt-4o-mini | 빠름 | 좋음 | 매우 낮음 |
+| gpt-4o | 보통 | 뛰어남 | 보통 |
+| gpt-4-turbo | 보통 | 뛰어남 | 높음 |
+
+### 사용 시기
+
+- 다른 서비스에서 이미 OpenAI를 사용하는 경우
+- 특정 OpenAI 기능이 필요한 경우
+- Azure OpenAI를 선호하는 경우 (사용자 정의 baseUrl 설정)
+
+## Ollama
+
+프라이버시나 오프라인 사용을 위한 로컬, 자체 호스팅 LLM입니다. API 키가 필요하지 않습니다.
+
+::: warning 모델에 따라 품질이 달라집니다
+Ollama 번역 품질은 **모델 선택에 크게 의존합니다**. 신뢰할 수 있는 번역 결과를 위해서는:
+
+- **최소**: 14B+ 매개변수 모델 (예:`qwen2.5:14b `,` llama3.1:14b`)
+- **권장**: 32B+ 모델 (예:`qwen2.5:32b `,` llama3.3:70b`)
+- **권장하지 않음**: 7B 미만 모델은 일관성이 없고 종종 사용할 수 없는 번역을 생성합니다
+
+작은 모델(3B, 7B)은 간단한 내용에서는 작동할 수 있지만 기술 문서에서는 자주 실패하거나, 불완전한 출력을 생성하거나, 형식 지침을 무시합니다.
+:::
+
+### 빠른 설정
+
+```bash
+# 1. Install (macOS)
+brew install ollama
+
+# 2. Pull qwen2.5:14b (recommended)
+ollama pull qwen2.5:14b
+
+# 3. Translate
+llm-translate file doc.md -s en -t ko --provider ollama --model qwen2.5:14b
+```
+
+### 권장 모델
+
+| 모델 | RAM | 품질 | 최적 용도 |
+|-------|-----|---------|----------|
+|`qwen2.5:14b`| 16GB | 매우 좋음 | **최고의 균형 (권장)** |
+|`qwen2.5:32b`| 32GB | 뛰어남 | 더 높은 품질 |
+|`llama3.1:8b`| 8GB | 좋음 | 가벼운 무게 |
+|`llama3.2`| 4GB | 보통 | 간단한 내용만 |
+
+### 사용 시기
+
+- 민감한/개인 문서
+- 오프라인 환경
+- 비용 최적화 (API 수수료 없음)
+- 간단하거나 보통 복잡도의 내용
+
+::: tip 전체 가이드
+완전한 설정 지침, GPU 최적화, 문제 해결 및 고급 구성은 [Ollama를 사용한 로컬 번역](./ollama)을 참조하세요.
+:::
+
+## 제공자 비교
+
+### 품질
+
+```
+Opus > Sonnet ≈ GPT-4o > Haiku ≈ GPT-4o-mini > Qwen2.5:32b > Qwen2.5:14b
+```
+
+### 비용 (100만 토큰당)
+
+```
+Ollama ($0) < GPT-4o-mini ($0.15) < Haiku ($1) < GPT-4o ($2.5) < Sonnet ($3) < Opus ($15)
+```
+
+### 속도
+
+```
+Haiku ≈ GPT-4o-mini > Sonnet ≈ GPT-4o > Opus > Ollama (varies with hardware)
+```
+
+## 제공자 전환
+
+### CLI
+
+```bash
+# Different providers
+llm-translate file doc.md -s en -t ko --provider claude
+llm-translate file doc.md -s en -t ko --provider openai
+llm-translate file doc.md -s en -t ko --provider ollama
+```
+
+### 설정 파일
+
+```json
+{
+  "provider": {
+    "name": "openai",
+    "model": "gpt-4o"
+  }
+}
+```
+
+### 프로그래밍 방식
+
+```typescript
+import {
+  createClaudeProvider,
+  createOpenAIProvider,
+  createOllamaProvider,
+  TranslationEngine,
+} from '@llm-translate/cli';
+
+// Switch providers easily
+const providers = {
+  claude: createClaudeProvider(),
+  openai: createOpenAIProvider(),
+  ollama: createOllamaProvider(),
+};
+
+const engine = new TranslationEngine({
+  provider: providers[selectedProvider],
+});
+```
+
+## 폴백 구성
+
+신뢰성을 위한 폴백 제공자를 구성합니다:
+
+```json
+{
+  "provider": {
+    "name": "claude",
+    "model": "claude-haiku-4-5-20251001",
+    "fallback": [
+      { "name": "openai", "model": "gpt-4o-mini" },
+      { "name": "ollama", "model": "llama3.1" }
+    ]
+  }
+}
+```
+
+## 사용자 정의 엔드포인트
+
+### Azure OpenAI
+
+```json
+{
+  "provider": {
+    "name": "openai",
+    "baseUrl": "https://your-resource.openai.azure.com",
+    "apiKey": "your-azure-key"
+  }
+}
+```
+
+### 자체 호스팅
+
+```json
+{
+  "provider": {
+    "name": "ollama",
+    "baseUrl": "https://your-server.com:11434"
+  }
+}
+```

package/docs/ko/guide/quality-control.md

@@ -0,0 +1,137 @@
+# 품질 관리
+
+::: info 번역
+모든 비영어 문서는 Claude Sonnet 4를 사용하여 자동으로 번역됩니다.
+:::
+
+llm-translate는 Self-Refine 알고리즘을 사용하여 번역 품질이 요구사항을 충족하도록 보장합니다.
+
+## Self-Refine 작동 방식
+
+```
+┌─────────────────┐
+│ Initial Translate│
+└────────┬────────┘
+         ▼
+┌─────────────────┐
+│ Evaluate Quality │◀──────────────┐
+└────────┬────────┘               │
+         ▼                        │
+    Score >= Threshold?           │
+         │                        │
+    No   │   Yes                  │
+         │    │                   │
+         ▼    ▼                   │
+┌─────────┐ ┌──────┐              │
+│ Reflect │ │ Done │              │
+└────┬────┘ └──────┘              │
+     ▼                            │
+┌─────────────────┐               │
+│    Improve      │───────────────┘
+└─────────────────┘
+```
+
+### 1. 초기 번역
+
+첫 번째 번역은 다음과 함께 생성됩니다:
+- 전체 용어집 컨텍스트
+- 문서 구조 정보
+- 이전 청크 컨텍스트 (연속성을 위해)
+
+### 2. 품질 평가
+
+각 번역은 네 가지 기준으로 점수가 매겨집니다:
+
+| 기준 | 가중치 | 설명 |
+|------|--------|------|
+| 의미 정확성 | 40% | 올바른 의미를 전달하는가? |
+| 유창성 | 25% | 대상 언어로 자연스럽게 읽히는가? |
+| 용어집 준수 | 20% | 모든 용어집 용어가 올바르게 적용되었는가? |
+| 형식 보존 | 15% | Markdown/HTML 구조가 유지되었는가? |
+
+### 3. 성찰
+
+품질이 임계값 이하인 경우, LLM이 다음을 분석합니다:
+- 어떤 구체적인 문제가 존재하는지
+- 어떤 용어집 용어가 누락되었는지
+- 유창성을 어디서 개선할 수 있는지
+
+### 4. 개선
+
+성찰 피드백을 바탕으로 대상 수정이 적용되고, 그 후 사이클이 반복됩니다.
+
+## 구성
+
+### 품질 임계값
+
+```bash
+# CLI
+llm-translate file doc.md -o doc.ko.md -s en -t ko --quality 90
+
+# Config file
+{
+  "translation": {
+    "qualityThreshold": 90
+  }
+}
+```
+
+### 최대 반복 횟수
+
+```bash
+# CLI
+llm-translate file doc.md -o doc.ko.md -s en -t ko --max-iterations 6
+
+# Config file
+{
+  "translation": {
+    "maxIterations": 6
+  }
+}
+```
+
+### 엄격 모드
+
+품질 임계값이 충족되지 않으면 실패:
+
+```bash
+llm-translate file doc.md -o doc.ko.md -s en -t ko --strict-quality
+```
+
+종료 코드:
+-`0`- 성공
+-`4`- 품질 임계값 미충족 (엄격 모드)
+
+## 품질 점수 해석
+
+| 점수 | 품질 수준 | 설명 |
+|------|----------|------|
+| 95-100 | 우수 | 출판 준비 완료 |
+| 85-94 | 양호 | 사소한 문제, 대부분의 용도에 허용 가능 |
+| 75-84 | 보통 | 눈에 띄는 문제, 검토가 필요할 수 있음 |
+| 60-74 | 미흡 | 심각한 문제, 수동 검토 필요 |
+| < 60 | 허용 불가 | 주요 문제, 재번역 고려 |
+
+## 출력 이해하기
+
+```
+✓ Translation complete
+  Quality: 92/85 (threshold met)
+  Breakdown:
+    - Accuracy: 38/40
+    - Fluency: 24/25
+    - Glossary: 18/20
+    - Format: 12/15
+  Iterations: 2
+```
+
+### 세부 분석
+
+- **정확성 (38/40)**: 번역이 의미적으로 정확함
+- **유창성 (24/25)**: 대상 언어로 자연스럽게 읽힘
+- **용어집 (18/20)**: 대부분의 용어가 적용됨, 일부 변형 있음
+- **형식 (12/15)**: 사소한 형식 조정 필요
+
+## 품질 조정
+
+### 더 높은 품질을 위해

package/docs/ko/guide/vitepress-integration.md

@@ -0,0 +1,265 @@
+# VitePress 통합
+
+::: info 번역
+모든 비영어 문서는 Claude Sonnet 4를 사용하여 자동으로 번역됩니다.
+:::
+
+llm-translate는 번역된 문서 구조를 기반으로 VitePress i18n 구성을 자동으로 생성하는 헬퍼 함수를 제공합니다.
+
+## 개요
+
+`llm-translate dir` 로 문서를 번역한 후, 내장된 VitePress 헬퍼를 사용하여 각 로케일에 대한 네비게이션 및 사이드바 구성을 자동 생성할 수 있습니다.
+
+## 설치
+
+```bash
+npm install @llm-translate/cli
+```
+
+## 기본 사용법
+
+```typescript
+// docs/.vitepress/config.ts
+import { defineConfig } from 'vitepress';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { generateLocaleConfig } from '@llm-translate/cli';
+
+// Get docs directory path relative to this config file
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const docsDir = resolve(__dirname, '..');
+
+const locales = generateLocaleConfig(docsDir, {
+  defaultLocale: 'en',
+  locales: ['ko', 'ja'],
+});
+
+export default defineConfig({
+  title: 'My Project',
+  locales,
+});
+```
+
+::: tip 절대 경로를 사용하는 이유는?
+VitePress 구성은 프로젝트 루트에서 실행되므로 `'./docs'` 와 같은 상대 경로는 올바르게 해석되지 않을 수 있습니다.`import.meta.url` 를 사용하면 구성 파일 위치를 기준으로 경로가 계산됩니다.
+:::
+
+이는 다음과 같은 작업을 수행합니다:
+1. `./docs` 디렉토리 구조를 스캔합니다
+2. 사이드바 디렉토리(guide, api, cli 등)를 자동 감지합니다
+3. 각 로케일에 대한 nav 및 사이드바를 생성합니다
+4. UI 요소에 대한 기본 번역을 적용합니다
+
+## 구성 옵션
+
+```typescript
+interface GenerateOptions {
+  /** Default locale code (e.g., 'en') - defaults to 'en' */
+  defaultLocale?: string;
+
+  /** List of locale codes to generate (auto-detected if omitted) */
+  locales?: string[];
+
+  /** Locale display labels */
+  labels?: Record<string, string>;
+
+  /** Locale lang codes for HTML */
+  langCodes?: Record<string, string>;
+
+  /** Locale descriptions */
+  descriptions?: Record<string, string>;
+
+  /** Directories to include in sidebar (auto-detected if omitted) */
+  sidebarDirs?: string[];
+
+  /** Use title from file's first heading (default: true) */
+  useTitleFromHeading?: boolean;
+
+  /** Custom locale translations */
+  translations?: Record<string, LocaleTranslations>;
+}
+```
+
+## 예제
+
+### 로케일 자동 감지
+
+```typescript
+import { generateLocaleConfig, detectLocales } from '@llm-translate/cli';
+
+// Automatically detect locales from directory structure
+// (looks for 2-letter directories like 'ko', 'ja', 'zh')
+const locales = generateLocaleConfig('./docs');
+```
+
+### 사용자 정의 레이블 및 설명
+
+```typescript
+const locales = generateLocaleConfig('./docs', {
+  defaultLocale: 'en',
+  locales: ['ko', 'ja'],
+  labels: {
+    en: 'English',
+    ko: '한국어',
+    ja: '日本語',
+  },
+  descriptions: {
+    en: 'Documentation for My Project',
+    ko: 'My Project 문서',
+    ja: 'My Projectのドキュメント',
+  },
+});
+```
+
+### 사이드바 디렉토리 지정
+
+```typescript
+const locales = generateLocaleConfig('./docs', {
+  sidebarDirs: ['guide', 'api', 'examples'],
+});
+```
+
+### 사용자 정의 번역
+
+```typescript
+const locales = generateLocaleConfig('./docs', {
+  translations: {
+    ko: {
+      editLinkText: 'GitHub에서 편집',
+      docFooter: { prev: '이전', next: '다음' },
+      outline: { label: '목차' },
+    },
+  },
+});
+```
+
+## 사이드바 전용 생성
+
+nav는 수동으로 구성하고 사이드바만 자동 생성하려는 경우:
+
+```typescript
+import { defineConfig } from 'vitepress';
+import { generateSidebarConfig } from '@llm-translate/cli';
+
+const sidebars = generateSidebarConfig('./docs', {
+  defaultLocale: 'en',
+  locales: ['ko'],
+});
+
+export default defineConfig({
+  locales: {
+    root: {
+      label: 'English',
+      themeConfig: {
+        nav: [/* custom nav */],
+        sidebar: sidebars.root,
+      },
+    },
+    ko: {
+      label: '한국어',
+      themeConfig: {
+        nav: [/* custom nav */],
+        sidebar: sidebars.ko,
+      },
+    },
+  },
+});
+```
+
+## 단일 로케일 생성
+
+단일 로케일에 대한 구성 생성:
+
+```typescript
+import { generateLocale } from '@llm-translate/cli';
+
+const koConfig = generateLocale('./docs', 'ko', {
+  defaultLocale: 'en',
+});
+
+// Use in your config
+export default defineConfig({
+  locales: {
+    ko: koConfig,
+  },
+});
+```
+
+## 유틸리티 함수
+
+### detectLocales
+
+로케일 디렉토리를 스캔하여 사용 가능한 로케일을 자동 감지합니다:
+
+```typescript
+import { detectLocales } from '@llm-translate/cli';
+
+const locales = detectLocales('./docs', 'en');
+// Returns: ['ko', 'ja', 'zh'] (based on directories found)
+```
+
+### detectSidebarDirs
+
+사이드바에 표시되어야 하는 디렉토리를 자동 감지합니다:
+
+```typescript
+import { detectSidebarDirs } from '@llm-translate/cli';
+
+const dirs = detectSidebarDirs('./docs');
+// Returns: ['guide', 'api', 'cli'] (excludes locale dirs, assets, etc.)
+```
+
+## 제목 추출
+
+헬퍼는 다음 순서로 페이지 제목을 추출합니다:
+1. Frontmatter `title` 필드
+2. 파일의 첫 번째 `#` 헤딩
+3. Title Case로 변환된 파일명
+
+Frontmatter 예제:
+```yaml
+---
+title: Getting Started
+---
+```
+
+## 기본 번역
+
+일반적인 로케일에 대한 내장 번역이 제공됩니다:
+
+| 로케일 | 레이블 | 문서 푸터 | 목차 |
+|--------|-------|------------|---------|
+| ko | 한국어 | 이전/다음 페이지 | 목차 |
+| ja | 日本語 | 前/次のページ | 目次 |
+| zh | 中文 | 上/下一页 | 目录 |
+
+## 워크플로우
+
+다국어 문서화를 위한 일반적인 워크플로우:
+
+```bash
+# 1. Write documentation in English
+docs/
+  guide/
+    getting-started.md
+    configuration.md
+  api/
+    index.md
+
+# 2. Translate to Korean
+llm-translate dir ./docs ./docs/ko --target-lang ko --glossary glossary.json
+
+# 3. Update VitePress config to use auto-generation
+# (see examples above)
+
+# 4. Build and preview
+npm run docs:build
+npm run docs:preview
+```
+
+## 주의사항
+
+- **절대 경로 사용**: 기본 사용법에서 보여준 것처럼 항상 `import.meta.url` 를 사용하여 docs 디렉토리 경로를 해석하십시오. VitePress가 프로젝트 루트에서 실행되므로 상대 경로는 올바르게 작동하지 않을 수 있습니다.
+- 로케일 디렉토리는 2글자 코드를 사용해야 합니다(예:`ko `,` ja `,` zh`)
+- 헬퍼는 번역된 문서가 소스 구조를 미러링한다고 가정합니다
+- 사용자 정의 nav 항목(외부 링크, 드롭다운)은 수동 구성이 필요합니다

package/docs/ko/index.md

@@ -0,0 +1,58 @@
+---
+layout: home
+
+hero:
+  name: llm-translate
+  text: LLM 기반 문서 번역
+  tagline: 용어집 적용, 품질 관리, 비용 최적화를 통한 문서 번역
+  actions:
+    - theme: brand
+      text: 시작하기
+      link: ./guide/getting-started
+    - theme: alt
+      text: GitHub에서 보기
+      link: https://github.com/selenehyun/llm-translate
+
+features:
+  - icon: 📚
+    title: 용어집 적용
+    details: 잘못 번역되지 않는 강제 용어집 용어를 통해 번역 전반에 걸쳐 일관된 용어를 보장합니다.
+  - icon: 🔄
+    title: Self-Refine 품질 관리
+    details: AI 기반 품질 평가를 사용한 반복적 번역 개선으로 품질 임계값을 충족합니다.
+  - icon: 💰
+    title: 비용 최적화
+    details: 프롬프트 캐싱으로 용어집 및 시스템 프롬프트와 같은 반복 콘텐츠에 대한 API 비용을 최대 90%까지 절감합니다.
+  - icon: 🔌
+    title: 다중 제공자 지원
+    details: Claude, OpenAI, Ollama와 함께 작동합니다. 워크플로우를 변경하지 않고도 제공자를 전환할 수 있습니다.
+  - icon: 📄
+    title: 형식 보존
+    details: 번역 중에 Markdown 형식, 코드 블록, 링크 및 문서 구조를 유지합니다.
+  - icon: ⚡
+    title: 일괄 처리
+    details: 병렬 처리 및 진행률 추적으로 전체 디렉토리를 번역합니다.
+---
+
+## 빠른 시작
+
+```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
+```
+
+## 왜 llm-translate인가요?
+
+기존 번역 도구는 기술 문서에서 어려움을 겪습니다:
+
+- **일관성 없는 용어** - "API endpoint"가 매번 다르게 번역됨
+- **깨진 형식** - 코드 블록과 Markdown이 손상됨
+- **품질 관리 없음** - LLM이 출력하는 것을 그대로 수용
+
+llm-translate는 다음과 같이 이러한 문제를 해결합니다: