# gyunggyung/docling-translate architecture

> Architecture diagram of the GitHub repository gyunggyung/docling-translate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gyunggyung/docling-translate
- Repository: https://github.com/gyunggyung/docling-translate

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        CLI["CLI (main.py)"]:::ui
        WebUI["Web UI (Streamlit app.py)"]:::ui
    end

    %% Core Pipeline
    subgraph "Pipeline Core"
        Core["Core Translation Engine\n(src/core.py)"]:::internal
        Parse["Document Parser\n(Docling)"]:::internal
        Map["Sentence Mapper"]:::internal
        Manager["Translation Engine Manager\n(src/translation/base.py)"]:::internal
        Generate["HTML/Interactive Viewer Generator\n(src/html_generator.py)"]:::internal
    end

    %% Translation Plugins
    subgraph "Translation Plugins"
        Utils["Translation Utilities\n(src/translation/utils.py)"]:::internal
        Deepl["DeepL Plugin\n(src/translation/engines/deepl.py)"]:::internal
        Google["Google Plugin\n(src/translation/engines/google.py)"]:::internal
        Gemini["Gemini Plugin\n(src/translation/engines/gemini.py)"]:::internal
        OpenAI["OpenAI Plugin\n(src/translation/engines/openai.py)"]:::internal
    end

    %% External APIs
    subgraph "External APIs"
        DeepLAPI[(DeepL API)]:::external
        GoogleAPI[(Google API)]:::external
        GeminiAPI[(Gemini API)]:::external
        OpenAIAPI[(OpenAI API)]:::external
    end

    %% Supporting Components
    subgraph "Supporting Components"
        I18n["Internationalization Helpers\n(src/i18n.py)"]:::internal
        UtilsShared["Shared Utilities\n(src/utils.py)"]:::internal
        Benchmark["Performance Benchmark\n(src/benchmark.py)"]:::internal
        Env["Environment Template\n(.env.example)"]:::fs
        Config["Streamlit Config\n(.streamlit/config.toml)"]:::fs
    end

    %% Filesystem & Docs
    subgraph "Filesystem & Docs"
        FS["Local File System"]:::fs
        Docs["Documentation (docs/)"]:::fs
        Samples["Sample Documents (samples/)"]:::fs
    end

    %% Data Flow
    CLI -->|Document Blob| Core
    WebUI -->|Document Blob| Core

    Core -->|Parsed Structure| Parse
    Parse -->|Sentence List| Map
    Map -->|Mapped Sentences| Manager
    Manager -->|Translation Requests| Utils
    Utils --> Deepl
    Utils --> Google
    Utils --> Gemini
    Utils --> OpenAI

    Deepl -->|API Call| DeepLAPI
    Google -->|API Call| GoogleAPI
    Gemini -->|API Call| GeminiAPI
    OpenAI -->|API Call| OpenAIAPI

    Manager -->|Translated Segments| Generate
    Generate -->|HTML Output| FS
    Generate -->|Streamed HTML| WebUI

    Core -->|i18n strings| I18n
    Core -->|helpers| UtilsShared

    Benchmark -->|runs on| Core
    Env -->|configures| DeepLAPI
    Env -->|configures| GoogleAPI
    Env -->|configures| GeminiAPI
    Env -->|configures| OpenAIAPI

    Docs -->|guides| CLI
    Docs -->|guides| WebUI
    Samples -->|test inputs| Core

    %% Click Events
    click CLI "https://github.com/gyunggyung/docling-translate/blob/main/main.py"
    click WebUI "https://github.com/gyunggyung/docling-translate/blob/main/app.py"
    click Config "https://github.com/gyunggyung/docling-translate/blob/main/.streamlit/config.toml"
    click Core "https://github.com/gyunggyung/docling-translate/blob/main/src/core.py"
    click Manager "https://github.com/gyunggyung/docling-translate/blob/main/src/translation/base.py"
    click Utils "https://github.com/gyunggyung/docling-translate/blob/main/src/translation/utils.py"
    click Deepl "https://github.com/gyunggyung/docling-translate/blob/main/src/translation/engines/deepl.py"
    click Google "https://github.com/gyunggyung/docling-translate/blob/main/src/translation/engines/google.py"
    click Gemini "https://github.com/gyunggyung/docling-translate/blob/main/src/translation/engines/gemini.py"
    click OpenAI "https://github.com/gyunggyung/docling-translate/blob/main/src/translation/engines/openai.py"
    click Generate "https://github.com/gyunggyung/docling-translate/blob/main/src/html_generator.py"
    click I18n "https://github.com/gyunggyung/docling-translate/blob/main/src/i18n.py"
    click UtilsShared "https://github.com/gyunggyung/docling-translate/blob/main/src/utils.py"
    click Benchmark "https://github.com/gyunggyung/docling-translate/blob/main/src/benchmark.py"
    click Env "https://github.com/gyunggyung/docling-translate/blob/main/.env.example"
    click Docs "https://github.com/gyunggyung/docling-translate/tree/main/docs/"
    click Samples "https://github.com/gyunggyung/docling-translate/tree/main/samples/"

    %% Styles
    classDef ui fill:#c6f6d5,stroke:#2f855a,stroke-width:1px;
    classDef internal fill:#bee3f8,stroke:#2b6cb0,stroke-width:1px;
    classDef external fill:#fed7aa,stroke:#dd6b20,stroke-width:1px;
    classDef fs fill:#e2e8f0,stroke:#4a5568,stroke-width:1px;
```
