@llm-translate/cli 1.0.0-next.1

package/src/types/index.ts

@@ -0,0 +1,265 @@
+// ============================================================================
+// Configuration Types
+// ============================================================================
+
+export type ProviderName = 'claude' | 'openai' | 'ollama' | 'custom';
+
+export interface TranslateConfig {
+  version: string;
+  project?: {
+    name: string;
+    description: string;
+    purpose: string;
+  };
+  languages: {
+    source: string;
+    targets: string[];
+    /** Per-language style instructions (e.g., { "ko": "경어체", "ja": "です・ます調" }) */
+    styles?: Record<string, string>;
+  };
+  provider: {
+    default: ProviderName;
+    model?: string;
+    fallback?: ProviderName[];
+    apiKeys?: Record<ProviderName, string>;
+  };
+  quality: {
+    threshold: number;
+    maxIterations: number;
+    evaluationMethod: 'llm' | 'embedding' | 'hybrid';
+  };
+  chunking: {
+    maxTokens: number;
+    overlapTokens: number;
+    preserveStructure: boolean;
+  };
+  glossary?: {
+    path: string;
+    strict: boolean;
+  };
+  paths: {
+    output: string;
+    cache?: string;
+  };
+  ignore?: string[];
+}
+
+// ============================================================================
+// Glossary Types
+// ============================================================================
+
+export interface Glossary {
+  metadata: {
+    name: string;
+    sourceLang: string;
+    targetLangs: string[];
+    version: string;
+    domain?: string;
+  };
+  terms: GlossaryTerm[];
+}
+
+export interface GlossaryTerm {
+  source: string;
+  targets: Record<string, string>;
+  context?: string;
+  caseSensitive?: boolean;
+  doNotTranslate?: boolean;
+  doNotTranslateFor?: string[];
+  partOfSpeech?: 'noun' | 'verb' | 'adjective' | 'other';
+  notes?: string;
+}
+
+export interface ResolvedGlossary {
+  metadata: {
+    name: string;
+    sourceLang: string;
+    targetLang: string;
+    version: string;
+    domain?: string;
+  };
+  terms: ResolvedGlossaryTerm[];
+}
+
+export interface ResolvedGlossaryTerm {
+  source: string;
+  target: string;
+  context?: string;
+  caseSensitive: boolean;
+  doNotTranslate: boolean;
+}
+
+// ============================================================================
+// Translation Types
+// ============================================================================
+
+export type DocumentFormat = 'markdown' | 'html' | 'text';
+
+export interface TranslationRequest {
+  content: string;
+  sourceLang: string;
+  targetLang: string;
+  format: DocumentFormat;
+  glossary?: ResolvedGlossary;
+  context?: {
+    documentPurpose?: string;
+    /** Per-language style instruction (e.g., "경어체", "です・ます調") */
+    styleInstruction?: string;
+    previousChunks?: string[];
+    documentSummary?: string;
+  };
+  options?: {
+    qualityThreshold?: number;
+    maxIterations?: number;
+    preserveFormatting?: boolean;
+  };
+}
+
+export interface TranslationResult {
+  content: string;
+  metadata: {
+    qualityScore: number;
+    qualityThreshold: number;
+    thresholdMet: boolean;
+    iterations: number;
+    tokensUsed: {
+      input: number;
+      output: number;
+      /** Tokens read from cache (90% cost reduction) */
+      cacheRead?: number;
+      /** Tokens written to cache (25% cost increase for first write) */
+      cacheWrite?: number;
+    };
+    duration: number;
+    provider: string;
+    model: string;
+  };
+  glossaryCompliance?: {
+    applied: string[];
+    missed: string[];
+  };
+}
+
+export interface ChunkResult {
+  original: string;
+  translated: string;
+  startOffset: number;
+  endOffset: number;
+  qualityScore: number;
+  iterations?: number;
+  tokensUsed?: {
+    input: number;
+    output: number;
+    /** Number of cache hits for this chunk */
+    cacheRead?: number;
+  };
+  /** Whether this chunk was retrieved from cache */
+  cached?: boolean;
+}
+
+export interface DocumentResult {
+  content: string;
+  chunks: ChunkResult[];
+  metadata: {
+    totalTokensUsed: number;
+    totalDuration: number;
+    averageQuality: number;
+    provider: string;
+    model: string;
+    totalIterations: number;
+    tokensUsed: {
+      input: number;
+      output: number;
+      /** Tokens read from cache (90% cost reduction) */
+      cacheRead?: number;
+      /** Tokens written to cache (25% cost increase for first write) */
+      cacheWrite?: number;
+    };
+    /** Cache statistics */
+    cache?: {
+      hits: number;
+      misses: number;
+    };
+  };
+  glossaryCompliance?: {
+    applied: string[];
+    missed: string[];
+    compliant: boolean;
+  };
+}
+
+// ============================================================================
+// Chunking Types
+// ============================================================================
+
+export interface Chunk {
+  id: string;
+  content: string;
+  type: 'translatable' | 'preserve';
+  startOffset: number;
+  endOffset: number;
+  metadata?: {
+    headerHierarchy?: string[];
+    previousContext?: string;
+  };
+}
+
+export interface ChunkingConfig {
+  maxTokens: number;
+  overlapTokens: number;
+  separators: string[];
+  preservePatterns: RegExp[];
+}
+
+// ============================================================================
+// Quality Evaluation Types
+// ============================================================================
+
+/**
+ * Legacy simple quality evaluation (for fast mode or fallback)
+ */
+export interface SimpleQualityEvaluation {
+  score: number;
+  breakdown: {
+    accuracy: number;
+    fluency: number;
+    glossary: number;
+    format: number;
+  };
+  issues: string[];
+}
+
+// Re-export MQM types
+export * from './mqm.js';
+
+// Re-export analysis types
+export * from './analysis.js';
+
+// Re-export mode types
+export * from './modes.js';
+
+/**
+ * Combined quality evaluation type (supports both MQM and simple)
+ */
+export type QualityEvaluation = SimpleQualityEvaluation;
+
+// ============================================================================
+// Cache Types
+// ============================================================================
+
+export interface CacheEntry {
+  sourceHash: string;
+  sourceLang: string;
+  targetLang: string;
+  glossaryHash: string;
+  translation: string;
+  qualityScore: number;
+  createdAt: string;
+  provider: string;
+  model: string;
+}
+
+export interface CacheIndex {
+  version: string;
+  entries: Record<string, CacheEntry>;
+}

