@llm-translate/cli 1.0.0-next.1

package/docs/cli/file.md

@@ -0,0 +1,213 @@
+# llm-translate file
+
+::: info Translations
+All non-English documentation is automatically translated using Claude Sonnet 4.
+:::
+
+Translate a single file.
+
+## Synopsis
+
+```bash
+llm-translate file <input> [output] [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `<input>` | Input file path (required) |
+| `[output]` | Output file path (optional, defaults to stdout) |
+
+## Options
+
+### Translation Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--source-lang`, `-s` | required | Source language code |
+| `--target-lang`, `-t` | required | Target language code |
+| `--glossary`, `-g` | none | Path to glossary file |
+
+### Quality Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--quality` | 85 | Quality threshold (0-100) |
+| `--max-iterations` | 4 | Maximum refinement iterations |
+| `--strict-quality` | false | Fail if threshold not met |
+| `--strict-glossary` | false | Fail if glossary terms not applied |
+
+### Provider Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--provider`, `-p` | claude | Provider name |
+| `--model`, `-m` | varies | Model identifier |
+
+### Output Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--output`, `-o` | auto | Output file path |
+| `--format`, `-f` | auto | Force output format (md\|html\|txt) |
+| `--dry-run` | false | Show what would be done |
+| `--json` | false | Output results as JSON |
+| `--verbose`, `-v` | false | Enable verbose logging |
+| `--quiet`, `-q` | false | Suppress non-error output |
+
+### Advanced Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--no-cache` | false | Disable translation cache |
+| `--chunk-size` | 1024 | Max tokens per chunk |
+| `--context` | none | Additional context for translation |
+
+## Examples
+
+### Basic Usage
+
+```bash
+# Translate to Korean
+llm-translate file README.md -o README.ko.md -s en -t ko
+
+# With explicit output path
+llm-translate file README.md --output README.ko.md --source-lang en --target-lang ko
+
+# Specify source and target languages
+llm-translate file doc.md -o doc.ja.md --source-lang en --target-lang ja
+```
+
+### With Glossary
+
+```bash
+# Use glossary for consistent terminology
+llm-translate file api-docs.md -o api-docs.ko.md \
+  -s en -t ko \
+  --glossary glossary.json
+```
+
+### Quality Control
+
+```bash
+# Higher quality threshold
+llm-translate file important.md -o important.ko.md \
+  -s en -t ko \
+  --quality 95 \
+  --max-iterations 6
+
+# Strict mode (fail if not met)
+llm-translate file legal.md -o legal.ko.md \
+  --source-lang en \
+  --target-lang ko \
+  --quality 95 \
+  --strict-quality
+```
+
+### Provider Selection
+
+```bash
+# Use Claude Sonnet
+llm-translate file doc.md -o doc.ko.md \
+  -s en -t ko \
+  --provider claude \
+  --model claude-sonnet-4-5-20250929
+
+# Use OpenAI
+llm-translate file doc.md -o doc.ko.md \
+  -s en -t ko \
+  --provider openai \
+  --model gpt-4o
+```
+
+### From stdin
+
+```bash
+# Pipe content (uses stdin mode when no TTY)
+cat doc.md | llm-translate -s en -t ko > doc.ko.md
+
+# Use with other tools
+curl https://example.com/doc.md | llm-translate -s en -t ko
+```
+
+## Output Format
+
+### Normal Mode
+
+```
+✓ Translated README.md → README.ko.md
+  Quality: 92/85 (threshold met)
+  Duration: 3.2s
+```
+
+### Verbose Mode
+
+```bash
+llm-translate file doc.md -o doc.ko.md --target ko --verbose
+```
+
+```
+ℹ Loading configuration...
+ℹ Provider: claude (claude-haiku-4-5-20251001)
+ℹ Parsing document...
+ℹ Chunks: 5
+ℹ Starting translation...
+
+[Chunk 1/5] Starting initial translation...
+[Chunk 1/5] Quality: 78/85
+[Chunk 1/5] Generating improvements...
+[Chunk 1/5] Quality: 91/85 ✓
+
+[Chunk 2/5] Starting initial translation...
+[Chunk 2/5] Quality: 88/85 ✓
+...
+
+✓ Translation complete
+  Quality: 89/85 (threshold met)
+  Iterations: avg 1.8
+  Tokens: 5,234 input / 6,456 output
+  Cache: 3,200 read / 800 written
+  Duration: 8.4s
+```
+
+## Language Codes
+
+Common language codes:
+
+| Code | Language |
+|------|----------|
+| `en` | English |
+| `ko` | Korean |
+| `ja` | Japanese |
+| `zh` | Chinese (Simplified) |
+| `zh-TW` | Chinese (Traditional) |
+| `es` | Spanish |
+| `fr` | French |
+| `de` | German |
+
+## Error Handling
+
+### File Not Found
+
+```bash
+$ llm-translate file missing.md -s en -t ko
+Error: Could not read file 'missing.md'
+Exit code: 3
+```
+
+### Quality Not Met (Strict Mode)
+
+```bash
+$ llm-translate file doc.md -o doc.ko.md -s en -t ko --quality 99 --strict-quality
+Error: Quality threshold not met: 94/99
+Exit code: 4
+```
+
+### API Error
+
+```bash
+$ llm-translate file doc.md --target ko
+Error: Provider error: Rate limit exceeded
+Exit code: 5
+```

