manga-translator-ui/README_EN.md at main · hgmzhn/manga-translator-ui

Translate text in all mainstream manga images with one click — detect → OCR → translate → inpaint → typeset, with a built-in full rich-text editor

Language / 语言: 简体中文 | English

💬 QQ Group: 1079089991 (password: kP9#mB2!vR5*sL1)

Developers are welcome to submit PRs and help improve the project. If you are unsure whether a change fits the project direction, or want to discuss an implementation before coding, open an Issue first. Before submitting, read the PR contribution guidelines.

If you encounter any problem, please open an Issue and include the environment, reproduction steps, logs, or screenshots whenever possible so it can be diagnosed quickly.

If this tool has helped you, you can support the author! Your support is what keeps the project maintained—thank you!

🔗 Friend Link: MTU-JSON-GUI: A Web-based visual typesetting tool built specifically for Manga Translator UI. Beyond text replacement, it includes a geometric layout engine that algorithmically handles alignment, spacing, and perspective issues in manga typesetting.

📸 Results Preview

Before Translation	After Translation

🖥️ Application Interface

Visual Editor

Settings

✨ Core Features

Translation

🔍 Smart text detection - Automatically detects text regions in manga pages
📝 Multilingual OCR - Supports Japanese, Chinese, English, and more
🌐 Multiple translation engines - OpenAI, Gemini, Vertex, and Sakura, including high-quality modes
🎯 High-quality translation - Uses GPT-4o and Gemini multimodal translation
📚 Automatic glossary extraction - Identifies and accumulates proper nouns for consistent translation
🎨 AI colorization / OCR / rendering - Provides multimodal AI image-processing tools
🔑 API key rotation and cooldown - Rotates across multiple keys to reduce rate-limit interruptions

Typesetting and Rich Text

🎈 Smart balloon layout - Fits text inside the balloon shape, with Smart Balloon, Smart Scaling, and Strict Bounds modes plus centering and balloon-layout options (Typesetting and rendering)
✂️ Chinese semantic line breaking - Uses a local HanLP model to choose meaningful line breaks, falls back automatically when unavailable, and can be combined with AI line breaking (Line-breaking settings)
🤖 AI line breaking - Optimizes line breaks from context for better readability
🖋️ Automatic horizontal / vertical detection - Selects the appropriate text direction automatically
🎨 Full rich text - Supports inline bold, color, stroke, font size, ruby, and tate-chu-yoko, with presets and automatic rules (Floating rich-text editor ｜ Rich-text rules)
🧩 Automatic rich-text rules - Applies styles automatically while text is entered
🔤 Font management - Supports system fonts and custom fonts from fonts/

Visual Editor

✏️ Region editing - Move, rotate, and reshape text boxes
📐 Text editing - Edit translations and adjust size, color, stroke, and spacing per box
🖌️ Mask editing - Includes brush, eraser, and clone-stamp tools
🔍 Original comparison - Compare the edited page side by side with the original
📏 Multi-selection layout - Align text boxes and distribute spacing
⏪ Undo / redo - Maintains a complete operation history
⌨️ Keyboard shortcuts - A/D navigate images, 1/2/3 switch the Mask/Paint/Clone Stamp tabs, Q/W/E choose the three tools on the current tab, Ctrl+A selects all regions, Ctrl+S saves project data, Ctrl+Q exports the image, and Ctrl+Shift+R shows/hides the floating rich-text editor
🖱️ Mouse-wheel shortcuts - Resize text boxes and brushes with modifier keys

Batch and Automation

📦 Batch processing - Processes a whole folder in one run
🧰 Batch management - Matches regions by condition, bulk-edits properties or text, applies rich-text styles, previews matches, and supports backup restoration (Guide)
📥 PSD export - Exports original, repaired, and text layers for further editing
🔄 JSON / TXT import and export - Imports, exports, and writes text back
⌨️ Command-line mode - Supports batch jobs and automation scripts
🌐 Web UI - Includes account and quota management
🐳 Docker deployment - Supports containerized operation

📖 Full shortcut reference ｜ Every setting explained

🚀 Quick Start

⚠️ Windows users: install the runtime first: Microsoft Visual C++ Redistributable

Windows

Portable package (⭐ Recommended, supports updates)

No separate Python installation is required. Download the portable package, extract it, run Win-Install-or-Update.bat, then start with Win-Start.bat. Choose [2] Update in the installer menu when updating. 📖 Portable package walkthrough ｜ Updates and version switching

Download a portable release

Download a CPU, CUDA 13.0, CUDA 12.6, or experimental ROCm 7.2.1 build from GitHub Releases, extract it, and run Win-Start.bat. GeForce 10-series GPUs such as the GTX 1060/1070/1080 must use the compatibility build whose filename contains cuda12.6. CUDA 13.0 requires Turing (compute capability 7.5) or newer; RTX 20/30/40/50-series GPUs may use cuda13.0 when the driver supports CUDA 13.0, and it is recommended for RTX 50-series GPUs. Drivers supporting CUDA 13.0 or newer can also run the CUDA 12.6 build. Python dependencies and model files are included. The ROCm 7.2.1 build requires a supported AMD GPU and driver 26.2.2. 📖 Release download notes

Run from source (developers)

For users who need to modify the code, follow the Windows source installation guide.

Linux / macOS

Linux and macOS use the same installer:

mkdir -p ~/manga-translator-ui && cd ~/manga-translator-ui
curl -L -O https://raw.githubusercontent.com/hgmzhn/manga-translator-ui/main/Unix-Install-or-Update.sh
chmod +x Unix-Install-or-Update.sh && ./Unix-Install-or-Update.sh

After installation, start with ./Unix-Start.sh; update code and dependencies with ./Unix-Install-or-Update.sh.

Apple Silicon uses Metal/MPS; Linux automatically selects NVIDIA, AMD ROCm, or CPU dependencies. 📖 Linux and macOS installation

Docker Deployment (Experimental)

docker run -d --name manga-translator -p 8000:8000 --restart unless-stopped -v manga-translator-models:/app/models -v manga-translator-fonts:/app/fonts -v manga-translator-dict:/app/dict -v manga-translator-config:/app/config -v manga-translator-server:/app/manga_translator/server/data -v manga-translator-logs:/app/logs -v manga-translator-result:/app/result hgmzhn/manga-translator:latest-cpu

The named volumes persist models, fonts, dictionaries, configuration, account data, logs, and translation results even if the container is removed. Open http://localhost:8000 after startup; see the deployment guides for GPU support or custom host directories. 📖 Docker deployment ｜ Web UI launch and access

📖 Usage Guide

🖥️ Qt UI Mode

After opening the app, choose the source language, target language, and translator. If you use an online translator, configure its API key first. OpenAI High Quality and Gemini High Quality are recommended for first-time users; choose Vertex High Quality if you want separate Google-official key and model settings.

Set the output directory, add images or a folder, then click Start Translation. Turn off Use GPU when running the CPU build. 📖 Your first translation, step by step

⌨️ CLI Mode

Best for batch processing and automation scripts.

Run these commands from the project root. After dependencies are prepared with uv sync or an installer, no manual virtual-environment activation is required.

# Local mode (recommended for CLI translation)
uv run --no-sync python -m manga_translator local -i manga.jpg

# Short form (defaults to Local mode)
uv run --no-sync python -m manga_translator -i manga.jpg

# Translate a whole folder
uv run --no-sync python -m manga_translator local -i ./manga_folder/ -o ./output/

# Web server mode (with API and admin UI)
uv run --no-sync python -m manga_translator web --host 127.0.0.1 --port 8000 --use-gpu

# Show all arguments
uv run --no-sync python -m manga_translator --help

📖 Need CLI options? View command structure and arguments

📋 Looking for another workflow? View the workflow overview

⚙️ Want to configure every setting? View the settings and parameter reference

🔍 Something went wrong? View troubleshooting

⭐ Star History

🙏 Acknowledgements

Core engine and reference projects

zyddnys/manga-image-translator — core translation engine
dmMaze/BallonsTranslator — text rendering reference
charlespfan/mtu-json-gui — rich text reference

Models and recognition

bilibili/ailab — Real-CUGAN super-resolution model
the-database/MangaJaNai — MangaJaNai / IllustrationJaNai super-resolution models
lhj5426/YSG — model support
huyvux3005/manga109-segmentation-bubble — MangaLens Bubble Segmentation model
PaddleOCR — OCR model support
kha-white/manga-ocr — MangaOCR model support
PaddlePaddle/PaddleOCR-VL-1.5 — official PaddleOCR-VL-1.5 model page

And all the contributors and users who support the project ❤️

❤️ Support the Author

If this project helps you, you are welcome to buy the author a milk tea 🧋

_{💚 WeChat Support}

_{💙 Alipay Support}

_{Thank you for your support ✨}

📝 License

The source code of this project is released under the GPL-3.0 license.

Model license notice: this project also supports MangaJaNai / IllustrationJaNai model weights for image super-resolution. Those model weights use the CC BY-NC 4.0 license and are for non-commercial use only. Model source: MangaJaNai.

⚠️ Special Notice

This project is provided for technical demonstration, personal study, and communication purposes only. It does not constitute legal, commercial, or compliance advice. When installing, configuring, calling, or distributing this project and related features, you are responsible for confirming and continuously complying with local laws, platform rules, content source licenses, and third-party service terms.

Disclaimer and limitation of liability

All actions and consequences resulting from use of this project, including but not limited to content processing, publishing, distribution, redistribution, and commercial use, are the sole responsibility of the user.
You must ensure that your input content, output content, and data sources are legally authorized, and that they are not used in ways that infringe copyright, trademark, privacy, portrait rights, or other lawful rights and interests.
This project must not be used for any illegal or non-compliant purpose, including but not limited to piracy distribution, unauthorized mass scraping or reposting, bypassing platform restrictions, fraud, defamation, or infringement of lawful rights and interests.
This project depends on third-party models, APIs, datasets, and libraries, including OCR, translation, and super-resolution related services. Availability, accuracy, stability, pricing, risk control, and compliance requirements are the responsibility of the corresponding providers, and users bear the related risks and costs.
To the maximum extent permitted by applicable law, the project author and contributors are not liable for any direct or indirect loss arising from the use of or inability to use this project, including but not limited to data loss, business interruption, profit loss, account risk, or third-party claims.
If you use this project in a team or organizational environment, you are responsible for permission management, logging and auditing, content review, compliance assessment, and establishing the necessary human review process.

Please evaluate the risks carefully before use. Continuing to use this project is deemed as having read, understood, and agreed to the statements above.

FilesExpand file tree

README_EN.md

Latest commit

History