@llm-translate/cli 1.0.0-next.1

package/docker-compose.yml

@@ -0,0 +1,56 @@
+version: '3.8'
+
+services:
+  # ==============================================================================
+  # llm-translate API Server
+  # ==============================================================================
+  llm-translate:
+    build: .
+    container_name: llm-translate-api
+    restart: unless-stopped
+    ports:
+      - "${TRANSLATE_PORT:-3000}:3000"
+    environment:
+      - NODE_ENV=production
+      - TRANSLATE_API_KEY=${TRANSLATE_API_KEY}
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - OLLAMA_BASE_URL=${OLLAMA_BASE_URL:-http://ollama:11434}
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://localhost:3000/health/live').then(r => r.ok ? process.exit(0) : process.exit(1))"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+        reservations:
+          memory: 256M
+
+  # ==============================================================================
+  # Optional: Local Ollama service for self-hosted LLM
+  # Enable with: docker compose --profile with-ollama up
+  # ==============================================================================
+  ollama:
+    image: ollama/ollama:latest
+    container_name: ollama
+    profiles:
+      - with-ollama
+    ports:
+      - "11434:11434"
+    volumes:
+      - ollama-models:/root/.ollama
+    deploy:
+      resources:
+        limits:
+          memory: 4G
+
+volumes:
+  ollama-models:

package/docs/.vitepress/config.ts

@@ -0,0 +1,161 @@
+import { defineConfig } from 'vitepress';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { generateLocaleConfig } from '../../dist/index.js';
+
+// Get docs directory path relative to this config file
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const docsDir = resolve(__dirname, '..');
+
+// Generate locale configurations automatically
+const locales = generateLocaleConfig(docsDir, {
+  defaultLocale: 'en',
+  locales: ['ko', 'ja', 'zh'],
+  labels: {
+    en: 'English',
+    ko: '한국어',
+    ja: '日本語',
+    zh: '中文',
+  },
+  descriptions: {
+    en: 'LLM-powered document translation CLI with glossary enforcement',
+    ko: 'LLM 기반 문서 번역 CLI - 용어집 적용 및 품질 관리',
+    ja: 'LLM駆動のドキュメント翻訳CLI - 用語集の適用と品質管理',
+    zh: 'LLM驱动的文档翻译CLI - 术语表应用和质量管理',
+  },
+  sidebarDirs: ['guide', 'cli', 'api'],
+  useTitleFromHeading: true,
+  translations: {
+    ko: {
+      editLinkText: 'GitHub에서 이 페이지 편집하기',
+      docFooter: { prev: '이전 페이지', next: '다음 페이지' },
+      outline: { label: '목차' },
+      lastUpdated: { text: '최종 업데이트' },
+      returnToTopLabel: '맨 위로',
+      sidebarMenuLabel: '메뉴',
+      darkModeSwitchLabel: '다크 모드',
+    },
+    ja: {
+      editLinkText: 'GitHubでこのページを編集する',
+      docFooter: { prev: '前のページ', next: '次のページ' },
+      outline: { label: '目次' },
+      lastUpdated: { text: '最終更新' },
+      returnToTopLabel: 'トップへ戻る',
+      sidebarMenuLabel: 'メニュー',
+      darkModeSwitchLabel: 'ダークモード',
+    },
+    zh: {
+      editLinkText: '在 GitHub 上编辑此页',
+      docFooter: { prev: '上一页', next: '下一页' },
+      outline: { label: '目录' },
+      lastUpdated: { text: '最后更新' },
+      returnToTopLabel: '返回顶部',
+      sidebarMenuLabel: '菜单',
+      darkModeSwitchLabel: '深色模式',
+    },
+  },
+});
+
+// Shared configuration
+const shared = defineConfig({
+  title: 'llm-translate',
+  base: '/llm-translate/',
+  head: [['link', { rel: 'icon', href: '/favicon.ico' }]],
+
+  themeConfig: {
+    logo: '/logo.svg',
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/selenehyun/llm-translate' },
+    ],
+    search: {
+      provider: 'local',
+      options: {
+        locales: {
+          ko: {
+            translations: {
+              button: {
+                buttonText: '검색',
+                buttonAriaLabel: '검색',
+              },
+              modal: {
+                displayDetails: '상세 목록 표시',
+                resetButtonTitle: '검색 지우기',
+                backButtonTitle: '검색 닫기',
+                noResultsText: '결과를 찾을 수 없습니다',
+                footer: {
+                  selectText: '선택',
+                  selectKeyAriaLabel: '선택하기',
+                  navigateText: '탐색',
+                  navigateUpKeyAriaLabel: '위로',
+                  navigateDownKeyAriaLabel: '아래로',
+                  closeText: '닫기',
+                  closeKeyAriaLabel: 'esc',
+                },
+              },
+            },
+          },
+          ja: {
+            translations: {
+              button: {
+                buttonText: '検索',
+                buttonAriaLabel: '検索',
+              },
+              modal: {
+                displayDetails: '詳細リストを表示',
+                resetButtonTitle: '検索をクリア',
+                backButtonTitle: '検索を閉じる',
+                noResultsText: '結果が見つかりませんでした',
+                footer: {
+                  selectText: '選択',
+                  selectKeyAriaLabel: '選択する',
+                  navigateText: '移動',
+                  navigateUpKeyAriaLabel: '上へ',
+                  navigateDownKeyAriaLabel: '下へ',
+                  closeText: '閉じる',
+                  closeKeyAriaLabel: 'esc',
+                },
+              },
+            },
+          },
+          zh: {
+            translations: {
+              button: {
+                buttonText: '搜索',
+                buttonAriaLabel: '搜索',
+              },
+              modal: {
+                displayDetails: '显示详细列表',
+                resetButtonTitle: '清除搜索',
+                backButtonTitle: '关闭搜索',
+                noResultsText: '未找到结果',
+                footer: {
+                  selectText: '选择',
+                  selectKeyAriaLabel: '选择',
+                  navigateText: '导航',
+                  navigateUpKeyAriaLabel: '向上',
+                  navigateDownKeyAriaLabel: '向下',
+                  closeText: '关闭',
+                  closeKeyAriaLabel: 'esc',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    editLink: {
+      pattern: 'https://github.com/selenehyun/llm-translate/edit/main/docs/:path',
+      text: 'Edit this page on GitHub',
+    },
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © 2025-present',
+    },
+  },
+});
+
+// Main config with locales
+export default defineConfig({
+  ...shared,
+  locales,
+});

package/docs/api/agent.md

@@ -0,0 +1,262 @@
+# TranslationAgent
+
+::: info Translations
+All non-English documentation is automatically translated using Claude Sonnet 4.
+:::
+
+Low-level translation agent implementing the Self-Refine algorithm.
+
+## Constructor
+
+```typescript
+import { TranslationAgent } from '@llm-translate/cli';
+
+const agent = new TranslationAgent(options: TranslationAgentOptions);
+```
+
+### Options
+
+```typescript
+interface TranslationAgentOptions {
+  provider: LLMProvider;
+  qualityThreshold?: number;  // Default: 85
+  maxIterations?: number;     // Default: 4
+  verbose?: boolean;          // Default: false
+  strictQuality?: boolean;    // Default: false
+  enableCaching?: boolean;    // Default: true for Claude
+}
+```
+
+## Methods
+
+### translate
+
+Translate content using Self-Refine loop.
+
+```typescript
+const result = await agent.translate(request: TranslationRequest);
+```
+
+#### Request
+
+```typescript
+interface TranslationRequest {
+  content: string;           // Source text to translate
+  sourceLang: string;        // Source language code
+  targetLang: string;        // Target language code
+  glossary?: ResolvedGlossary;  // Resolved glossary for target language
+  context?: {
+    documentPurpose?: string;
+    previousChunks?: string[];
+    documentSummary?: string;
+  };
+}
+```
+
+#### Result
+
+```typescript
+interface TranslationResult {
+  content: string;           // Translated text
+  metadata: {
+    qualityScore: number;
+    qualityThreshold: number;
+    thresholdMet: boolean;
+    iterations: number;
+    tokensUsed: {
+      input: number;
+      output: number;
+      cacheRead?: number;
+      cacheWrite?: number;
+    };
+    duration: number;
+    provider: string;
+    model: string;
+  };
+  glossaryCompliance?: {
+    applied: string[];       // Terms successfully applied
+    missed: string[];        // Terms not found in translation
+  };
+}
+```
+
+## Self-Refine Algorithm
+
+The agent implements this iterative refinement process:
+
+```typescript
+// Pseudocode
+async translate(request) {
+  // 1. Initial translation with glossary
+  let translation = await generateInitialTranslation(request);
+  let iterations = 1;
+
+  while (iterations < maxIterations) {
+    // 2. Evaluate quality
+    const evaluation = await evaluateQuality(translation);
+
+    if (evaluation.score >= qualityThreshold) {
+      break;  // Quality met
+    }
+
+    // 3. Generate improvement suggestions
+    const suggestions = await generateReflection(translation);
+
+    // 4. Apply improvements
+    translation = await improveTranslation(translation, suggestions);
+    iterations++;
+  }
+
+  return { content: translation, metadata: { ... } };
+}
+```
+
+## Example Usage
+
+### Basic Translation
+
+```typescript
+import { TranslationAgent, createClaudeProvider } from '@llm-translate/cli';
+
+const provider = createClaudeProvider();
+const agent = new TranslationAgent({
+  provider,
+  qualityThreshold: 85,
+});
+
+const result = await agent.translate({
+  content: 'Hello, world!',
+  sourceLang: 'en',
+  targetLang: 'ko',
+});
+
+console.log(result.content);  // 안녕하세요, 세계!
+console.log(result.metadata.qualityScore);  // 92
+```
+
+### With Glossary
+
+```typescript
+import { loadGlossary, resolveGlossary } from '@llm-translate/cli';
+
+const glossary = await loadGlossary('./glossary.json');
+const resolved = resolveGlossary(glossary, 'ko');
+
+const result = await agent.translate({
+  content: 'The component renders a prop.',
+  sourceLang: 'en',
+  targetLang: 'ko',
+  glossary: resolved,
+});
+
+console.log(result.glossaryCompliance);
+// { applied: ['component', 'prop'], missed: [] }
+```
+
+### With Context
+
+```typescript
+const result = await agent.translate({
+  content: 'Click the button to continue.',
+  sourceLang: 'en',
+  targetLang: 'ko',
+  context: {
+    documentPurpose: 'User interface instructions',
+    previousChunks: [
+      '이전 단계에서 설정을 완료했습니다.',  // Previous translation
+    ],
+  },
+});
+```
+
+### Strict Quality Mode
+
+```typescript
+import { TranslationError, ErrorCode } from '@llm-translate/cli';
+
+const agent = new TranslationAgent({
+  provider,
+  qualityThreshold: 95,
+  strictQuality: true,  // Throw if threshold not met
+});
+
+try {
+  const result = await agent.translate(request);
+} catch (error) {
+  if (error instanceof TranslationError &&
+      error.code === ErrorCode.QUALITY_THRESHOLD_NOT_MET) {
+    console.log(`Quality: ${error.details.score}/${error.details.threshold}`);
+    console.log(`Issues: ${error.details.issues.join(', ')}`);
+  }
+}
+```
+
+## Quality Evaluation
+
+The agent evaluates translations on four criteria:
+
+| Criterion | Weight | Description |
+|-----------|--------|-------------|
+| Semantic Accuracy | 40% | Meaning preservation |
+| Fluency | 25% | Natural language flow |
+| Glossary Compliance | 20% | Term consistency |
+| Format Preservation | 15% | Structure maintenance |
+
+### Evaluation Result
+
+```typescript
+interface QualityEvaluation {
+  score: number;           // 0-100
+  breakdown: {
+    accuracy: number;      // 0-40
+    fluency: number;       // 0-25
+    glossary: number;      // 0-20
+    format: number;        // 0-15
+  };
+  issues: string[];        // Specific problems identified
+}
+```
+
+## Prompt Caching
+
+When `enableCaching` is true (default for Claude), the agent structures prompts for caching:
+
+```
+┌─────────────────────────────────┐
+│ System Instructions (CACHED)    │  ← Reused across chunks
+├─────────────────────────────────┤
+│ Glossary (CACHED)              │  ← Reused across chunks
+├─────────────────────────────────┤
+│ Source Text (NOT cached)       │  ← Changes per chunk
+└─────────────────────────────────┘
+```
+
+This can reduce costs by 40-50% for multi-chunk documents.
+
+## Advanced: Custom Evaluation
+
+Override the default evaluation logic:
+
+```typescript
+class CustomAgent extends TranslationAgent {
+  protected async evaluateQuality(
+    source: string,
+    translation: string,
+    sourceLang: string,
+    targetLang: string
+  ): Promise<QualityEvaluation> {
+    // Custom evaluation logic
+    const baseEval = await super.evaluateQuality(
+      source, translation, sourceLang, targetLang
+    );
+
+    // Add custom checks
+    if (translation.length < source.length * 0.5) {
+      baseEval.score -= 10;
+      baseEval.issues.push('Translation suspiciously short');
+    }
+
+    return baseEval;
+  }
+}
+```