@llm-translate/cli 1.0.0-next.1

package/docs/guide/providers.md

@@ -0,0 +1,232 @@
+# Providers
+
+::: info Translations
+All non-English documentation is automatically translated using Claude Sonnet 4.
+:::
+
+llm-translate supports multiple LLM providers. Each has different strengths and trade-offs.
+
+## Supported Providers
+
+| Provider | Caching | Best For | Setup Complexity |
+|----------|---------|----------|------------------|
+| Claude | Full | Quality + Cost | Easy |
+| OpenAI | Automatic | Ecosystem | Easy |
+| Ollama | None | Privacy/Offline | Medium |
+
+## Claude (Recommended)
+
+### Why Claude?
+
+- **Prompt caching**: Up to 90% cost reduction
+- **High quality**: Excellent translation accuracy
+- **Long context**: 200K token context window
+- **Multiple tiers**: Haiku (fast), Sonnet (balanced), Opus (best)
+
+### Setup
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-xxxxx
+```
+
+### Model Selection
+
+```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
+```
+
+### When to Use Each Model
+
+| Model | Use Case |
+|-------|----------|
+| Haiku | README files, simple docs, high volume |
+| Sonnet | Technical documentation, API references |
+| Opus | Legal, marketing, nuanced content |
+
+## OpenAI
+
+### Setup
+
+```bash
+export OPENAI_API_KEY=sk-xxxxx
+```
+
+### Usage
+
+```bash
+llm-translate file doc.md --target ko --provider openai --model gpt-4o
+```
+
+### Available Models
+
+| Model | Speed | Quality | Cost |
+|-------|-------|---------|------|
+| gpt-4o-mini | Fast | Good | Very Low |
+| gpt-4o | Medium | Excellent | Medium |
+| gpt-4-turbo | Medium | Excellent | High |
+
+### When to Use
+
+- Already using OpenAI for other services
+- Need specific OpenAI features
+- Prefer Azure OpenAI (set custom baseUrl)
+
+## Ollama
+
+Local, self-hosted LLMs for privacy or offline use. No API keys required.
+
+::: warning Quality Varies by Model
+Ollama translation quality is **highly dependent on model selection**. For reliable translation results:
+
+- **Minimum**: 14B+ parameter models (e.g., `qwen2.5:14b`, `llama3.1:14b`)
+- **Recommended**: 32B+ models (e.g., `qwen2.5:32b`, `llama3.3:70b`)
+- **Not recommended**: Models under 7B produce inconsistent and often unusable translations
+
+Smaller models (3B, 7B) may work for simple content but frequently fail on technical documentation, produce incomplete outputs, or ignore formatting instructions.
+:::
+
+### Quick Setup
+
+```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
+```
+
+### Recommended Models
+
+| Model | RAM | Quality | Best For |
+|-------|-----|---------|----------|
+| `qwen2.5:14b` | 16GB | Very Good | **Best balance (recommended)** |
+| `qwen2.5:32b` | 32GB | Excellent | Higher quality |
+| `llama3.1:8b` | 8GB | Good | Lighter weight |
+| `llama3.2` | 4GB | Fair | Simple content only |
+
+### When to Use
+
+- Sensitive/private documents
+- Offline environments
+- Cost optimization (no API fees)
+- Simple to moderate complexity content
+
+::: tip Full Guide
+See [Local Translation with Ollama](./ollama) for complete setup instructions, GPU optimization, troubleshooting, and advanced configuration.
+:::
+
+## Provider Comparison
+
+### Quality
+
+```
+Opus > Sonnet ≈ GPT-4o > Haiku ≈ GPT-4o-mini > Qwen2.5:32b > Qwen2.5:14b
+```
+
+### Cost (per 1M tokens)
+
+```
+Ollama ($0) < GPT-4o-mini ($0.15) < Haiku ($1) < GPT-4o ($2.5) < Sonnet ($3) < Opus ($15)
+```
+
+### Speed
+
+```
+Haiku ≈ GPT-4o-mini > Sonnet ≈ GPT-4o > Opus > Ollama (varies with hardware)
+```
+
+## Switching Providers
+
+### 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
+```
+
+### Config File
+
+```json
+{
+  "provider": {
+    "name": "openai",
+    "model": "gpt-4o"
+  }
+}
+```
+
+### Programmatic
+
+```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],
+});
+```
+
+## Fallback Configuration
+
+Configure fallback providers for reliability:
+
+```json
+{
+  "provider": {
+    "name": "claude",
+    "model": "claude-haiku-4-5-20251001",
+    "fallback": [
+      { "name": "openai", "model": "gpt-4o-mini" },
+      { "name": "ollama", "model": "llama3.1" }
+    ]
+  }
+}
+```
+
+## Custom Endpoints
+
+### Azure OpenAI
+
+```json
+{
+  "provider": {
+    "name": "openai",
+    "baseUrl": "https://your-resource.openai.azure.com",
+    "apiKey": "your-azure-key"
+  }
+}
+```
+
+### Self-Hosted
+
+```json
+{
+  "provider": {
+    "name": "ollama",
+    "baseUrl": "https://your-server.com:11434"
+  }
+}
+```

