@llm-translate/cli 1.0.0-next.1

package/docs/ja/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/ja/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. 品質評価
+
+各翻訳は4つの基準で評価されます：
+
+| 基準 | 重み | 説明 |
+|-----------|--------|-------------|
+| 意味的正確性 | 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/ja/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とsidebarを生成
+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を手動で設定し、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,
+      },
+    },
+  },
+});
+```
+
+## 単一ロケールの生成
+
+単一ロケールの設定を生成：
+
+```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. フロントマターの `title` フィールド
+2. ファイル内の最初の `#` 見出し
+3. タイトルケースに変換されたファイル名
+
+フロントマターの例：
+```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/ja/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エンドポイント」が毎回異なって翻訳される
+- **壊れたフォーマット** - コードブロックやMarkdownが破損する
+- **品質管理なし** - LLMの出力をそのまま受け入れる
+
+llm-translateはこれらの問題を以下で解決します：