@llm-translate/cli 1.0.0-next.1

package/docs/api/providers.md

@@ -0,0 +1,304 @@
+# Providers
+
+::: info Translations
+All non-English documentation is automatically translated using Claude Sonnet 4.
+:::
+
+LLM provider implementations for different AI services.
+
+## Overview
+
+All providers implement the `LLMProvider` interface:
+
+```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 Provider
+
+The recommended provider, with full support for prompt caching.
+
+### Setup
+
+```typescript
+import { createClaudeProvider } from '@llm-translate/cli';
+
+const provider = createClaudeProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  defaultModel: 'claude-haiku-4-5-20251001',
+});
+```
+
+### Configuration
+
+```typescript
+interface ClaudeProviderConfig {
+  apiKey?: string;          // Defaults to ANTHROPIC_API_KEY env
+  baseUrl?: string;         // Custom API endpoint
+  defaultModel?: string;    // Default: claude-haiku-4-5-20251001
+}
+```
+
+### Available Models
+
+| Model | Context | Input Cost | Output Cost |
+|-------|---------|------------|-------------|
+| `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 |
+
+### Prompt Caching
+
+Claude provider supports prompt caching automatically:
+
+```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 Provider
+
+### Setup
+
+```typescript
+import { createOpenAIProvider } from '@llm-translate/cli';
+
+const provider = createOpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY,
+  defaultModel: 'gpt-4o-mini',
+});
+```
+
+### Configuration
+
+```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
+}
+```
+
+### Available Models
+
+| Model | Context | Input Cost | Output Cost |
+|-------|---------|------------|-------------|
+| `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 |
+
+### Automatic Caching
+
+OpenAI handles caching automatically for prompts > 1024 tokens.
+
+## Ollama Provider
+
+For local, self-hosted models.
+
+### Setup
+
+```typescript
+import { createOllamaProvider } from '@llm-translate/cli';
+
+const provider = createOllamaProvider({
+  baseUrl: 'http://localhost:11434',
+  defaultModel: 'llama3.1',
+});
+```
+
+### Configuration
+
+```typescript
+interface OllamaProviderConfig {
+  baseUrl?: string;         // Default: http://localhost:11434
+  defaultModel?: string;    // Default: llama3.1
+}
+```
+
+### Available Models
+
+Any model available in your Ollama installation:
+
+```bash
+# List available models
+ollama list
+
+# Pull a model
+ollama pull llama3.1
+ollama pull mistral
+ollama pull codellama
+```
+
+### Limitations
+
+- No prompt caching support
+- Quality varies by model
+- Limited context window (model-dependent)
+
+## Provider Interface
+
+### 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;
+}
+```
+
+## Custom Provider
+
+Implement your own provider:
+
+```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,
+    };
+  }
+}
+```
+
+## Provider Selection Guide
+
+| Use Case | Recommended Provider | Model |
+|----------|---------------------|-------|
+| Cost-effective | Claude | Haiku 4.5 |
+| High quality | Claude | Sonnet 4.5 |
+| OpenAI ecosystem | OpenAI | GPT-4o |
+| Budget constrained | OpenAI | GPT-4o-mini |
+| Privacy/offline | Ollama | Llama 3.1 |
+| Enterprise | Claude/OpenAI | Varies |
+
+## Error Handling
+
+All providers throw `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/changelog.md

