@llm-translate/cli 1.0.0-next.1

package/docs/ja/cli/index.md

@@ -0,0 +1,111 @@
+# CLIリファレンス
+
+::: info 翻訳について
+英語以外のドキュメントはすべてClaude Sonnet 4を使用して自動翻訳されています。
+:::
+
+llm-translateは、ドキュメントを翻訳するためのコマンドラインインターフェースを提供します。
+
+## インストール
+
+```bash
+npm install -g @llm-translate/cli
+```
+
+## グローバルオプション
+
+これらのオプションはすべてのコマンドで使用できます：
+
+| オプション | 説明 |
+|--------|-------------|
+|`--help `,`-h`| ヘルプを表示 |
+|`--version `,`-V`| バージョンを表示 |
+|`--verbose `,`-v`| 詳細出力を有効化 |
+|`--quiet `,`-q`| 非必須出力を抑制 |
+|`--config`| 設定ファイルへのパス |
+
+## コマンド
+
+### [file](./file)
+
+単一ファイルを翻訳します。
+
+```bash
+llm-translate file <input> [output] [options]
+```
+
+### [dir](./dir)
+
+ディレクトリ内のすべてのファイルを翻訳します。
+
+```bash
+llm-translate dir <input> <output> [options]
+```
+
+### [init](./init)
+
+設定ファイルを初期化します。
+
+```bash
+llm-translate init [options]
+```
+
+### [glossary](./glossary)
+
+用語集ファイルを管理します。
+
+```bash
+llm-translate glossary <subcommand> [options]
+```
+
+## クイック例
+
+```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
+```
+
+## 終了コード
+
+| コード | 説明 |
+|------|-------------|
+| 0 | 成功 |
+| 1 | 一般的なエラー |
+| 2 | 無効な引数 |
+| 3 | ファイルが見つかりません |
+| 4 | 品質しきい値を満たしていません（厳密モード） |
+| 5 | プロバイダー/APIエラー |
+| 6 | 用語集の検証に失敗 |
+
+## 環境変数
+
+```bash
+# API Keys
+ANTHROPIC_API_KEY=sk-ant-xxxxx
+OPENAI_API_KEY=sk-xxxxx
+OLLAMA_BASE_URL=http://localhost:11434
+```
+
+## 設定の優先順位
+
+設定は以下の順序で適用されます（後のものが前のものを上書きします）：
+
+1. 組み込みデフォルト
+2. 設定ファイル（`.translaterc.json`）
+3. 環境変数
+4. CLI引数
+
+詳細については[設定](../guide/configuration)をご覧ください。

package/docs/ja/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/ja/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/ja/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/ja/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を使用する
+- [ ] 品質しきい値を適切に設定する（必要以上に高く設定しない）
+- [ ] プロンプトキャッシングを有効にして最大限活用する
+- [ ] ファイルをバッチで処理する
+- [ ] 用語集を簡潔に保つ
+- [ ] 増分更新には翻訳キャッシュを使用する
+- [ ] 詳細出力でコストを監視する
+- [ ] 大規模なジョブの前に見積もりを行う