PDFMathTranslate

Translates PDF scientific documents while maintaining original layout, columns, spacing, and positioning through a five-stage pipeline: PDF parsing via PDFConverterEx/PDFPageInterpreterEx for structure detection, content classification (text/formula/figure/table), AI-powered translation with caching, and document reconstruction via PyMuPDF with font injection. Uses font pattern matching to detect and preserve mathematical formulas during translation, preventing corruption of equations and special symbols.

Abstracts 24+ translation services (Google Translate, DeepL, OpenAI, Anthropic, Ollama, etc.) behind a unified BaseTranslator interface, routing requests based on configuration and cost optimization. Implements SQLite-based translation cache that stores previously translated segments, reducing redundant API calls and costs. Supports custom prompts per service and batch processing via thread pools for parallel translation of document segments.

SQLite-based translation cache (TranslationCache class) stores previously translated segments with metadata (source text, target language, service, timestamp). Implements exact-match deduplication to avoid re-translating identical phrases, reducing API costs and improving performance. Cache is persistent across sessions and supports cache invalidation, statistics tracking, and cost analysis per service.

PDFConverterEx and PDFPageInterpreterEx classes parse PDF structure to extract text with precise spatial coordinates, column detection, and reading order inference. Uses PyMuPDF's layout analysis to identify text blocks, figures, tables, and headers/footers, enabling content-aware translation that respects document structure. Handles complex layouts (multi-column, rotated text, overlapping elements) through geometric analysis.

Implements comprehensive exception handling throughout translation pipeline with automatic fallback strategies: if primary translation service fails, automatically retries with secondary service; if PDF parsing fails, attempts alternative parsing methods; if font embedding fails, falls back to system fonts. Logs detailed error context for debugging and provides user-friendly error messages.

Centralized configuration system (pdf2zh/config.py) supporting YAML/JSON configuration files, environment variables, and command-line arguments with hierarchical precedence. Enables users to configure translation services, custom prompts, font paths, cache settings, thread pool size, and logging without modifying code. Configuration is validated on load and provides helpful error messages for invalid settings.

Classifies PDF content into four categories (text, mathematical formulas, figures, tables) using font pattern matching and layout heuristics, then applies service-specific handling: text gets translated, formulas/figures/tables are preserved as-is or minimally modified. Uses TranslateConverter class with font exception handling to detect mathematical notation (subscripts, superscripts, special Unicode ranges) and prevent translation of non-translatable elements.

Exposes PDFMathTranslate as a Model Context Protocol (MCP) server via pdf2zh/mcp.py, allowing LLM applications (Claude, ChatGPT with MCP support) to invoke translation operations as native tools. Implements MCP resource and tool schemas for document upload, translation configuration, and result retrieval, enabling seamless integration into agentic workflows without custom API wrappers.

Provides five distinct entry points for the same translation engine: CLI (pdf2zh/__main__.py) for batch scripting, Gradio-based Web GUI (pdf2zh/gui.py) for interactive use, Flask HTTP API (pdf2zh/api.py) for service integration, Python API for programmatic access, and Docker containers for containerized deployment. All interfaces share the same core translate() and translate_stream() functions, enabling consistent behavior across deployment models.

Provides Zotero plugin that intercepts PDF imports and automatically translates documents while preserving bibliography metadata, citations, and reference formatting. Integrates with Zotero's document management system to store both original and translated PDFs, enabling researchers to maintain bilingual reference libraries without manual file management.

Implements translate_stream() function that yields translated segments progressively rather than buffering entire document, enabling real-time progress feedback and memory-efficient processing of large PDFs. Reconstructs PDF incrementally as segments complete translation, allowing users to see partial results before full document finishes processing.

Manages font substitution and injection for target languages, detecting missing glyphs and automatically selecting appropriate fonts from system or bundled font library. Supports CJK (Chinese, Japanese, Korean), Cyrillic, Arabic, and other scripts by embedding fonts into reconstructed PDFs, ensuring translated documents render correctly regardless of system font availability.

Allows users to define custom prompts for each translation service (OpenAI, Anthropic, Ollama, etc.) to control translation style, terminology, and domain-specific handling. Prompts are stored in configuration files and applied per-segment, enabling fine-grained control over translation quality without modifying code. Supports prompt templating with variables for context (document title, language pair, segment number).

Implements multi-threaded translation execution via thread pool in translation engine, allowing parallel processing of document segments across multiple CPU cores. Configurable thread count balances parallelism against API rate limits and memory usage. Handles thread-safe access to translation cache and manages concurrent API requests to avoid rate limiting.