@@ -0,0 +1,64 @@
+# Changelog
+
+::: info Translations
+All non-English documentation is automatically translated using Claude Sonnet 4.
+:::
+
+All notable changes to llm-translate will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Prompt caching support for Claude models (40-50% cost reduction)
+- Cache token usage tracking in translation results
+- `enableCaching` option in TranslationAgent
+- `cacheRead` and `cacheWrite` fields in token usage metadata
+- MQM (Multidimensional Quality Metrics) based quality evaluation system
+- MAPS-style pre-translation analysis step
+- Translation mode support (`--mode fast|balanced|quality`)
+
+### Changed
+
+- `ChatMessage.content` now supports cacheable text parts
+- `ChatResponse.usage` includes cache token metrics
+- Default model updated to `claude-haiku-4-5-20251001`
+
+### Documentation
+
+- Added Ollama quality warning: 14B+ models required for reliable translation
+
+## [0.1.0] - 2025-12-12
+
+### Added
+
+- Initial release
+- Single file translation (`llm-translate file`)
+- Directory batch translation (`llm-translate dir`)
+- Configuration initialization (`llm-translate init`)
+- Glossary management (`llm-translate glossary`)
+- Claude, OpenAI, and Ollama provider support
+- Self-Refine quality control loop
+- Markdown AST-based chunking
+- Glossary enforcement
+- Quality threshold configuration
+- Verbose output mode
+
+### Providers
+
+- Claude (claude-haiku-4-5, claude-sonnet-4-5, claude-opus-4-5)
+- OpenAI (gpt-4o-mini, gpt-4o, gpt-4-turbo)
+- Ollama (any local model)
+
+### Documentation
+
+- CLI reference documentation
+- API reference documentation
+- Getting started guide
+- Configuration guide
+- Glossary guide
+- Quality control guide
+- Cost optimization guide

package/docs/cli/dir.md

@@ -0,0 +1,243 @@
+# llm-translate dir
+
+::: info Translations
+All non-English documentation is automatically translated using Claude Sonnet 4.
+:::
+
+Translate all files in a directory.
+
+## Synopsis
+
+```bash
+llm-translate dir <input> <output> [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `<input>` | Input directory path (required) |
+| `<output>` | Output directory path (required) |
+
+## Options
+
+### Language Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-s, --source-lang <lang>` | config default | Source language code |
+| `-t, --target-lang <lang>` | required | Target language code |
+
+### Translation Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-g, --glossary <path>` | none | Path to glossary file |
+| `-p, --provider <name>` | `claude` | LLM provider (claude\|openai\|ollama) |
+| `-m, --model <name>` | provider default | Model name |
+| `--context <text>` | none | Additional context for translation |
+
+### Quality Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--quality <0-100>` | 85 | Quality threshold |
+| `--max-iterations <n>` | 4 | Maximum refinement iterations |
+
+### File Selection
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--include <patterns>` | `*.md,*.markdown` | File patterns to include (comma-separated) |
+| `--exclude <patterns>` | none | File patterns to exclude (comma-separated) |
+
+### Processing Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--parallel <n>` | 3 | Parallel file processing |
+| `--chunk-size <tokens>` | 1024 | Max tokens per chunk |
+| `--no-cache` | false | Disable translation cache |
+
+### Output Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-f, --format <fmt>` | auto | Force output format (md\|html\|txt) |
+| `--dry-run` | false | Show what would be translated |
+| `--json` | false | Output results as JSON |
+| `-v, --verbose` | false | Enable verbose logging |
+| `-q, --quiet` | false | Suppress non-error output |
+
+## Examples
+
+### Basic Usage
+
+```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
+```
+
+### File Selection
+
+```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/**"
+```
+
+### Parallel Processing
+
+```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
+```
+
+### Quality Settings
+
+```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
+```
+
+### Preview Mode
+
+```bash
+# Show what would be translated
+llm-translate dir ./docs ./docs-ko -s en -t ko --dry-run
+```
+
+Output:
+```
+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)
+```
+
+## Output Structure
+
+Directory structure is preserved by default:
+
+```
+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
+```
+
+## Progress Reporting
+
+### Normal Mode
+
+```
+ℹ 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 Output
+
+```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": [...]
+}
+```
+
+## Best Practices
+
+### 1. Preview First
+
+```bash
+llm-translate dir ./docs ./docs-ko -s en -t ko --dry-run
+```
+
+### 2. Use Appropriate Parallelism
+
+- Rate-limited APIs: `--parallel 1-2`
+- High limits: `--parallel 5-10`
+- Local (Ollama): `--parallel 1` (model limited)
+
+### 3. Handle Large Projects
+
+```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. Leverage Caching
+
+Cache allows skipping unchanged content:
+
+```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. Quality by Content Type
+
+```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
+```