package/docs/guide/quality-control.md

@@ -0,0 +1,206 @@
+# Quality Control
+
+::: info Translations
+All non-English documentation is automatically translated using Claude Sonnet 4.
+:::
+
+llm-translate uses a Self-Refine algorithm to ensure translation quality meets your requirements.
+
+## How Self-Refine Works
+
+```
+┌─────────────────┐
+│ Initial Translate│
+└────────┬────────┘
+         ▼
+┌─────────────────┐
+│ Evaluate Quality │◀──────────────┐
+└────────┬────────┘               │
+         ▼                        │
+    Score >= Threshold?           │
+         │                        │
+    No   │   Yes                  │
+         │    │                   │
+         ▼    ▼                   │
+┌─────────┐ ┌──────┐              │
+│ Reflect │ │ Done │              │
+└────┬────┘ └──────┘              │
+     ▼                            │
+┌─────────────────┐               │
+│    Improve      │───────────────┘
+└─────────────────┘
+```
+
+### 1. Initial Translation
+
+The first translation is generated with:
+- Full glossary context
+- Document structure information
+- Previous chunk context (for continuity)
+
+### 2. Quality Evaluation
+
+Each translation is scored on four criteria:
+
+| Criterion | Weight | Description |
+|-----------|--------|-------------|
+| Semantic Accuracy | 40% | Does it convey the correct meaning? |
+| Fluency | 25% | Does it read naturally in target language? |
+| Glossary Compliance | 20% | Are all glossary terms applied correctly? |
+| Format Preservation | 15% | Is markdown/HTML structure maintained? |
+
+### 3. Reflection
+
+If quality is below threshold, the LLM analyzes:
+- What specific issues exist
+- Which glossary terms were missed
+- Where fluency can be improved
+
+### 4. Improvement
+
+Targeted fixes are applied based on reflection feedback, then the cycle repeats.
+
+## Configuration
+
+### Quality Threshold
+
+```bash
+# CLI
+llm-translate file doc.md -o doc.ko.md -s en -t ko --quality 90
+
+# Config file
+{
+  "translation": {
+    "qualityThreshold": 90
+  }
+}
+```
+
+### Maximum Iterations
+
+```bash
+# CLI
+llm-translate file doc.md -o doc.ko.md -s en -t ko --max-iterations 6
+
+# Config file
+{
+  "translation": {
+    "maxIterations": 6
+  }
+}
+```
+
+### Strict Mode
+
+Fail if quality threshold is not met:
+
+```bash
+llm-translate file doc.md -o doc.ko.md -s en -t ko --strict-quality
+```
+
+Exit codes:
+- `0` - Success
+- `4` - Quality threshold not met (strict mode)
+
+## Quality Score Interpretation
+
+| Score | Quality Level | Description |
+|-------|--------------|-------------|
+| 95-100 | Excellent | Publication-ready |
+| 85-94 | Good | Minor issues, acceptable for most uses |
+| 75-84 | Fair | Noticeable issues, may need review |
+| 60-74 | Poor | Significant issues, needs manual review |
+| < 60 | Unacceptable | Major problems, consider re-translation |
+
+## Understanding the Output
+
+```
+✓ Translation complete
+  Quality: 92/85 (threshold met)
+  Breakdown:
+    - Accuracy: 38/40
+    - Fluency: 24/25
+    - Glossary: 18/20
+    - Format: 12/15
+  Iterations: 2
+```
+
+### Breakdown Analysis
+
+- **Accuracy (38/40)**: Translation is semantically correct
+- **Fluency (24/25)**: Reads naturally in target language
+- **Glossary (18/20)**: Most terms applied, some variations
+- **Format (12/15)**: Minor formatting adjustments needed
+
+## Tuning Quality
+
+### For Higher Quality
+
+1. **Increase threshold**: `--quality 95`
+2. **Allow more iterations**: `--max-iterations 6`
+3. **Use better model**: `--model claude-sonnet-4-5-20250929`
+4. **Provide more context**: Add document purpose in config
+
+### For Faster Processing
+
+1. **Lower threshold**: `--quality 75`
+2. **Reduce iterations**: `--max-iterations 2`
+3. **Use faster model**: `--model claude-haiku-4-5-20251001`
+
+### Cost vs Quality Trade-offs
+
+| Setting | Cost | Time | Quality |
+|---------|------|------|---------|
+| threshold=70, iterations=2 | Low | Fast | Draft |
+| threshold=85, iterations=4 | Medium | Moderate | Standard |
+| threshold=95, iterations=6 | High | Slow | Premium |
+
+## Quality Issues and Fixes
+
+### Low Accuracy Score
+
+**Causes:**
+- Ambiguous source text
+- Missing context
+- Complex technical content
+
+**Fixes:**
+- Add context to glossary terms
+- Use a more capable model
+- Break complex sentences into simpler ones
+
+### Low Fluency Score
+
+**Causes:**
+- Literal translation
+- Unnatural phrasing
+- Wrong register (formal/informal)
+
+**Fixes:**
+- Increase max iterations
+- Use native-quality model (Sonnet/GPT-4)
+- Review source text for clarity
+
+### Low Glossary Compliance
+
+**Causes:**
+- Terms not in glossary
+- Case sensitivity mismatch
+- Term appears in different form
+
+**Fixes:**
+- Add missing terms to glossary
+- Check `caseSensitive` setting
+- Add term variations
+
+### Low Format Score
+
+**Causes:**
+- Complex nested structures
+- Code blocks with comments
+- Tables with formatting
+
+**Fixes:**
+- Ensure chunking respects structure
+- Review markdown source
+- Consider pre-processing complex content

