@llm-translate/cli 1.0.0-next.1

package/src/services/config.ts

@@ -0,0 +1,217 @@
+import { cosmiconfig } from 'cosmiconfig';
+import { z } from 'zod';
+import type { TranslateConfig, ProviderName } from '../types/index.js';
+import { TranslationError, ErrorCode } from '../errors.js';
+
+// ============================================================================
+// Zod Schema for Config Validation
+// ============================================================================
+
+const providerNameSchema = z.enum(['claude', 'openai', 'ollama', 'custom']);
+
+const configSchema = z.object({
+  version: z.string(),
+  project: z
+    .object({
+      name: z.string(),
+      description: z.string(),
+      purpose: z.string(),
+    })
+    .optional(),
+  languages: z.object({
+    source: z.string(),
+    targets: z.array(z.string()),
+    styles: z.record(z.string(), z.string()).optional(),
+  }),
+  provider: z.object({
+    default: providerNameSchema,
+    model: z.string().optional(),
+    fallback: z.array(providerNameSchema).optional(),
+    apiKeys: z.record(providerNameSchema, z.string()).optional(),
+  }),
+  quality: z.object({
+    threshold: z.number().min(0).max(100),
+    maxIterations: z.number().min(1).max(10),
+    evaluationMethod: z.enum(['llm', 'embedding', 'hybrid']),
+  }),
+  chunking: z.object({
+    maxTokens: z.number().min(100).max(8000),
+    overlapTokens: z.number().min(0),
+    preserveStructure: z.boolean(),
+  }),
+  glossary: z
+    .object({
+      path: z.string(),
+      strict: z.boolean(),
+    })
+    .optional(),
+  paths: z.object({
+    output: z.string(),
+    cache: z.string().optional(),
+  }),
+  ignore: z.array(z.string()).optional(),
+});
+
+// ============================================================================
+// Default Configuration
+// ============================================================================
+
+const defaultConfig: TranslateConfig = {
+  version: '1.0',
+  languages: {
+    source: 'en',
+    targets: [],
+  },
+  provider: {
+    default: 'claude',
+  },
+  quality: {
+    threshold: 85,
+    maxIterations: 4,
+    evaluationMethod: 'llm',
+  },
+  chunking: {
+    maxTokens: 1024,
+    overlapTokens: 150,
+    preserveStructure: true,
+  },
+  paths: {
+    output: './{lang}',
+  },
+};
+
+// ============================================================================
+// Config Loader
+// ============================================================================
+
+const explorer = cosmiconfig('translate', {
+  searchPlaces: [
+    '.translaterc',
+    '.translaterc.json',
+    '.translaterc.yaml',
+    '.translaterc.yml',
+    'translate.config.js',
+    'translate.config.mjs',
+  ],
+});
+
+export interface LoadConfigOptions {
+  configPath?: string;
+  cwd?: string;
+}
+
+export async function loadConfig(
+  options: LoadConfigOptions = {}
+): Promise<TranslateConfig> {
+  const { configPath, cwd = process.cwd() } = options;
+
+  let result;
+
+  try {
+    if (configPath) {
+      result = await explorer.load(configPath);
+    } else {
+      result = await explorer.search(cwd);
+    }
+  } catch (error) {
+    throw new TranslationError(ErrorCode.CONFIG_NOT_FOUND, {
+      path: configPath ?? cwd,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  if (!result || result.isEmpty) {
+    // Return default config if no config file found
+    return defaultConfig;
+  }
+
+  // Validate config
+  const parseResult = configSchema.safeParse(result.config);
+
+  if (!parseResult.success) {
+    throw new TranslationError(ErrorCode.CONFIG_INVALID, {
+      path: result.filepath,
+      errors: parseResult.error.errors.map((e) => ({
+        path: e.path.join('.'),
+        message: e.message,
+      })),
+    });
+  }
+
+  return parseResult.data as TranslateConfig;
+}
+
+// ============================================================================
+// Config Merger (CLI options override config file)
+// ============================================================================
+
+export interface CLIOverrides {
+  sourceLang?: string;
+  targetLang?: string;
+  provider?: ProviderName;
+  model?: string;
+  quality?: number;
+  maxIterations?: number;
+  chunkSize?: number;
+  glossary?: string;
+  output?: string;
+  noCache?: boolean;
+}
+
+export function mergeConfig(
+  config: TranslateConfig,
+  overrides: CLIOverrides
+): TranslateConfig {
+  const merged = { ...config };
+
+  if (overrides.sourceLang) {
+    merged.languages = { ...merged.languages, source: overrides.sourceLang };
+  }
+
+  if (overrides.targetLang) {
+    merged.languages = {
+      ...merged.languages,
+      targets: [overrides.targetLang],
+    };
+  }
+
+  if (overrides.provider) {
+    merged.provider = { ...merged.provider, default: overrides.provider };
+  }
+
+  if (overrides.model) {
+    merged.provider = { ...merged.provider, model: overrides.model };
+  }
+
+  if (overrides.quality !== undefined) {
+    merged.quality = { ...merged.quality, threshold: overrides.quality };
+  }
+
+  if (overrides.maxIterations !== undefined) {
+    merged.quality = {
+      ...merged.quality,
+      maxIterations: overrides.maxIterations,
+    };
+  }
+
+  if (overrides.chunkSize !== undefined) {
+    merged.chunking = { ...merged.chunking, maxTokens: overrides.chunkSize };
+  }
+
+  if (overrides.glossary) {
+    merged.glossary = {
+      path: overrides.glossary,
+      strict: merged.glossary?.strict ?? false,
+    };
+  }
+
+  if (overrides.output) {
+    merged.paths = { ...merged.paths, output: overrides.output };
+  }
+
+  if (overrides.noCache) {
+    merged.paths = { ...merged.paths, cache: undefined };
+  }
+
+  return merged;
+}

package/src/services/glossary.ts

@@ -0,0 +1,247 @@
+import { readFile } from 'node:fs/promises';
+import type {
+  Glossary,
+  GlossaryTerm,
+  ResolvedGlossary,
+  ResolvedGlossaryTerm,
+} from '../types/index.js';
+import { TranslationError, ErrorCode } from '../errors.js';
+
+// ============================================================================
+// Glossary Loading
+// ============================================================================
+
+export async function loadGlossary(path: string): Promise<Glossary> {
+  let content: string;
+
+  try {
+    content = await readFile(path, 'utf-8');
+  } catch (error) {
+    throw new TranslationError(ErrorCode.GLOSSARY_NOT_FOUND, {
+      path,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  try {
+    return JSON.parse(content) as Glossary;
+  } catch (error) {
+    throw new TranslationError(ErrorCode.GLOSSARY_INVALID, {
+      path,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+// ============================================================================
+// Glossary Resolution
+// ============================================================================
+
+export function resolveGlossary(
+  glossary: Glossary,
+  targetLang: string
+): ResolvedGlossary {
+  return {
+    metadata: {
+      name: glossary.metadata.name,
+      sourceLang: glossary.metadata.sourceLang,
+      targetLang,
+      version: glossary.metadata.version,
+      domain: glossary.metadata.domain,
+    },
+    terms: glossary.terms
+      .map((term) => resolveGlossaryTerm(term, targetLang))
+      .filter((term): term is ResolvedGlossaryTerm => term !== null),
+  };
+}
+
+function resolveGlossaryTerm(
+  term: GlossaryTerm,
+  targetLang: string
+): ResolvedGlossaryTerm | null {
+  const target = resolveTarget(term, targetLang);
+
+  // Skip if no translation available and not a doNotTranslate term
+  if (target === undefined) {
+    return null;
+  }
+
+  return {
+    source: term.source,
+    target,
+    context: term.context,
+    caseSensitive: term.caseSensitive ?? false,
+    doNotTranslate: resolveDoNotTranslate(term, targetLang),
+  };
+}
+
+function resolveTarget(term: GlossaryTerm, targetLang: string): string | undefined {
+  if (term.doNotTranslate) {
+    return term.source;
+  }
+
+  if (term.doNotTranslateFor?.includes(targetLang)) {
+    return term.source;
+  }
+
+  const translation = term.targets[targetLang];
+  if (translation) {
+    return translation;
+  }
+
+  // No translation available for this language
+  return undefined;
+}
+
+function resolveDoNotTranslate(term: GlossaryTerm, targetLang: string): boolean {
+  return (
+    term.doNotTranslate === true ||
+    term.doNotTranslateFor?.includes(targetLang) === true
+  );
+}
+
+// ============================================================================
+// Glossary Lookup
+// ============================================================================
+
+export interface GlossaryLookup {
+  /**
+   * Find a term in the glossary
+   */
+  find(text: string): ResolvedGlossaryTerm | undefined;
+
+  /**
+   * Find all matching terms in a text
+   */
+  findAll(text: string): ResolvedGlossaryTerm[];
+
+  /**
+   * Get all terms
+   */
+  getTerms(): ResolvedGlossaryTerm[];
+
+  /**
+   * Format glossary for prompt injection
+   */
+  formatForPrompt(): string;
+}
+
+export function createGlossaryLookup(glossary: ResolvedGlossary): GlossaryLookup {
+  // Create a map for fast lookup
+  const termMap = new Map<string, ResolvedGlossaryTerm>();
+  const caseSensitiveTerms: ResolvedGlossaryTerm[] = [];
+  const caseInsensitiveTerms: ResolvedGlossaryTerm[] = [];
+
+  for (const term of glossary.terms) {
+    if (term.caseSensitive) {
+      termMap.set(term.source, term);
+      caseSensitiveTerms.push(term);
+    } else {
+      termMap.set(term.source.toLowerCase(), term);
+      caseInsensitiveTerms.push(term);
+    }
+  }
+
+  return {
+    find(text: string): ResolvedGlossaryTerm | undefined {
+      // Try exact match first
+      const exact = termMap.get(text);
+      if (exact) return exact;
+
+      // Try case-insensitive
+      return termMap.get(text.toLowerCase());
+    },
+
+    findAll(text: string): ResolvedGlossaryTerm[] {
+      const matches: ResolvedGlossaryTerm[] = [];
+
+      // Check case-sensitive terms
+      for (const term of caseSensitiveTerms) {
+        if (text.includes(term.source)) {
+          matches.push(term);
+        }
+      }
+
+      // Check case-insensitive terms
+      const lowerText = text.toLowerCase();
+      for (const term of caseInsensitiveTerms) {
+        if (lowerText.includes(term.source.toLowerCase())) {
+          matches.push(term);
+        }
+      }
+
+      return matches;
+    },
+
+    getTerms(): ResolvedGlossaryTerm[] {
+      return glossary.terms;
+    },
+
+    formatForPrompt(): string {
+      const lines: string[] = [];
+
+      for (const term of glossary.terms) {
+        const flags: string[] = [];
+
+        if (term.caseSensitive) {
+          flags.push('case-sensitive');
+        } else {
+          flags.push('case-insensitive');
+        }
+
+        if (term.context) {
+          flags.push(`context: ${term.context}`);
+        }
+
+        const flagStr = flags.length > 0 ? ` (${flags.join(', ')})` : '';
+
+        if (term.doNotTranslate) {
+          lines.push(`- "${term.source}" → [DO NOT TRANSLATE, keep as-is]${flagStr}`);
+        } else {
+          lines.push(`- "${term.source}" → "${term.target}"${flagStr}`);
+        }
+      }
+
+      return lines.join('\n');
+    },
+  };
+}
+
+// ============================================================================
+// Glossary Compliance Check
+// ============================================================================
+
+export interface ComplianceResult {
+  applied: string[];
+  missed: string[];
+  score: number;
+}
+
+export function checkGlossaryCompliance(
+  sourceText: string,
+  translatedText: string,
+  glossary: ResolvedGlossary
+): ComplianceResult {
+  const lookup = createGlossaryLookup(glossary);
+  const sourceTerms = lookup.findAll(sourceText);
+
+  const applied: string[] = [];
+  const missed: string[] = [];
+
+  for (const term of sourceTerms) {
+    const targetInTranslation = term.caseSensitive
+      ? translatedText.includes(term.target)
+      : translatedText.toLowerCase().includes(term.target.toLowerCase());
+
+    if (targetInTranslation) {
+      applied.push(term.source);
+    } else {
+      missed.push(term.source);
+    }
+  }
+
+  const total = sourceTerms.length;
+  const score = total > 0 ? (applied.length / total) * 100 : 100;
+
+  return { applied, missed, score };
+}

package/src/types/analysis.ts

@@ -0,0 +1,164 @@
+/**
+ * Pre-Translation Analysis Types
+ * Based on MAPS (Multi-Aspect Prompting and Selection) framework
+ *
+ * Reference: TACL 2024
+ * https://direct.mit.edu/tacl/article/doi/10.1162/tacl_a_00642/119992
+ * https://github.com/zwhe99/MAPS-mt
+ */
+
+/**
+ * Key term identified during pre-analysis
+ */
+export interface AnalyzedTerm {
+  /** The term in source language */
+  term: string;
+
+  /** Usage context */
+  context: string;
+
+  /** Suggested translation (if not in glossary) */
+  suggestedTranslation?: string;
+
+  /** Whether this term was found in the glossary */
+  fromGlossary: boolean;
+}
+
+/**
+ * Ambiguous phrase that needs clarification
+ */
+export interface AmbiguousPhrase {
+  /** The ambiguous phrase */
+  phrase: string;
+
+  /** Possible interpretations */
+  interpretations: string[];
+
+  /** Recommended interpretation */
+  recommendation: string;
+}
+
+/**
+ * Domain classification for the content
+ */
+export type ContentDomain =
+  | 'technical'
+  | 'marketing'
+  | 'legal'
+  | 'medical'
+  | 'general';
+
+/**
+ * Register/formality recommendation
+ */
+export type RegisterLevel = 'formal' | 'informal' | 'neutral';
+
+/**
+ * Pre-translation analysis result (MAPS-style)
+ */
+export interface PreTranslationAnalysis {
+  /** Key domain-specific terms identified */
+  keyTerms: AnalyzedTerm[];
+
+  /** Phrases with multiple possible interpretations */
+  ambiguousPhrases: AmbiguousPhrase[];
+
+  /** Items that should NOT be translated (code, URLs, names) */
+  preserveExact: string[];
+
+  /** Identified translation challenges for this language pair */
+  challenges: string[];
+
+  /** Detected content domain */
+  domain: ContentDomain;
+
+  /** Recommended formality level */
+  registerRecommendation: RegisterLevel;
+}
+
+/**
+ * Parse pre-analysis JSON response from LLM
+ */
+export function parseAnalysisResponse(
+  response: string
+): PreTranslationAnalysis | null {
+  try {
+    // Extract JSON from response
+    const jsonMatch = response.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) {
+      return null;
+    }
+
+    const parsed = JSON.parse(jsonMatch[0]) as Partial<PreTranslationAnalysis>;
+
+    return {
+      keyTerms: parsed.keyTerms ?? [],
+      ambiguousPhrases: parsed.ambiguousPhrases ?? [],
+      preserveExact: parsed.preserveExact ?? [],
+      challenges: parsed.challenges ?? [],
+      domain: parsed.domain ?? 'general',
+      registerRecommendation: parsed.registerRecommendation ?? 'neutral',
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format analysis result for translation prompt
+ */
+export function formatAnalysisForPrompt(
+  analysis: PreTranslationAnalysis
+): string {
+  const sections: string[] = [];
+
+  // Key terms section
+  if (analysis.keyTerms.length > 0) {
+    const terms = analysis.keyTerms
+      .map((t) => {
+        const translation = t.suggestedTranslation
+          ? ` → ${t.suggestedTranslation}`
+          : '';
+        const source = t.fromGlossary ? ' (glossary)' : '';
+        return `- "${t.term}"${translation}${source}: ${t.context}`;
+      })
+      .join('\n');
+    sections.push(`**Key Terms:**\n${terms}`);
+  }
+
+  // Ambiguous phrases section
+  if (analysis.ambiguousPhrases.length > 0) {
+    const phrases = analysis.ambiguousPhrases
+      .map((p) => `- "${p.phrase}": Use interpretation "${p.recommendation}"`)
+      .join('\n');
+    sections.push(`**Ambiguous Phrases (use these interpretations):**\n${phrases}`);
+  }
+
+  // Preserve exact section
+  if (analysis.preserveExact.length > 0) {
+    sections.push(
+      `**Do NOT translate (keep exactly as-is):**\n${analysis.preserveExact.map((s) => `- ${s}`).join('\n')}`
+    );
+  }
+
+  // Domain and register
+  sections.push(
+    `**Content Type:** ${analysis.domain}\n**Tone:** ${analysis.registerRecommendation}`
+  );
+
+  return sections.join('\n\n');
+}
+
+/**
+ * Create empty analysis result (for fast mode)
+ */
+export function createEmptyAnalysis(): PreTranslationAnalysis {
+  return {
+    keyTerms: [],
+    ambiguousPhrases: [],
+    preserveExact: [],
+    challenges: [],
+    domain: 'general',
+    registerRecommendation: 'neutral',
+  };
+}