package/src/types/modes.ts

@@ -0,0 +1,121 @@
+/**
+ * Translation Mode Configurations
+ *
+ * Defines preset configurations for different translation quality/speed tradeoffs
+ */
+
+/**
+ * Available translation modes
+ */
+export type TranslationMode = 'fast' | 'balanced' | 'quality';
+
+/**
+ * Configuration for a translation mode
+ */
+export interface ModeConfig {
+  /** Enable pre-translation analysis (MAPS-style) */
+  enableAnalysis: boolean;
+
+  /** Use MQM-based evaluation instead of simple scoring */
+  useMQMEvaluation: boolean;
+
+  /** Maximum refinement iterations */
+  maxIterations: number;
+
+  /** Quality threshold (0 = skip threshold check) */
+  qualityThreshold: number;
+}
+
+/**
+ * Mode preset configurations
+ */
+export const MODE_PRESETS: Record<TranslationMode, ModeConfig> = {
+  /**
+   * Fast mode: Single pass, no evaluation
+   * Best for: Quick drafts, large batches, local models
+   * Speed: ~1x (fastest)
+   */
+  fast: {
+    enableAnalysis: false,
+    useMQMEvaluation: false,
+    maxIterations: 1,
+    qualityThreshold: 0, // Skip threshold check
+  },
+
+  /**
+   * Balanced mode: TEaR with MQM evaluation
+   * Best for: General use, good quality with reasonable speed
+   * Speed: ~2-3x
+   */
+  balanced: {
+    enableAnalysis: false,
+    useMQMEvaluation: true,
+    maxIterations: 2,
+    qualityThreshold: 75,
+  },
+
+  /**
+   * Quality mode: Full MAPS + TEaR pipeline
+   * Best for: Production content, critical documents
+   * Speed: ~4-5x
+   */
+  quality: {
+    enableAnalysis: true,
+    useMQMEvaluation: true,
+    maxIterations: 4,
+    qualityThreshold: 85,
+  },
+};
+
+/**
+ * Get mode configuration with optional overrides
+ */
+export function getModeConfig(
+  mode: TranslationMode,
+  overrides?: Partial<ModeConfig>
+): ModeConfig {
+  const preset = MODE_PRESETS[mode];
+
+  if (!overrides) {
+    return preset;
+  }
+
+  return {
+    enableAnalysis: overrides.enableAnalysis ?? preset.enableAnalysis,
+    useMQMEvaluation: overrides.useMQMEvaluation ?? preset.useMQMEvaluation,
+    maxIterations: overrides.maxIterations ?? preset.maxIterations,
+    qualityThreshold: overrides.qualityThreshold ?? preset.qualityThreshold,
+  };
+}
+
+/**
+ * Determine effective mode from CLI options
+ */
+export function resolveMode(options: {
+  mode?: TranslationMode;
+  quality?: number;
+  maxIterations?: number;
+  noAnalysis?: boolean;
+  noMqm?: boolean;
+}): ModeConfig {
+  const baseMode = options.mode ?? 'balanced';
+  const preset = MODE_PRESETS[baseMode];
+
+  return {
+    enableAnalysis:
+      options.noAnalysis !== undefined
+        ? !options.noAnalysis
+        : preset.enableAnalysis,
+    useMQMEvaluation:
+      options.noMqm !== undefined ? !options.noMqm : preset.useMQMEvaluation,
+    maxIterations: options.maxIterations ?? preset.maxIterations,
+    qualityThreshold: options.quality ?? preset.qualityThreshold,
+  };
+}
+
+/**
+ * Check if mode allows skipping evaluation
+ */
+export function shouldSkipEvaluation(config: ModeConfig): boolean {
+  return config.maxIterations <= 1 && config.qualityThreshold <= 0;
+}