package/docs/guide/vitepress-integration.md

@@ -0,0 +1,265 @@
+# VitePress Integration
+
+::: info Translations
+All non-English documentation is automatically translated using Claude Sonnet 4.
+:::
+
+llm-translate provides helper functions to automatically generate VitePress i18n configuration based on your translated document structure.
+
+## Overview
+
+After translating your documentation with `llm-translate dir`, you can use the built-in VitePress helpers to auto-generate navigation and sidebar configuration for each locale.
+
+## Installation
+
+```bash
+npm install @llm-translate/cli
+```
+
+## Basic Usage
+
+```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 Why use absolute paths?
+VitePress config runs from the project root, so relative paths like `'./docs'` may not resolve correctly. Using `import.meta.url` ensures the path is calculated relative to the config file location.
+:::
+
+This will:
+1. Scan your `./docs` directory structure
+2. Auto-detect sidebar directories (guide, api, cli, etc.)
+3. Generate nav and sidebar for each locale
+4. Apply default translations for UI elements
+
+## Configuration Options
+
+```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>;
+}
+```
+
+## Examples
+
+### Auto-detect Locales
+
+```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');
+```
+
+### Custom Labels and Descriptions
+
+```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のドキュメント',
+  },
+});
+```
+
+### Specify Sidebar Directories
+
+```typescript
+const locales = generateLocaleConfig('./docs', {
+  sidebarDirs: ['guide', 'api', 'examples'],
+});
+```
+
+### Custom Translations
+
+```typescript
+const locales = generateLocaleConfig('./docs', {
+  translations: {
+    ko: {
+      editLinkText: 'GitHub에서 편집',
+      docFooter: { prev: '이전', next: '다음' },
+      outline: { label: '목차' },
+    },
+  },
+});
+```
+
+## Sidebar-Only Generation
+
+If you want to manually configure nav but auto-generate sidebar:
+
+```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,
+      },
+    },
+  },
+});
+```
+
+## Single Locale Generation
+
+Generate config for a single locale:
+
+```typescript
+import { generateLocale } from '@llm-translate/cli';
+
+const koConfig = generateLocale('./docs', 'ko', {
+  defaultLocale: 'en',
+});
+
+// Use in your config
+export default defineConfig({
+  locales: {
+    ko: koConfig,
+  },
+});
+```
+
+## Utility Functions
+
+### detectLocales
+
+Auto-detect available locales by scanning for locale directories:
+
+```typescript
+import { detectLocales } from '@llm-translate/cli';
+
+const locales = detectLocales('./docs', 'en');
+// Returns: ['ko', 'ja', 'zh'] (based on directories found)
+```
+
+### detectSidebarDirs
+
+Auto-detect directories that should appear in the sidebar:
+
+```typescript
+import { detectSidebarDirs } from '@llm-translate/cli';
+
+const dirs = detectSidebarDirs('./docs');
+// Returns: ['guide', 'api', 'cli'] (excludes locale dirs, assets, etc.)
+```
+
+## Title Extraction
+
+The helper extracts page titles in this order:
+1. Frontmatter `title` field
+2. First `#` heading in the file
+3. File name converted to Title Case
+
+Example frontmatter:
+```yaml
+---
+title: Getting Started
+---
+```
+
+## Default Translations
+
+Built-in translations are provided for common locales:
+
+| Locale | Label | Doc Footer | Outline |
+|--------|-------|------------|---------|
+| ko | 한국어 | 이전/다음 페이지 | 목차 |
+| ja | 日本語 | 前/次のページ | 目次 |
+| zh | 中文 | 上/下一页 | 目录 |
+
+## Workflow
+
+Typical workflow for multilingual documentation:
+
+```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
+```
+
+## Caveats
+
+- **Use absolute paths**: Always resolve the docs directory path using `import.meta.url` as shown in Basic Usage. Relative paths may not work correctly since VitePress runs from the project root.
+- Locale directories must use 2-letter codes (e.g., `ko`, `ja`, `zh`)
+- The helper assumes translated docs mirror the source structure
+- Custom nav items (external links, dropdowns) need manual configuration