# luckysongxiao/ppt-text-translation architecture

> Architecture diagram of the GitHub repository luckysongxiao/ppt-text-translation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/luckysongxiao/ppt-text-translation
- Repository: https://github.com/luckysongxiao/ppt-text-translation

## Overview

##### Project Type and Purpose
- The project is a specialized translation tool for PowerPoint files (PPT/PPTX) that supports bidirectional Chinese-English translation combined with dedicated terminology management.
- It offers both offline and online translation models, a web-based UI (via Gradio), and configuration/record handling.
- The README confirms that its focus is on improving translation efficiency though human verification is still needed.

##### Analyzing the File Tree – Key Components
- Top-level files like main.py and requirements.txt indicate a Python-based command line entry point.
- The data directory with config.json suggests centralized configuration management.
- The src folder further structures the application:
- src/api: Contains API client modules (ollama_client.py, zhipuai_client.py) that abstract calls to translation backends.
- src/core: Consists of core translation logic including modules like translator.py, prompt_manager.py, and terminology.py, which together manage the translation process and language-specific customization.
- src/ui: Holds the Gradio-based web interface (gradio_app.py) and additional user interface components (terminology_manager_ui.py) to manage translation settings and terminology.
- src/json: Contains a JSON file that likely maintains the terminology database.
- src/utils: Provides utility modules (config.py) for managing configuration loading and any global settings.
- src/output and src/user_data: Appear to be directories for storing exported translation logs and user data, respectively.

##### Main Components and Their Relationships
a. Frontend / User Interface:
- Gradio-based web UI (within src/ui) serves as the primary user interaction layer.
- It interacts closely with the translation engine by sending user input (PPT file, translation settings) and displaying progress and results.
b. Core Translation Engine:
- Located in src/core, it contains:
- The translator module that orchestrates the translation process.
- The prompt_manager, which likely formats requests for translation.
- The terminology module that applies language-specific or industry-specific terminology adjustments.
c. API Clients / Integration Layer:
- Within src/api, modules communicate with external or local translation models:
- zhipuai_client.py for online models.
- ollama_client.py for offline/local translation setups.
d. Configuration and Terminology Data:
- The project reads configuration from data/config.json and houses language/terminology specifics in src/json/terminology.json.
e. Utility and Support Layers:
- Utility functions in src/utils help manage configs, logging, or error handling.
- Output and user data directories store logs or exported translation records.
f. Entry Point:
- main.py serves to initialize the system, load configurations, start the web server, and integrate the components.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Different directories clearly delineate API integration, core business logic, UI components, and utility functions.
- Modular Design: Each functional unit (translation core, API wrappers, UI) exists as an independent module, making it easy to swap or extend translation models.
- Clear Data Flow: The front end initiates requests that pass through the core translation engine before invoking the appropriate API client.
- Config & Data Abstraction: External configs and terminology databases are stored in JSON files, simplifying updates without modifying core logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    subgraph "Entry Point"
        ME("main.py"):::entry
    end

    %% Configuration & Data
    subgraph "Configuration & Data"
        CD("Configuration Data"):::config
        TD("Terminology Data"):::config
    end

    %% Utility Modules
    subgraph "Utility Modules"
        UT("Utility (config.py)"):::utility
    end

    %% Translation Core
    subgraph "Translation Core"
        TR("Translator Module"):::core
        PM("Prompt Manager"):::core
        TH("Terminology Handler"):::core
    end

    %% API Clients
    subgraph "API Clients"
        OC("Ollama Client"):::api
        ZC("Zhipuai Client"):::api
    end

    %% User Interface
    subgraph "User Interface"
        GW("Gradio Web UI"):::ui
        TM("Terminology Manager UI"):::ui
    end

    %% Data/Output Management
    subgraph "Data/Output Management"
        OL("Output Logs/Exports"):::data
        UD("User Data"):::data
    end

    %% Connections
    ME -->|"load_config"| CD
    ME -->|"start_UI"| GW
    ME -->|"init_utility"| UT

    CD -->|"config_fetch"| TR
    TD -->|"terminology_fetch"| TH
    UT -->|"support"| TR

    GW -->|"translation_request"| TR
    TM -->|"UI_settings"| TR

    TR -->|"uses"| PM
    TR -->|"uses"| TH

    TR -->|"API_call"| OC
    TR -->|"API_call"| ZC
    OC -->|"result_feedback"| TR
    ZC -->|"result_feedback"| TR

    TR -->|"return_translation"| GW
    TR -->|"export_logs"| OL
    TR -->|"store_user_data"| UD

    %% Click Events
    click ME "https://github.com/luckysongxiao/ppt-text-translation/blob/main/main.py"
    click CD "https://github.com/luckysongxiao/ppt-text-translation/blob/main/data/config.json"
    click OC "https://github.com/luckysongxiao/ppt-text-translation/blob/main/src/api/ollama_client.py"
    click ZC "https://github.com/luckysongxiao/ppt-text-translation/blob/main/src/api/zhipuai_client.py"
    click TR "https://github.com/luckysongxiao/ppt-text-translation/blob/main/src/core/translator.py"
    click PM "https://github.com/luckysongxiao/ppt-text-translation/blob/main/src/core/prompt_manager.py"
    click TH "https://github.com/luckysongxiao/ppt-text-translation/blob/main/src/core/terminology.py"
    click TD "https://github.com/luckysongxiao/ppt-text-translation/blob/main/src/json/terminology.json"
    click GW "https://github.com/luckysongxiao/ppt-text-translation/blob/main/src/ui/gradio_app.py"
    click TM "https://github.com/luckysongxiao/ppt-text-translation/blob/main/src/ui/terminology_manager_ui.py"
    click UT "https://github.com/luckysongxiao/ppt-text-translation/blob/main/src/utils/config.py"
    click OL "https://github.com/luckysongxiao/ppt-text-translation/tree/main/src/output"
    click UD "https://github.com/luckysongxiao/ppt-text-translation/tree/main/src/user_data"

    %% Styles
    classDef entry fill:#F5CBA7,stroke:#D35400,stroke-width:2px;
    classDef config fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef utility fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef core fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef api fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
    classDef ui fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef data fill:#D6EAF8,stroke:#2980B9,stroke-width:2px;
```