package/docs/cli/glossary.md

@@ -0,0 +1,273 @@
+# llm-translate glossary
+
+::: info Translations
+All non-English documentation is automatically translated using Claude Sonnet 4.
+:::
+
+Manage glossary files for consistent terminology.
+
+## Synopsis
+
+```bash
+llm-translate glossary <subcommand> [options]
+```
+
+## Subcommands
+
+### list
+
+List all terms in a glossary.
+
+```bash
+llm-translate glossary list --glossary glossary.json
+```
+
+Options:
+| Option | Description |
+|--------|-------------|
+| `--glossary`, `-g` | Path to glossary file (required) |
+| `--target`, `-t` | Filter by target language |
+| `--format` | Output format: `table`, `json` |
+
+Examples:
+
+```bash
+# List all terms
+llm-translate glossary list -g glossary.json
+
+# Filter by target language
+llm-translate glossary list -g glossary.json --target ko
+
+# JSON output
+llm-translate glossary list -g glossary.json --format json
+```
+
+Output:
+```
+Glossary: glossary.json (15 terms)
+
+Source          | Korean (ko)      | Japanese (ja)    | Flags
+----------------|------------------|------------------|-------
+component       | 컴포넌트         | コンポーネント    |
+prop            | 프롭             | プロップ          |
+state           | 상태             | ステート          |
+TypeScript      | -                | -                | DNT
+API             | -                | -                | DNT, CS
+
+DNT = Do Not Translate, CS = Case Sensitive
+```
+
+### validate
+
+Validate glossary file structure and content.
+
+```bash
+llm-translate glossary validate --glossary glossary.json
+```
+
+Options:
+| Option | Description |
+|--------|-------------|
+| `--glossary`, `-g` | Path to glossary file (required) |
+| `--strict` | Fail on warnings |
+
+Examples:
+
+```bash
+# Basic validation
+llm-translate glossary validate -g glossary.json
+
+# Strict mode
+llm-translate glossary validate -g glossary.json --strict
+```
+
+Output:
+```
+Validating glossary.json...
+
+✓ Valid JSON structure
+✓ Required fields present
+✓ 15 terms found
+
+Warnings:
+  - Term "component" has no context
+  - Term "hook" missing Japanese translation
+
+✓ Validation passed (2 warnings)
+```
+
+### add
+
+Add a new term to the glossary.
+
+```bash
+llm-translate glossary add <source> [options]
+```
+
+Options:
+| Option | Description |
+|--------|-------------|
+| `--glossary`, `-g` | Path to glossary file (required) |
+| `--target` | Target translation (format: `lang=value`) |
+| `--context` | Context for the term |
+| `--dnt` | Mark as "do not translate" |
+| `--case-sensitive` | Mark as case sensitive |
+
+Examples:
+
+```bash
+# Add with translations
+llm-translate glossary add "container" \
+  -g glossary.json \
+  --target ko="컨테이너" \
+  --target ja="コンテナ"
+
+# Add do-not-translate term
+llm-translate glossary add "Kubernetes" \
+  -g glossary.json \
+  --dnt
+
+# Add with context
+llm-translate glossary add "instance" \
+  -g glossary.json \
+  --target ko="인스턴스" \
+  --context "Cloud computing instance"
+```
+
+### remove
+
+Remove a term from the glossary.
+
+```bash
+llm-translate glossary remove <source> --glossary glossary.json
+```
+
+Examples:
+
+```bash
+llm-translate glossary remove "deprecated-term" -g glossary.json
+```
+
+### update
+
+Update an existing term.
+
+```bash
+llm-translate glossary update <source> [options]
+```
+
+Options:
+| Option | Description |
+|--------|-------------|
+| `--glossary`, `-g` | Path to glossary file (required) |
+| `--target` | Update target translation |
+| `--context` | Update context |
+| `--dnt` | Set/unset do not translate |
+
+Examples:
+
+```bash
+# Update translation
+llm-translate glossary update "component" \
+  -g glossary.json \
+  --target ko="컴포넌트 요소"
+
+# Add context
+llm-translate glossary update "state" \
+  -g glossary.json \
+  --context "React component state"
+```
+
+### stats
+
+Show glossary statistics.
+
+```bash
+llm-translate glossary stats --glossary glossary.json
+```
+
+Output:
+```
+Glossary Statistics: glossary.json
+
+Terms: 15
+  - With translations: 12
+  - Do not translate: 3
+
+Languages:
+  - Korean (ko): 12 terms
+  - Japanese (ja): 10 terms
+  - Chinese (zh): 8 terms
+
+Token estimate: ~450 tokens
+```
+
+### merge
+
+Merge multiple glossaries.
+
+```bash
+llm-translate glossary merge \
+  --input glossary-a.json \
+  --input glossary-b.json \
+  --output merged.json
+```
+
+Options:
+| Option | Description |
+|--------|-------------|
+| `--input`, `-i` | Input glossary files (multiple) |
+| `--output`, `-o` | Output merged glossary |
+| `--strategy` | Conflict resolution: `first`, `last`, `error` |
+
+### export
+
+Export glossary to different formats.
+
+```bash
+llm-translate glossary export --glossary glossary.json --format csv
+```
+
+Options:
+| Option | Description |
+|--------|-------------|
+| `--format` | Export format: `csv`, `tsv`, `xlsx` |
+| `--output`, `-o` | Output file path |
+
+## Best Practices
+
+### Organizing Large Glossaries
+
+```bash
+# Split by domain
+glossaries/
+├── common.json      # Shared terms
+├── frontend.json    # UI terminology
+├── backend.json     # Server terminology
+└── devops.json      # Infrastructure terms
+
+# Merge for use
+llm-translate glossary merge \
+  -i glossaries/common.json \
+  -i glossaries/frontend.json \
+  -o project-glossary.json
+```
+
+### Version Control
+
+Include glossary in version control:
+
+```bash
+git add glossary.json
+git commit -m "Add project glossary"
+```
+
+### Regular Maintenance
+
+```bash
+# Validate before commits
+llm-translate glossary validate -g glossary.json --strict
+
+# Review stats periodically
+llm-translate glossary stats -g glossary.json
+```

