@llm-translate/cli 1.0.0-next.1

package/docs/ja/api/index.md

@@ -0,0 +1,171 @@
+# API リファレンス
+
+::: info 翻訳について
+英語以外のドキュメントはすべてClaude Sonnet 4を使用して自動翻訳されています。
+:::
+
+llm-translateはNode.jsアプリケーションでプログラム的に使用できます。
+
+## インストール
+
+```bash
+npm install @llm-translate/cli
+```
+
+## クイックスタート
+
+```typescript
+import { TranslationEngine, createClaudeProvider } from '@llm-translate/cli';
+
+// Create provider
+const provider = createClaudeProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+});
+
+// Create engine
+const engine = new TranslationEngine({
+  provider,
+  qualityThreshold: 85,
+});
+
+// Translate
+const result = await engine.translateFile({
+  input: 'README.md',
+  output: 'README.ko.md',
+  sourceLang: 'en',
+  targetLang: 'ko',
+});
+
+console.log(result.metadata);
+```
+
+## コアクラス
+
+### [TranslationEngine](./engine)
+
+翻訳操作のメインエントリーポイントです。
+
+```typescript
+const engine = new TranslationEngine(options);
+await engine.translateFile({ input, output, targetLang });
+await engine.translateContent(content, options);
+```
+
+### [TranslationAgent](./agent)
+
+Self-Refineループを持つ低レベル翻訳エージェントです。
+
+```typescript
+const agent = new TranslationAgent({ provider, qualityThreshold });
+const result = await agent.translate(request);
+```
+
+### [Providers](./providers)
+
+LLMプロバイダーの実装です。
+
+```typescript
+import {
+  createClaudeProvider,
+  createOpenAIProvider,
+  createOllamaProvider,
+} from '@llm-translate/cli';
+```
+
+## 型エクスポート
+
+```typescript
+import type {
+  // Configuration
+  TranslationConfig,
+  ProviderConfig,
+
+  // Requests/Results
+  TranslationRequest,
+  TranslationResult,
+
+  // Glossary
+  Glossary,
+  GlossaryTerm,
+  ResolvedGlossary,
+
+  // Quality
+  QualityEvaluation,
+
+  // Provider
+  LLMProvider,
+  ChatMessage,
+  ChatResponse,
+} from '@llm-translate/cli';
+```
+
+## ユーティリティ関数
+
+### Chunking
+
+```typescript
+import { chunkContent, chunkMarkdown } from '@llm-translate/cli';
+
+const chunks = chunkContent(text, { maxTokens: 1024 });
+const mdChunks = chunkMarkdown(markdown, { maxTokens: 1024 });
+```
+
+### 用語集
+
+```typescript
+import { loadGlossary, resolveGlossary, createGlossaryLookup } from '@llm-translate/cli';
+
+const glossary = await loadGlossary('./glossary.json');
+const resolved = resolveGlossary(glossary, 'ko');
+const lookup = createGlossaryLookup(resolved);
+
+const terms = lookup.findAll(sourceText);
+```
+
+### トークン推定
+
+```typescript
+import { estimateTokens, calculateTokenBudget } from '@llm-translate/cli';
+
+const tokens = estimateTokens(text);
+const budget = calculateTokenBudget(text, { glossaryTokens: 500 });
+```
+
+## エラーハンドリング
+
+```typescript
+import { TranslationError, ErrorCode } from '@llm-translate/cli';
+
+try {
+  await engine.translateFile(options);
+} catch (error) {
+  if (error instanceof TranslationError) {
+    switch (error.code) {
+      case ErrorCode.FILE_NOT_FOUND:
+        // Handle missing file
+        break;
+      case ErrorCode.QUALITY_THRESHOLD_NOT_MET:
+        // Handle quality issue
+        console.log('Score:', error.details.score);
+        break;
+      case ErrorCode.PROVIDER_RATE_LIMITED:
+        // Handle rate limit
+        break;
+    }
+  }
+}
+```
+
+## エラーコード
+
+| コード | 説明 |
+|------|-------------|
+|`FILE_NOT_FOUND`| 入力ファイルが存在しません |
+|`INVALID_CONFIG`| 設定の検証に失敗しました |
+|`GLOSSARY_NOT_FOUND`| 用語集ファイルが見つかりません |
+|`GLOSSARY_INVALID`| 用語集の検証に失敗しました |
+|`PROVIDER_AUTH_FAILED`| APIキーが無効です |
+|`PROVIDER_RATE_LIMITED`| レート制限を超過しました |
+|`PROVIDER_ERROR`| 一般的なプロバイダーエラーです |
+|`QUALITY_THRESHOLD_NOT_MET`| 翻訳品質が品質しきい値を下回りました |
+|`PARSE_ERROR`| ドキュメントの解析に失敗しました |

package/docs/ja/api/providers.md