package/src/types/mqm.ts

@@ -0,0 +1,157 @@
+/**
+ * MQM (Multidimensional Quality Metrics) Types
+ * Based on https://themqm.org/ framework used in WMT evaluations
+ *
+ * Reference: TEaR (Translate, Estimate, Refine) - NAACL 2025
+ * https://arxiv.org/abs/2402.16379
+ */
+
+/**
+ * MQM Error Categories
+ */
+export type MQMErrorType =
+  // Accuracy errors - meaning/content issues
+  | 'accuracy/mistranslation' // Incorrect meaning
+  | 'accuracy/omission' // Missing content from source
+  | 'accuracy/addition' // Extra content not in source
+  | 'accuracy/untranslated' // Source text left unchanged
+  // Fluency errors - target language issues
+  | 'fluency/grammar' // Grammatical errors
+  | 'fluency/spelling' // Spelling/typos
+  | 'fluency/register' // Inappropriate formality level
+  | 'fluency/inconsistency' // Inconsistent terminology
+  // Style errors - quality/naturalness issues
+  | 'style/awkward' // Unnatural phrasing
+  | 'style/unidiomatic'; // Non-native expressions
+
+/**
+ * MQM Severity Levels
+ */
+export type MQMSeverity = 'minor' | 'major' | 'critical';
+
+/**
+ * MQM Severity Weights for score calculation
+ */
+export const MQM_SEVERITY_WEIGHTS: Record<MQMSeverity, number> = {
+  minor: 1, // Noticeable but doesn't affect understanding
+  major: 5, // Affects understanding or usability
+  critical: 25, // Completely wrong or unusable
+};
+
+/**
+ * Individual MQM error annotation
+ */
+export interface MQMError {
+  /** Error category */
+  type: MQMErrorType;
+
+  /** Error severity */
+  severity: MQMSeverity;
+
+  /** The affected text in translation */
+  span: string;
+
+  /** Suggested correction */
+  suggestion: string;
+
+  /** Brief reason for the error */
+  explanation?: string;
+
+  /** Corresponding source text (if applicable) */
+  sourceSpan?: string;
+}
+
+/**
+ * MQM evaluation result
+ */
+export interface MQMEvaluation {
+  /** List of identified errors */
+  errors: MQMError[];
+
+  /** Quality score: 100 - sum(error weights), min 0 */
+  score: number;
+
+  /** Brief overall assessment */
+  summary: string;
+
+  /** Error count breakdown by category */
+  breakdown: {
+    accuracy: number;
+    fluency: number;
+    style: number;
+  };
+}
+
+/**
+ * Calculate MQM score from errors
+ * Score = max(0, 100 - Σ(error_weight))
+ */
+export function calculateMQMScore(errors: MQMError[]): number {
+  const totalPenalty = errors.reduce(
+    (sum, err) => sum + MQM_SEVERITY_WEIGHTS[err.severity],
+    0
+  );
+  return Math.max(0, 100 - totalPenalty);
+}
+
+/**
+ * Calculate error breakdown by category
+ */
+export function calculateMQMBreakdown(
+  errors: MQMError[]
+): MQMEvaluation['breakdown'] {
+  return {
+    accuracy: errors.filter((e) => e.type.startsWith('accuracy/')).length,
+    fluency: errors.filter((e) => e.type.startsWith('fluency/')).length,
+    style: errors.filter((e) => e.type.startsWith('style/')).length,
+  };
+}
+
+/**
+ * Parse MQM evaluation JSON response from LLM
+ */
+export function parseMQMResponse(response: string): MQMEvaluation | null {
+  try {
+    // Extract JSON from response
+    const jsonMatch = response.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) {
+      return null;
+    }
+
+    const parsed = JSON.parse(jsonMatch[0]) as {
+      errors?: MQMError[];
+      score?: number;
+      summary?: string;
+    };
+
+    const errors = parsed.errors ?? [];
+    const score = parsed.score ?? calculateMQMScore(errors);
+
+    return {
+      errors,
+      score,
+      summary: parsed.summary ?? '',
+      breakdown: calculateMQMBreakdown(errors),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format MQM errors for refinement prompt
+ */
+export function formatMQMErrorsForPrompt(errors: MQMError[]): string {
+  if (errors.length === 0) {
+    return 'No errors identified.';
+  }
+
+  return errors
+    .map((err, i) => {
+      const severity = err.severity.toUpperCase();
+      return `${i + 1}. [${severity}] ${err.type}
+   Text: "${err.span}"
+   Fix: "${err.suggestion}"${err.explanation ? `\n   Reason: ${err.explanation}` : ''}`;
+    })
+    .join('\n\n');
+}

package/src/utils/logger.ts

@@ -0,0 +1,141 @@
+import chalk from 'chalk';
+
+// ============================================================================
+// Log Levels
+// ============================================================================
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+// ============================================================================
+// Logger Configuration
+// ============================================================================
+
+interface LoggerConfig {
+  level: LogLevel;
+  quiet: boolean;
+  json: boolean;
+}
+
+let config: LoggerConfig = {
+  level: 'info',
+  quiet: false,
+  json: false,
+};
+
+export function configureLogger(options: Partial<LoggerConfig>): void {
+  config = { ...config, ...options };
+}
+
+// ============================================================================
+// Logger Implementation
+// ============================================================================
+
+function shouldLog(level: LogLevel): boolean {
+  if (config.quiet && level !== 'error') {
+    return false;
+  }
+  return LOG_LEVEL_PRIORITY[level] >= LOG_LEVEL_PRIORITY[config.level];
+}
+
+function formatMessage(
+  level: LogLevel,
+  message: string,
+  data?: Record<string, unknown>
+): string {
+  if (config.json) {
+    return JSON.stringify({
+      level,
+      message,
+      timestamp: new Date().toISOString(),
+      ...data,
+    });
+  }
+
+  const timestamp = new Date().toISOString().slice(11, 19);
+  const prefix = `[${timestamp}]`;
+
+  switch (level) {
+    case 'debug':
+      return chalk.gray(`${prefix} ${message}`);
+    case 'info':
+      return `${prefix} ${message}`;
+    case 'warn':
+      return chalk.yellow(`${prefix} ⚠ ${message}`);
+    case 'error':
+      return chalk.red(`${prefix} ✗ ${message}`);
+  }
+}
+
+export const logger = {
+  debug(message: string, data?: Record<string, unknown>): void {
+    if (shouldLog('debug')) {
+      console.log(formatMessage('debug', message, data));
+    }
+  },
+
+  info(message: string, data?: Record<string, unknown>): void {
+    if (shouldLog('info')) {
+      console.log(formatMessage('info', message, data));
+    }
+  },
+
+  warn(message: string, data?: Record<string, unknown>): void {
+    if (shouldLog('warn')) {
+      console.warn(formatMessage('warn', message, data));
+    }
+  },
+
+  error(message: string, data?: Record<string, unknown>): void {
+    if (shouldLog('error')) {
+      console.error(formatMessage('error', message, data));
+    }
+  },
+
+  success(message: string): void {
+    if (!config.quiet) {
+      console.log(chalk.green(`✓ ${message}`));
+    }
+  },
+
+  progress(current: number, total: number, message: string): void {
+    if (!config.quiet && !config.json) {
+      const percent = Math.round((current / total) * 100);
+      const bar = '█'.repeat(Math.round(percent / 5)) + '░'.repeat(20 - Math.round(percent / 5));
+      process.stdout.write(`\r[${bar}] ${percent}% ${message}`);
+      if (current === total) {
+        console.log();
+      }
+    }
+  },
+};
+
+// ============================================================================
+// Timing Utilities
+// ============================================================================
+
+export function createTimer(): {
+  elapsed: () => number;
+  format: () => string;
+} {
+  const start = performance.now();
+
+  return {
+    elapsed(): number {
+      return performance.now() - start;
+    },
+    format(): string {
+      const ms = this.elapsed();
+      if (ms < 1000) {
+        return `${ms.toFixed(0)}ms`;
+      }
+      return `${(ms / 1000).toFixed(1)}s`;
+    },
+  };
+}