package/docs/cli/index.md

@@ -0,0 +1,129 @@
+# CLI Reference
+
+::: info Translations
+All non-English documentation is automatically translated using Claude Sonnet 4.
+:::
+
+llm-translate provides a command-line interface for translating documents.
+
+## Installation
+
+```bash
+npm install -g @llm-translate/cli
+```
+
+## Global Options
+
+These options are available for all commands:
+
+| Option | Description |
+|--------|-------------|
+| `--help`, `-h` | Show help |
+| `--version`, `-V` | Show version |
+| `--verbose`, `-v` | Enable verbose output |
+| `--quiet`, `-q` | Suppress non-essential output |
+| `--config` | Path to config file |
+
+## Commands
+
+### [file](./file)
+
+Translate a single file.
+
+```bash
+llm-translate file <input> [output] [options]
+```
+
+### [dir](./dir)
+
+Translate all files in a directory.
+
+```bash
+llm-translate dir <input> <output> [options]
+```
+
+### [init](./init)
+
+Initialize configuration file.
+
+```bash
+llm-translate init [options]
+```
+
+### [glossary](./glossary)
+
+Manage glossary files.
+
+```bash
+llm-translate glossary <subcommand> [options]
+```
+
+### [serve](./serve)
+
+Start the translation API server.
+
+```bash
+llm-translate serve [options]
+```
+
+## Quick Examples
+
+```bash
+# Translate a file to Korean
+llm-translate file README.md -o README.ko.md -s en -t ko
+
+# Translate with glossary
+llm-translate file docs/guide.md -o docs/guide.ja.md \
+  -s en -t ja --glossary glossary.json
+
+# Batch translate a directory
+llm-translate dir ./docs ./docs-ko -s en -t ko
+
+# Initialize config
+llm-translate init --provider claude
+
+# Validate glossary
+llm-translate glossary validate glossary.json
+
+# Start translation API server
+llm-translate serve --port 3000
+
+# Start server with CORS and JSON logging (for Docker)
+llm-translate serve --cors --json
+```
+
+## Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Invalid arguments |
+| 3 | File not found |
+| 4 | Quality threshold not met (strict mode) |
+| 5 | Provider/API error |
+| 6 | Glossary validation failed |
+
+## Environment Variables
+
+```bash
+# API Keys
+ANTHROPIC_API_KEY=sk-ant-xxxxx
+OPENAI_API_KEY=sk-xxxxx
+OLLAMA_BASE_URL=http://localhost:11434
+
+# Server Mode
+TRANSLATE_PORT=3000
+TRANSLATE_API_KEY=your-api-key
+```
+
+## Configuration Priority
+
+Settings are applied in this order (later overrides earlier):
+
+1. Built-in defaults
+2. Config file (`.translaterc.json`)
+3. Environment variables
+4. CLI arguments
+
+See [Configuration](../guide/configuration) for details.