@@ -0,0 +1,304 @@
+# プロバイダー
+
+::: info 翻訳について
+英語以外のドキュメントはすべてClaude Sonnet 4を使用して自動翻訳されています。
+:::
+
+異なるAIサービス向けのLLMプロバイダー実装です。
+
+## 概要
+
+すべてのプロバイダーは `LLMProvider` インターフェースを実装しています：
+
+```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プロバイダー
+
+推奨プロバイダーで、プロンプトキャッシングを完全にサポートしています。
+
+### セットアップ
+
+```typescript
+import { createClaudeProvider } from '@llm-translate/cli';
+
+const provider = createClaudeProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  defaultModel: 'claude-haiku-4-5-20251001',
+});
+```
+
+### 設定
+
+```typescript
+interface ClaudeProviderConfig {
+  apiKey?: string;          // Defaults to ANTHROPIC_API_KEY env
+  baseUrl?: string;         // Custom API endpoint
+  defaultModel?: string;    // Default: claude-haiku-4-5-20251001
+}
+```
+
+### 利用可能なモデル
+
+| モデル | コンテキスト | 入力コスト | 出力コスト |
+|-------|---------|------------|-------------|
+|`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 |
+
+### プロンプトキャッシング
+
+Claudeプロバイダーはプロンプトキャッシングを自動的にサポートします：
+
+```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プロバイダー
+
+### セットアップ
+
+```typescript
+import { createOpenAIProvider } from '@llm-translate/cli';
+
+const provider = createOpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY,
+  defaultModel: 'gpt-4o-mini',
+});
+```
+
+### 設定
+
+```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
+}
+```
+
+### 利用可能なモデル
+
+| モデル | コンテキスト | 入力コスト | 出力コスト |
+|-------|---------|------------|-------------|
+|`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 |
+
+### 自動キャッシング
+
+OpenAIは1024トークンを超えるプロンプトに対して自動的にキャッシングを処理します。
+
+## Ollamaプロバイダー
+
+ローカルでセルフホストされたモデル用です。
+
+### セットアップ
+
+```typescript
+import { createOllamaProvider } from '@llm-translate/cli';
+
+const provider = createOllamaProvider({
+  baseUrl: 'http://localhost:11434',
+  defaultModel: 'llama3.1',
+});
+```
+
+### 設定
+
+```typescript
+interface OllamaProviderConfig {
+  baseUrl?: string;         // Default: http://localhost:11434
+  defaultModel?: string;    // Default: llama3.1
+}
+```
+
+### 利用可能なモデル
+
+Ollamaインストールで利用可能な任意のモデル：
+
+```bash
+# List available models
+ollama list
+
+# Pull a model
+ollama pull llama3.1
+ollama pull mistral
+ollama pull codellama
+```
+
+### 制限事項
+
+- プロンプトキャッシングサポートなし
+- モデルによって品質が異なる
+- 限定的なコンテキストウィンドウ（モデル依存）
+
+## プロバイダーインターフェース
+
+### 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;
+}
+```
+
+## カスタムプロバイダー
+
+独自のプロバイダーを実装します：
+
+```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,
+    };
+  }
+}
+```
+
+## プロバイダー選択ガイド
+
+| 用途 | 推奨プロバイダー | モデル |
+|----------|---------------------|-------|
+| コスト効率 | Claude | Haiku 4.5 |
+| 高品質 | Claude | Sonnet 4.5 |
+| OpenAIエコシステム | OpenAI | GPT-4o |
+| 予算制約 | OpenAI | GPT-4o-mini |
+| プライバシー/オフライン | Ollama | Llama 3.1 |
+| エンタープライズ | Claude/OpenAI | 様々 |
+
+## エラーハンドリング
+
+すべてのプロバイダーは `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/ja/changelog.md

@@ -0,0 +1,64 @@
+# 変更履歴
+
+::: info 翻訳について
+英語以外のすべてのドキュメントは、Claude Sonnet 4を使用して自動翻訳されています。
+:::
+
+llm-translateのすべての重要な変更は、このファイルに記録されます。
+
+形式は[Keep a Changelog](https://keepachangelog.com/en/1.0.0/)に基づいており、
+このプロジェクトは[Semantic Versioning](https://semver.org/spec/v2.0.0.html)に準拠しています。
+
+## [未リリース]
+
+### 追加
+
+- Claudeモデルのプロンプトキャッシングサポート（40-50%のコスト削減）
+- 翻訳結果でのキャッシュトークン使用量追跡
+- TranslationAgentの `enableCaching` オプション
+- トークン使用量メタデータの `cacheRead` および `cacheWrite` フィールド
+- MQM（多次元品質メトリクス）ベースの品質評価システム
+- MAPSスタイルの翻訳前分析ステップ
+- 翻訳モードサポート（`--mode fast|balanced|quality`）
+
+### 変更
+
+-`ChatMessage.content` がキャッシュ可能なテキスト部分をサポート
+-`ChatResponse.usage` にキャッシュトークンメトリクスを含む
+- デフォルトモデルを `claude-haiku-4-5-20251001` に更新
+
+### ドキュメント
+
+- Ollamaの品質警告を追加：信頼性の高い翻訳には14B+モデルが必要
+
+## [0.1.0] - 2025-12-12
+
+### 追加
+
+- 初回リリース
+- 単一ファイル翻訳（`llm-translate file`）
+- ディレクトリ一括翻訳（`llm-translate dir`）
+- 設定初期化（`llm-translate init`）
+- 用語集管理（`llm-translate glossary`）
+- Claude、OpenAI、Ollamaプロバイダーサポート
+- Self-Refine品質制御ループ
+- Markdown ASTベースのChunking
+- 用語集の強制適用
+- 品質しきい値設定
+- 詳細出力モード
+
+### プロバイダー
+
+- Claude（claude-haiku-4-5、claude-sonnet-4-5、claude-opus-4-5）
+- OpenAI（gpt-4o-mini、gpt-4o、gpt-4-turbo）
+- Ollama（任意のローカルモデル）
+
+### ドキュメント
+
+- CLIリファレンスドキュメント
+- APIリファレンスドキュメント
+- 入門ガイド
+- 設定ガイド
+- 用語集ガイド
+- 品質制御ガイド
+- コスト最適化ガイド