$ show hydropix/TranslateBooksWithLLMs
TranslateBooksWithLLMs is a full-stack web application for translating eBooks (EPUB, DOCX, TXT, SRT) using multiple LLM providers (Ollama, OpenAI, Gemini, Mistral, DeepSeek, Poe, OpenRouter, NVIDIA NIM, LiteLLM). The architecture is a Flask server with Socket.IO for real-time progress streaming, a JavaScript SPA frontend with i18n support across 7 locales, and a SQLite-based checkpoint/resume system for interrupted translations. The core pipeline extracts content with HTML/XML placeholder preservation, chunks text using tiktoken-aware splitting, translates via configurable LLM providers with multi-phase fallback (LLM → token alignment → original), and reconstructs the output file. Additional features include glossary management with NER-based term suggestion, style extraction from source text, TTS generation via Edge-TTS and Chatterbox, and a comprehensive benchmark framework for evaluating translation quality across 35+ languages. The codebase demonstrates strong engineering with clean abstractions (adapter pattern for formats, factory pattern for LLM providers, generic orchestrator for translation pipeline), extensive testing (unit, integration, characterization with golden snapshots, e2e), and several genuinely reusable components. Notable patterns include a token-aware chunker with exact reassembly, an API key pool with round-robin rotation on 429 responses, an ordered concurrent executor that preserves chunk ordering, a retry manager with exponential backoff and circuit breaker, and a placeholder system for preserving HTML/XML structure during LLM translation. The benchmark subsystem and prompt optimization tool are supporting features that add research value but are secondary to the core application purpose.
The LLM identified 8 files worth highlighting for reuse:
TokenChunker with soft limit ratio, natural boundary detection (sentence/paragraph), and join_before tracking for exact reassembly. Uses tiktoken for token counting. Reusable for any text chunking task requiring token-aware splitting with deterministic reconstruction.
KeyPool implementing round-robin rotation on HTTP 429 responses with monotonic time for expiry tracking. Generic API key rotation pattern applicable to any rate-limited API service. Includes throttle tracking and failover logic.
iter_ordered_windows and iter_ordered_concurrent functions that preserve chunk ordering while executing concurrent LLM requests. Uses asyncio queues and result tracking to maintain sequential output order. Reusable for any parallel processing task where output order must match input order.
Ok/Err monad implementation with chaining (and_then, map, map_err, unwrap, unwrap_or). Used extensively in the EPUB pipeline for error-safe flows without exceptions. Reusable as a lightweight result type for any Python project.
RetryManager with configurable strategies (exponential, linear, immediate), circuit breaker pattern, and per-error-type configuration. Supports max retries, backoff factors, and jitter. Reusable for any API client requiring robust retry logic.
Centralized PlaceholderFormat class with create, parse, find_all, remove_all, and renumber methods. Supports both legacy tuple format and modern object format. Reusable for any text processing pipeline requiring placeholder preservation and restoration.
Style extractor that uses LLM prompts to derive writing style rules (register, narrative voice, sentence rhythm, lexicon, imagery, dialogue, punctuation, formatting). Features a permissive JSON parser that handles trailing commas, unquoted keys, and nested structures without raising exceptions. Reusable for any LLM-based structured extraction task.
Generates target-language inflection instructions for glossary terms, handling case, number, gender, and verb conjugation across multiple languages. Used to ensure glossary terms are correctly inflected in translated output. Reusable for any multilingual NLP system requiring morphological awareness.