How pdfmathtranslate/pdfmathtranslate-next works
Project Type and Purpose
• PDFMathTranslate (pdf2zh-next) is a full-stack, Python-based PDF translation tool. It exposes:
a. A command-line interface (CLI) for batch translation of scientific PDFs.
b. An interactive WebUI (via Gradio or similar) for real-time use.
c. A Dockerized deployment for ease of installation.
d. An HTTP API endpoint for integration into other services.
• Core purpose: parse PDF layouts (text, formulas, images), translate content via pluggable translator backends, and reassemble bilingual PDF preserving original formatting.
File Structure Analysis
• Top-level:
• Dockerfile + script/ for container images (China, Demo).
• pyproject.toml, setup.cfg: packaging config.
• mkdocs.yml + docs/: multi-language documentation site.
• Python package pdf2zh_next/:
• config/: CLI/env/model definitions and loading.
• main.py, high_level.py: orchestration entrypoints.
• gui.py: launches WebUI.
• http_api.py: HTTP server endpoints.
• translator/:
– base_translator.py, base_rate_limiter.py, cache.py
– rate_limiter/: QPS limiter implementations
– translator_impl/: one module per supported backend (OpenAI, Azure, Google, DeepL, etc.)
• utils/asynchronize/: asynchronous task utilities.
• tests/ and test/: unit and integration tests for config, cache, translator.
Architecture Highlights from README
• Plugin-style translator backends, selected at runtime.
• Support for multiple translation services and language codes.
• Three usage modes (CLI, WebUI, HTTP API).
a. Main Components
• Clients:
– CLI client (python -m pdf2zh_next.main)
– WebUI client (browser)
• Application server:
– CLI entrypoint (main.py)
– WebUI server (gui.py)
– HTTP API server (http_api.py)
• Core Orchestrator (high_level.py): document parsing, translation workflow.
• PDF Parser modules: Pdfminer.six, PyMuPDF integrations.
• Translator layer:
– Strategy pattern: base_translator + translator_impl plugins
– Rate limiter + cache subcomponents
• External Services: translation APIs (OpenAI, Azure, Google, Deepl, etc.)
• Output module: reassemble PDF, bilingual comparison, preserve formulas/images.
• Configuration store: CLI args, env vars, pyproject / config models.
b. Relationships & Data Flow
1. User → selects mode (CLI/WebUI/HTTP).
2. Entrypoint loads configuration.
3. Entrypoint calls orchestrator:
– Parse input PDF → internal representation (text blocks, formulas, figures).
– For each text segment: check cache → if miss, select translator_impl → apply rate limiter → call external API → update cache.
4. Merge translated segments with original layout → generate bilingual PDF.
5. Return/download result (stdout file path, WebUI preview, HTTP response).
c. Architectural Patterns
• Strategy pattern for translator backends.
• Decorator-like rate limiting and caching wrappers.
• Asynchronous task management for parallel translations.
• Modular separation: parsing, translation, output, UI/APIs.
d. Key Technologies
• Python 3, asyncio
• Pdfminer.six, PyMuPDF
• HTTP framework (FastAPI or Flask inside http_api.py)
• Gradio or similar for gui.py
• Docker for containerization
• mkdocs for documentation site