How gyunggyung/docling-translate works
Project Type and Purpose
• This is an open-source, Python-based document translation tool (docling-translate) that provides both a CLI (main.py) and a web UI (app.py via Streamlit).
• It leverages the Docling library to parse complex document structures (PDF, DOCX, PPTX, HTML, images), perform sentence-level mapping, invoke machine-translation engines, and generate an interactive, side-by-side HTML viewer.
File Structure Analysis
• Top-level:
• .agent/: internal planning and workflow drafts
• .streamlit/: Streamlit configuration for the web UI
• app.py, main.py: entrypoints for Web UI and CLI
• src/: core Python package
• docs/: user and contributor documentation
• requirements.txt, .env.example: dependencies and environment variables
• src/ breakdown:
• core.py: orchestrates the translation pipeline
• benchmark.py: performance measurement harness
• html_generator.py: builds the interactive HTML output
• i18n.py, utils.py: internationalization and shared helpers
• translation/: pluggable engines (base.py + deepl.py, gemini.py, google.py, openai.py) and utility functions
README Insights
• Technologies: Python 3.10+, Streamlit for Web UI, Docling for structure analysis, multi-threading via max_workers.
• External dependencies: DeepL, Google Translate, Gemini API, OpenAI GPT-5-nano.
• Features: sentence‐level parallel mapping, layout preservation (tables/images), side-by-side interactive viewer.
a. Main Components
• User Interfaces
– CLI (main.py)
– Web UI (Streamlit app.py)
• Core Translation Engine (src/core.py)
• Document Parser (Docling integration)
• Sentence Mapper
• Translation Engine Manager (pluggable backends)
• HTML/Interactive Viewer Generator (src/html_generator.py)
• External Services (DeepL API, Google API, Gemini API, OpenAI API)
• Local File System (input docs, output HTML, cache/history)
b. Relationships and Data Flow
1. User submits document via CLI or Web UI
2. Core Engine invokes Docling to parse and extract structure
3. Sentences are mapped 1:1 (original ↔ target)
4. Engine Manager dispatches translation requests (multi-threaded) to selected external API(s)
5. Translated segments are merged back into the original structure
6. HTML Generator produces an interactive, side-by-side viewer
7. Output is saved to filesystem and/or streamed back to the Web UI
c. Architectural Patterns & Design Principles
• Pipeline pattern: sequential stages (parse → map → translate → render)
• Plugin pattern for translation engines (base class + engine-specific implementations)
• Single responsibility per module: parsing, mapping, translation, rendering
• Dependency inversion: core engine depends on abstract engine interfaces
d. Key Technologies & Frameworks
• Python 3.10+
• Docling (document structure analysis)
• Streamlit (Web UI)
• Translation APIs: DeepL, Google, Gemini, OpenAI
• Multithreading (concurrent.futures)