@llm-translate/cli 1.0.0-next.1

package/dist/index.d.ts

@@ -0,0 +1,1152 @@
+import { Root } from 'mdast';
+
+/**
+ * Translation Mode Configurations
+ *
+ * Defines preset configurations for different translation quality/speed tradeoffs
+ */
+/**
+ * Available translation modes
+ */
+type TranslationMode = 'fast' | 'balanced' | 'quality';
+
+type ProviderName = 'claude' | 'openai' | 'ollama' | 'custom';
+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[];
+}
+interface Glossary {
+    metadata: {
+        name: string;
+        sourceLang: string;
+        targetLangs: string[];
+        version: string;
+        domain?: string;
+    };
+    terms: GlossaryTerm[];
+}
+interface GlossaryTerm {
+    source: string;
+    targets: Record<string, string>;
+    context?: string;
+    caseSensitive?: boolean;
+    doNotTranslate?: boolean;
+    doNotTranslateFor?: string[];
+    partOfSpeech?: 'noun' | 'verb' | 'adjective' | 'other';
+    notes?: string;
+}
+interface ResolvedGlossary {
+    metadata: {
+        name: string;
+        sourceLang: string;
+        targetLang: string;
+        version: string;
+        domain?: string;
+    };
+    terms: ResolvedGlossaryTerm[];
+}
+interface ResolvedGlossaryTerm {
+    source: string;
+    target: string;
+    context?: string;
+    caseSensitive: boolean;
+    doNotTranslate: boolean;
+}
+type DocumentFormat = 'markdown' | 'html' | 'text';
+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;
+    };
+}
+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[];
+    };
+}
+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;
+}
+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;
+    };
+}
+interface Chunk {
+    id: string;
+    content: string;
+    type: 'translatable' | 'preserve';
+    startOffset: number;
+    endOffset: number;
+    metadata?: {
+        headerHierarchy?: string[];
+        previousContext?: string;
+    };
+}
+interface ChunkingConfig {
+    maxTokens: number;
+    overlapTokens: number;
+    separators: string[];
+    preservePatterns: RegExp[];
+}
+/**
+ * Legacy simple quality evaluation (for fast mode or fallback)
+ */
+interface SimpleQualityEvaluation {
+    score: number;
+    breakdown: {
+        accuracy: number;
+        fluency: number;
+        glossary: number;
+        format: number;
+    };
+    issues: string[];
+}
+
+/**
+ * Combined quality evaluation type (supports both MQM and simple)
+ */
+type QualityEvaluation = SimpleQualityEvaluation;
+interface CacheEntry {
+    sourceHash: string;
+    sourceLang: string;
+    targetLang: string;
+    glossaryHash: string;
+    translation: string;
+    qualityScore: number;
+    createdAt: string;
+    provider: string;
+    model: string;
+}
+interface CacheIndex {
+    version: string;
+    entries: Record<string, CacheEntry>;
+}
+
+type ChatRole = 'system' | 'user' | 'assistant';
+/**
+ * Content part with optional cache control for prompt caching
+ */
+interface CacheableTextPart {
+    type: 'text';
+    text: string;
+    /** Enable prompt caching for this content part (Claude only) */
+    cacheControl?: {
+        type: 'ephemeral';
+    };
+}
+interface ChatMessage {
+    role: ChatRole;
+    /** Content can be a string or array of cacheable parts */
+    content: string | CacheableTextPart[];
+}
+interface ChatRequest {
+    messages: ChatMessage[];
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+interface ChatResponse {
+    content: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        /** Tokens read from cache (90% cost reduction) */
+        cacheReadTokens?: number;
+        /** Tokens written to cache (25% cost increase for first write) */
+        cacheWriteTokens?: number;
+    };
+    model: string;
+    finishReason: 'stop' | 'length' | 'error';
+}
+interface ModelInfo {
+    maxContextTokens: number;
+    supportsStreaming: boolean;
+    costPer1kInput?: number;
+    costPer1kOutput?: number;
+}
+interface ProviderConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    defaultModel?: string;
+    timeout?: number;
+}
+interface LLMProvider {
+    readonly name: ProviderName;
+    /**
+     * The default model used by this provider
+     */
+    readonly defaultModel: string;
+    /**
+     * Send a chat request and receive a complete response
+     */
+    chat(request: ChatRequest): Promise<ChatResponse>;
+    /**
+     * Send a chat request and receive a streaming response
+     */
+    stream(request: ChatRequest): AsyncIterable<string>;
+    /**
+     * Count the number of tokens in a text string
+     */
+    countTokens(text: string): number;
+    /**
+     * Get information about a specific model
+     */
+    getModelInfo(model?: string): ModelInfo;
+}
+type ProviderFactory = (config: ProviderConfig) => LLMProvider;
+
+declare enum ErrorCode {
+    CONFIG_NOT_FOUND = "CONFIG_NOT_FOUND",
+    CONFIG_INVALID = "CONFIG_INVALID",
+    GLOSSARY_NOT_FOUND = "GLOSSARY_NOT_FOUND",
+    GLOSSARY_INVALID = "GLOSSARY_INVALID",
+    PROVIDER_NOT_FOUND = "PROVIDER_NOT_FOUND",
+    PROVIDER_AUTH_FAILED = "PROVIDER_AUTH_FAILED",
+    PROVIDER_RATE_LIMITED = "PROVIDER_RATE_LIMITED",
+    PROVIDER_ERROR = "PROVIDER_ERROR",
+    QUALITY_THRESHOLD_NOT_MET = "QUALITY_THRESHOLD_NOT_MET",
+    GLOSSARY_COMPLIANCE_FAILED = "GLOSSARY_COMPLIANCE_FAILED",
+    FILE_NOT_FOUND = "FILE_NOT_FOUND",
+    FILE_READ_ERROR = "FILE_READ_ERROR",
+    FILE_WRITE_ERROR = "FILE_WRITE_ERROR",
+    UNSUPPORTED_FORMAT = "UNSUPPORTED_FORMAT",
+    CHUNK_TOO_LARGE = "CHUNK_TOO_LARGE",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+declare class TranslationError extends Error {
+    readonly code: ErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(code: ErrorCode, details?: Record<string, unknown>, customMessage?: string);
+    /**
+     * Create a JSON representation of the error
+     */
+    toJSON(): Record<string, unknown>;
+}
+declare function isTranslationError(error: unknown): error is TranslationError;
+declare function isErrorCode(error: unknown, code: ErrorCode): boolean;
+declare const ExitCode: {
+    readonly SUCCESS: 0;
+    readonly GENERAL_ERROR: 1;
+    readonly INVALID_ARGUMENTS: 2;
+    readonly FILE_NOT_FOUND: 3;
+    readonly QUALITY_THRESHOLD_NOT_MET: 4;
+    readonly PROVIDER_ERROR: 5;
+    readonly GLOSSARY_VALIDATION_FAILED: 6;
+};
+type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];
+/**
+ * Map error codes to exit codes
+ */
+declare function getExitCode(error: TranslationError): ExitCode;
+
+interface LoadConfigOptions {
+    configPath?: string;
+    cwd?: string;
+}
+declare function loadConfig(options?: LoadConfigOptions): Promise<TranslateConfig>;
+interface CLIOverrides {
+    sourceLang?: string;
+    targetLang?: string;
+    provider?: ProviderName;
+    model?: string;
+    quality?: number;
+    maxIterations?: number;
+    chunkSize?: number;
+    glossary?: string;
+    output?: string;
+    noCache?: boolean;
+}
+declare function mergeConfig(config: TranslateConfig, overrides: CLIOverrides): TranslateConfig;
+
+declare function loadGlossary(path: string): Promise<Glossary>;
+declare function resolveGlossary(glossary: Glossary, targetLang: string): ResolvedGlossary;
+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;
+}
+declare function createGlossaryLookup(glossary: ResolvedGlossary): GlossaryLookup;
+interface ComplianceResult {
+    applied: string[];
+    missed: string[];
+    score: number;
+}
+declare function checkGlossaryCompliance(sourceText: string, translatedText: string, glossary: ResolvedGlossary): ComplianceResult;
+
+/**
+ * Translation Cache Service
+ *
+ * File-based caching using content hashes to avoid re-translating unchanged content.
+ * Cache entries are indexed by a composite key of content hash, target language,
+ * glossary hash, provider, and model.
+ */
+
+/**
+ * Context provided to invalidation policies for evaluation
+ */
+interface InvalidationContext {
+    /** Current glossary hash (if glossary is used) */
+    glossaryHash?: string;
+    /** Previous glossary hash (stored in cache metadata) */
+    previousGlossaryHash?: string;
+    /** Provider name */
+    provider?: string;
+    /** Model name */
+    model?: string;
+    /** Cache entry creation timestamp */
+    entryCreatedAt?: string;
+    /** Current timestamp */
+    currentTime?: Date;
+    /** Custom metadata for policy-specific checks */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of an invalidation check
+ */
+interface InvalidationResult {
+    /** Whether invalidation should occur */
+    shouldInvalidate: boolean;
+    /** Reason for invalidation (for logging) */
+    reason?: string;
+    /** Scope of invalidation */
+    scope: 'all' | 'matching' | 'none';
+    /** Filter function for 'matching' scope - returns true if entry should be invalidated */
+    filter?: (entry: CacheEntry, key: string) => boolean;
+}
+/**
+ * Abstract invalidation policy interface
+ */
+interface InvalidationPolicy {
+    /** Policy name for logging */
+    readonly name: string;
+    /** Check if cache should be invalidated */
+    check(context: InvalidationContext): InvalidationResult;
+}
+/**
+ * Invalidates all cache entries when glossary changes
+ */
+declare class GlossaryChangePolicy implements InvalidationPolicy {
+    readonly name = "GlossaryChangePolicy";
+    private readonly mode;
+    /**
+     * @param mode - 'all' invalidates entire cache, 'matching' only entries with old glossary hash
+     */
+    constructor(mode?: 'all' | 'matching');
+    check(context: InvalidationContext): InvalidationResult;
+}
+/**
+ * Invalidates cache entries older than specified TTL
+ */
+declare class TTLPolicy implements InvalidationPolicy {
+    readonly name = "TTLPolicy";
+    private readonly ttlMs;
+    /**
+     * @param ttlMs - Time-to-live in milliseconds
+     */
+    constructor(ttlMs: number);
+    /**
+     * Create policy with TTL in hours
+     */
+    static hours(hours: number): TTLPolicy;
+    /**
+     * Create policy with TTL in days
+     */
+    static days(days: number): TTLPolicy;
+    check(context: InvalidationContext): InvalidationResult;
+}
+/**
+ * Invalidates cache entries when provider or model changes
+ */
+declare class ProviderChangePolicy implements InvalidationPolicy {
+    readonly name = "ProviderChangePolicy";
+    private readonly checkModel;
+    /**
+     * @param checkModel - If true, also invalidate when model changes within same provider
+     */
+    constructor(checkModel?: boolean);
+    check(context: InvalidationContext): InvalidationResult;
+}
+/**
+ * Invalidates cache entries below a quality threshold
+ */
+declare class QualityThresholdPolicy implements InvalidationPolicy {
+    readonly name = "QualityThresholdPolicy";
+    private readonly threshold;
+    /**
+     * @param threshold - Minimum quality score (0-100)
+     */
+    constructor(threshold: number);
+    check(_context: InvalidationContext): InvalidationResult;
+}
+/**
+ * Combines multiple policies - invalidates if ANY policy triggers
+ */
+declare class CompositePolicy implements InvalidationPolicy {
+    readonly name = "CompositePolicy";
+    private readonly policies;
+    private readonly mode;
+    /**
+     * @param policies - Array of policies to combine
+     * @param mode - 'any' triggers if any policy matches, 'all' requires all policies to match
+     */
+    constructor(policies: InvalidationPolicy[], mode?: 'any' | 'all');
+    check(context: InvalidationContext): InvalidationResult;
+}
+interface CacheOptions {
+    /** Cache directory path */
+    cacheDir: string;
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /** Invalidation policies to apply */
+    invalidationPolicies?: InvalidationPolicy[];
+}
+interface CacheKey {
+    /** Source content (will be hashed) */
+    content: string;
+    /** Source language */
+    sourceLang: string;
+    /** Target language */
+    targetLang: string;
+    /** Glossary content or hash (will be hashed if string) */
+    glossary?: string;
+    /** Provider name */
+    provider: string;
+    /** Model name */
+    model: string;
+}
+interface CacheStats {
+    /** Total number of cached entries */
+    entries: number;
+    /** Total cache size in bytes */
+    sizeBytes: number;
+    /** Cache version */
+    version: string;
+    /** Number of entries invalidated by policies */
+    invalidated?: number;
+}
+/**
+ * Cache metadata stored separately for tracking state across sessions
+ */
+interface CacheMetadata {
+    /** Last known glossary hash */
+    glossaryHash?: string;
+    /** Last known provider */
+    provider?: string;
+    /** Last known model */
+    model?: string;
+    /** Last invalidation timestamp */
+    lastInvalidation?: string;
+    /** Custom metadata */
+    custom?: Record<string, unknown>;
+}
+interface CacheResult {
+    /** Whether the entry was found in cache */
+    hit: boolean;
+    /** The cached entry if found */
+    entry?: CacheEntry;
+}
+/**
+ * Generate SHA-256 hash of content
+ */
+declare function hashContent(content: string): string;
+/**
+ * Generate cache key from components
+ */
+declare function generateCacheKey(key: CacheKey): string;
+declare class CacheManager {
+    private cacheDir;
+    private indexPath;
+    private entriesDir;
+    private metadataPath;
+    private verbose;
+    private index;
+    private policies;
+    private metadata;
+    constructor(options: CacheOptions);
+    /**
+     * Initialize cache directory and load index
+     */
+    private ensureInitialized;
+    /**
+     * Load cache metadata from disk
+     */
+    private loadMetadata;
+    /**
+     * Save cache metadata to disk
+     */
+    private saveMetadata;
+    /**
+     * Update cache metadata
+     */
+    updateMetadata(updates: Partial<CacheMetadata>): void;
+    /**
+     * Get current cache metadata
+     */
+    getMetadata(): CacheMetadata;
+    /**
+     * Apply all configured invalidation policies
+     * @returns Number of entries invalidated
+     */
+    applyPolicies(context: InvalidationContext): number;
+    /**
+     * Invalidate entries matching a filter function
+     * @returns Number of entries invalidated
+     */
+    invalidateMatching(filter: (entry: CacheEntry, key: string) => boolean): number;
+    /**
+     * Add an invalidation policy at runtime
+     */
+    addPolicy(policy: InvalidationPolicy): void;
+    /**
+     * Remove an invalidation policy by name
+     */
+    removePolicy(name: string): boolean;
+    /**
+     * Get all configured policies
+     */
+    getPolicies(): InvalidationPolicy[];
+    /**
+     * Save index to disk
+     */
+    private saveIndex;
+    /**
+     * Get cached translation if available
+     */
+    get(key: CacheKey): CacheResult;
+    /**
+     * Store translation in cache
+     */
+    set(key: CacheKey, translation: string, qualityScore: number): void;
+    /**
+     * Check if entry exists in cache
+     */
+    has(key: CacheKey): boolean;
+    /**
+     * Remove entry from cache
+     */
+    delete(key: CacheKey): boolean;
+    /**
+     * Clear entire cache (synchronous)
+     */
+    private clearSync;
+    /**
+     * Clear entire cache
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Get all cached entries (for debugging)
+     */
+    getAllEntries(): Record<string, CacheEntry>;
+}
+/**
+ * Create a cache manager instance
+ */
+declare function createCacheManager(options: CacheOptions): CacheManager;
+/**
+ * Create a no-op cache manager that never caches (for --no-cache mode)
+ */
+declare function createNullCacheManager(): CacheManager & {
+    isNull: true;
+};
+/**
+ * Create default invalidation policies for typical translation workflow
+ */
+declare function createDefaultPolicies(): InvalidationPolicy[];
+/**
+ * Create strict invalidation policies (more aggressive invalidation)
+ */
+declare function createStrictPolicies(qualityThreshold?: number): InvalidationPolicy[];
+/**
+ * Create minimal invalidation policies (only glossary changes)
+ */
+declare function createMinimalPolicies(): InvalidationPolicy[];
+
+declare function registerProvider(name: ProviderName, factory: ProviderFactory): void;
+declare function getProvider(name: ProviderName, config?: ProviderConfig): LLMProvider;
+declare function hasProvider(name: ProviderName): boolean;
+declare function getAvailableProviders(): ProviderName[];
+declare function getProviderConfigFromEnv(name: ProviderName): ProviderConfig;
+interface CreateProviderOptions {
+    primary: ProviderName;
+    fallback?: ProviderName[];
+    config?: Partial<Record<ProviderName, ProviderConfig>>;
+}
+declare function createProviderWithFallback(options: CreateProviderOptions): LLMProvider;
+
+declare class ClaudeProvider implements LLMProvider {
+    readonly name: ProviderName;
+    readonly defaultModel: string;
+    private readonly client;
+    constructor(config?: ProviderConfig);
+    chat(request: ChatRequest): Promise<ChatResponse>;
+    /**
+     * Convert messages to Vercel AI SDK format with cache control support
+     */
+    private convertMessages;
+    stream(request: ChatRequest): AsyncIterable<string>;
+    countTokens(text: string): number;
+    getModelInfo(model?: string): ModelInfo;
+    private handleError;
+}
+declare function createClaudeProvider(config?: ProviderConfig): LLMProvider;
+
+interface ChunkerOptions {
+    maxTokens?: number;
+    overlapTokens?: number;
+    preserveCodeBlocks?: boolean;
+}
+/**
+ * Split content into chunks that respect token limits
+ */
+declare function chunkContent(content: string, options?: ChunkerOptions): Chunk[];
+/**
+ * Reassemble chunks back into a document
+ * Note: Chunks should not have overlapping content - overlap is only used for context metadata
+ */
+declare function reassembleChunks(chunks: Chunk[]): string;
+/**
+ * Get chunk statistics
+ */
+declare function getChunkStats(chunks: Chunk[]): {
+    totalChunks: number;
+    translatableChunks: number;
+    preservedChunks: number;
+    totalTokens: number;
+    averageTokens: number;
+};
+
+interface TranslationAgentOptions {
+    provider: LLMProvider;
+    qualityThreshold?: number;
+    maxIterations?: number;
+    verbose?: boolean;
+    /** If true, throw error when quality threshold is not met after max iterations */
+    strictQuality?: boolean;
+    /** Enable prompt caching for Claude provider (default: true) */
+    enableCaching?: boolean;
+    /** Translation mode: fast, balanced, quality (default: balanced) */
+    mode?: TranslationMode;
+    /** Enable pre-translation analysis (MAPS-style) - overrides mode setting */
+    enableAnalysis?: boolean;
+    /** Use MQM-based evaluation - overrides mode setting */
+    useMQMEvaluation?: boolean;
+}
+declare class TranslationAgent {
+    private provider;
+    private qualityThreshold;
+    private maxIterations;
+    private verbose;
+    private strictQuality;
+    private enableCaching;
+    private enableAnalysis;
+    private useMQMEvaluation;
+    constructor(options: TranslationAgentOptions);
+    /**
+     * Translate content using Self-Refine loop with optional MAPS analysis and MQM evaluation
+     */
+    translate(request: TranslationRequest): Promise<TranslationResult>;
+    private generateInitialTranslation;
+    private generateReflection;
+    private improveTranslation;
+    private evaluateQuality;
+    /**
+     * Pre-translation analysis using MAPS-style approach
+     * Identifies key terms, ambiguous phrases, and translation challenges
+     */
+    private analyzeSource;
+    /**
+     * Evaluate translation quality using MQM framework
+     * Returns structured error annotations for targeted refinement
+     */
+    private evaluateQualityMQM;
+    /**
+     * Refine translation based on MQM error annotations
+     * Applies targeted fixes for identified errors
+     */
+    private refineWithMQM;
+    /**
+     * Clean up translation output by removing prompt artifacts
+     * Uses guardrails to detect and remove any trailing prompt-like content
+     */
+    private cleanTranslationOutput;
+    /**
+     * Preserve leading/trailing whitespace from source text in translated text
+     * This ensures document structure (line breaks between sections) is maintained
+     */
+    private preserveWhitespace;
+    private checkGlossaryCompliance;
+}
+declare function createTranslationAgent(options: TranslationAgentOptions): TranslationAgent;
+
+interface TranslationEngineOptions {
+    config: TranslateConfig;
+    provider?: LLMProvider;
+    verbose?: boolean;
+    /** Disable caching (--no-cache mode) */
+    noCache?: boolean;
+}
+interface TranslateFileOptions {
+    content: string;
+    sourceLang: string;
+    targetLang: string;
+    format?: DocumentFormat;
+    glossaryPath?: string;
+    qualityThreshold?: number;
+    maxIterations?: number;
+    context?: string;
+    /** Per-language style instruction (e.g., "경어체", "です・ます調"). Falls back to config.languages.styles[targetLang] if not specified. */
+    styleInstruction?: string;
+    /** If true, throw error when quality threshold is not met */
+    strictQuality?: boolean;
+    /** If true, throw error when glossary terms are missed */
+    strictGlossary?: boolean;
+}
+declare class TranslationEngine {
+    private config;
+    private provider;
+    private verbose;
+    private cache;
+    private cacheHits;
+    private cacheMisses;
+    constructor(options: TranslationEngineOptions);
+    /**
+     * Translate a single file/content
+     */
+    translateContent(options: TranslateFileOptions): Promise<DocumentResult>;
+    /**
+     * Check glossary compliance for the entire document
+     */
+    private checkDocumentGlossaryCompliance;
+    private translateMarkdown;
+    private translatePlainText;
+    private translateChunk;
+    private detectFormat;
+}
+declare function createTranslationEngine(options: TranslationEngineOptions): TranslationEngine;
+declare function translateText(content: string, sourceLang: string, targetLang: string, options?: {
+    provider?: LLMProvider;
+    glossaryPath?: string;
+    qualityThreshold?: number;
+    maxIterations?: number;
+    verbose?: boolean;
+}): Promise<string>;
+
+interface ParsedDocument {
+    /** Original markdown content */
+    original: string;
+    /** AST representation */
+    ast: Root;
+    /** Extracted text nodes for translation */
+    textNodes: TextNode[];
+}
+interface TextNode {
+    /** Unique identifier for this node */
+    id: string;
+    /** Text content to translate */
+    content: string;
+    /** Node type in AST */
+    type: string;
+    /** Position in source document */
+    position?: {
+        start: {
+            line: number;
+            column: number;
+            offset?: number;
+        };
+        end: {
+            line: number;
+            column: number;
+            offset?: number;
+        };
+    };
+    /** Path to node in AST (for restoration) */
+    path: number[];
+    /** Whether this node should be translated */
+    translatable: boolean;
+}
+interface TranslationMap {
+    [nodeId: string]: string;
+}
+/**
+ * Parse markdown content and extract translatable text nodes
+ */
+declare function parseMarkdown(content: string): Promise<ParsedDocument>;
+/**
+ * Apply translations to AST and stringify back to markdown
+ */
+declare function applyTranslations(document: ParsedDocument, translations: TranslationMap): Promise<string>;
+/**
+ * Get only translatable text from a parsed document
+ */
+declare function getTranslatableText(document: ParsedDocument): string[];
+/**
+ * Create a translation map from an array of translations
+ * (in same order as getTranslatableText output)
+ */
+declare function createTranslationMap(document: ParsedDocument, translations: string[]): TranslationMap;
+/**
+ * Extract full text content for translation (preserving structure markers)
+ *
+ * Processing order is important:
+ * 1. First, handle fenced code blocks (must be at line start with newline after opener)
+ * 2. Then, handle multi-backtick inline code (for examples like ` ```js...``` `)
+ * 3. Then, handle single-backtick inline code
+ * 4. Finally, handle link URLs
+ */
+declare function extractTextForTranslation(content: string): {
+    text: string;
+    preservedSections: Map<string, string>;
+};
+/**
+ * Restore preserved sections after translation
+ *
+ * Uses flexible regex matching to handle cases where LLM may have:
+ * - Added spaces around placeholders
+ * - Changed case
+ * - Added extra underscores
+ */
+declare function restorePreservedSections(translatedText: string, preservedSections: Map<string, string>): string;
+/**
+ * Simple markdown translation that preserves structure
+ * This is the main function to use for translating markdown content
+ */
+declare function translateMarkdownContent(content: string, translateFn: (text: string) => Promise<string>): Promise<string>;
+
+/**
+ * Approximate token count for a given text.
+ * This is a rough estimate - actual token counts may vary by model.
+ *
+ * Rules of thumb:
+ * - English: ~4 characters per token
+ * - CJK (Korean, Japanese, Chinese): ~1.5 characters per token
+ * - Code: ~3.5 characters per token
+ */
+declare function estimateTokens(text: string): number;
+/**
+ * Check if text exceeds a token limit
+ */
+declare function exceedsTokenLimit(text: string, limit: number): boolean;
+/**
+ * Truncate text to approximately fit within a token limit
+ */
+declare function truncateToTokenLimit(text: string, limit: number): string;
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface LoggerConfig {
+    level: LogLevel;
+    quiet: boolean;
+    json: boolean;
+}
+declare function configureLogger(options: Partial<LoggerConfig>): void;
+declare const logger: {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    success(message: string): void;
+    progress(current: number, total: number, message: string): void;
+};
+declare function createTimer(): {
+    elapsed: () => number;
+    format: () => string;
+};
+
+/**
+ * VitePress Integration Helpers
+ *
+ * Helper functions to auto-generate VitePress i18n configuration
+ * based on translated document structure.
+ *
+ * @example
+ * ```typescript
+ * // docs/.vitepress/config.ts
+ * import { defineConfig } from 'vitepress';
+ * import { generateLocaleConfig } from 'llm-translate/vitepress';
+ *
+ * const locales = await generateLocaleConfig('./docs', {
+ *   defaultLocale: 'en',
+ *   locales: ['ko', 'ja'],
+ * });
+ *
+ * export default defineConfig({ locales });
+ * ```
+ */
+/**
+ * Navigation item with a link
+ * Compatible with VitePress DefaultTheme.NavItemWithLink
+ */
+interface NavItemWithLink {
+    text: string;
+    link: string;
+    activeMatch?: string;
+    rel?: string;
+    target?: string;
+    noIcon?: boolean;
+}
+/**
+ * Navigation item with children
+ * Compatible with VitePress DefaultTheme.NavItemWithChildren
+ */
+interface NavItemWithChildren {
+    text?: string;
+    items: NavItemWithLink[];
+    activeMatch?: string;
+}
+/**
+ * Navigation item type
+ * Compatible with VitePress DefaultTheme.NavItem
+ */
+type NavItem = NavItemWithLink | NavItemWithChildren;
+/**
+ * Sidebar item
+ * Compatible with VitePress DefaultTheme.SidebarItem
+ */
+interface SidebarItem {
+    text?: string;
+    link?: string;
+    items?: SidebarItem[];
+    collapsed?: boolean;
+    base?: string;
+    docFooterText?: string;
+    rel?: string;
+    target?: string;
+}
+/**
+ * Theme configuration
+ * Compatible with VitePress DefaultTheme.Config
+ */
+interface ThemeConfig {
+    nav?: NavItem[];
+    sidebar?: SidebarItem[] | Record<string, SidebarItem[]>;
+    editLink?: {
+        pattern: string;
+        text?: string;
+    };
+    docFooter?: {
+        prev?: string | false;
+        next?: string | false;
+    };
+    outline?: {
+        level?: number | [number, number] | 'deep';
+        label?: string;
+    };
+    lastUpdated?: {
+        text?: string;
+        formatOptions?: Intl.DateTimeFormatOptions;
+    };
+    returnToTopLabel?: string;
+    sidebarMenuLabel?: string;
+    darkModeSwitchLabel?: string;
+    langMenuLabel?: string;
+}
+/**
+ * Locale configuration
+ * Compatible with VitePress LocaleConfig
+ */
+interface LocaleConfig {
+    label: string;
+    lang?: string;
+    link?: string;
+    description?: string;
+    themeConfig?: ThemeConfig;
+}
+/**
+ * Options for generating locale configuration
+ */
+interface GenerateOptions {
+    /** Default locale code (e.g., 'en') */
+    defaultLocale?: string;
+    /** List of locale codes to generate (e.g., ['ko', 'ja']) */
+    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 (default: auto-detect) */
+    sidebarDirs?: string[];
+    /** Use title from file's first heading */
+    useTitleFromHeading?: boolean;
+    /** Custom locale translations */
+    translations?: Record<string, LocaleTranslations>;
+}
+interface LocaleTranslations {
+    editLinkText?: string;
+    docFooter?: {
+        prev: string;
+        next: string;
+    };
+    outline?: {
+        label: string;
+    };
+    lastUpdated?: {
+        text: string;
+    };
+    returnToTopLabel?: string;
+    sidebarMenuLabel?: string;
+    darkModeSwitchLabel?: string;
+}
+/**
+ * Auto-detect available locales by scanning for locale directories
+ */
+declare function detectLocales(docsDir: string, defaultLocale?: string): string[];
+/**
+ * Auto-detect sidebar directories by looking at root structure
+ */
+declare function detectSidebarDirs(docsDir: string): string[];
+/**
+ * Generate locale configuration for a specific locale
+ */
+declare function generateLocale(docsDir: string, locale: string, options?: GenerateOptions): LocaleConfig;
+/**
+ * Generate complete locale configuration for VitePress
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig } from 'vitepress';
+ * import { generateLocaleConfig } from 'llm-translate';
+ *
+ * const locales = generateLocaleConfig('./docs', {
+ *   defaultLocale: 'en',
+ *   locales: ['ko', 'ja'],
+ * });
+ *
+ * export default defineConfig({
+ *   locales,
+ *   // ... other config
+ * });
+ * ```
+ */
+declare function generateLocaleConfig(docsDir: string, options?: GenerateOptions): Record<string, LocaleConfig>;
+/**
+ * Generate sidebar configuration only
+ *
+ * Useful when you want to manually configure nav but auto-generate sidebar.
+ */
+declare function generateSidebarConfig(docsDir: string, options?: Omit<GenerateOptions, 'descriptions' | 'translations'>): Record<string, Record<string, SidebarItem[]>>;
+
+export { type CacheEntry, type CacheIndex, type CacheKey, CacheManager, type CacheMetadata, type CacheOptions, type CacheResult, type CacheStats, type ChatMessage, type ChatRequest, type ChatResponse, type Chunk, type ChunkResult, type ChunkingConfig, ClaudeProvider, CompositePolicy, type DocumentFormat, type DocumentResult, ErrorCode, ExitCode, type GenerateOptions, type Glossary, GlossaryChangePolicy, type GlossaryTerm, type InvalidationContext, type InvalidationPolicy, type InvalidationResult, type LLMProvider, type LocaleConfig, type LocaleTranslations, type ModelInfo, type NavItem, type NavItemWithChildren, type NavItemWithLink, ProviderChangePolicy, type ProviderConfig, type ProviderName, type QualityEvaluation, QualityThresholdPolicy, type ResolvedGlossary, type ResolvedGlossaryTerm, type SidebarItem, TTLPolicy, type ThemeConfig, type TranslateConfig, TranslationAgent, TranslationEngine, TranslationError, type TranslationRequest, type TranslationResult, applyTranslations, checkGlossaryCompliance, chunkContent, configureLogger, createCacheManager, createClaudeProvider, createDefaultPolicies, createGlossaryLookup, createMinimalPolicies, createNullCacheManager, createProviderWithFallback, createStrictPolicies, createTimer, createTranslationAgent, createTranslationEngine, createTranslationMap, detectLocales, detectSidebarDirs, estimateTokens, exceedsTokenLimit, extractTextForTranslation, generateCacheKey, generateLocale, generateLocaleConfig, generateSidebarConfig, getAvailableProviders, getChunkStats, getExitCode, getProvider, getProviderConfigFromEnv, getTranslatableText, hasProvider, hashContent, isErrorCode, isTranslationError, loadConfig, loadGlossary, logger, mergeConfig, parseMarkdown, reassembleChunks, registerProvider, resolveGlossary, restorePreservedSections, translateMarkdownContent, translateText, truncateToTokenLimit };