# manga-translator-ui: a desktop pipeline that detects, translates and re-letteres manga pages > A GPL-3.0 Python desktop tool built on manga-image-translator, with a Qt editor and a Docker web mode. It is strongest when you want to fix the lettering by hand after the AI pass. **hgmzhn/manga-translator-ui** — 基于manga-image-translator 实现的开源漫画AI翻译桌面工具。支持日、韩、英文漫画自动处理，集成OpenAl、Gemini等多翻译引擎；实现OCR文字检测、原文擦除、AI翻译、图像修复、译文排版完整链路，自带可视化编辑器，支持自定义文本样式，一键部署开箱即用。 - Repository: https://github.com/hgmzhn/manga-translator-ui - Stars: 2,904 · Forks: 138 - Language: Python - License: GPL-3.0 - Published: 2026-09-14 · Updated: 2026-09-14 · Language: en - Canonical page: https://hysenlabs.com/projects/hgmzhn-manga-translator-ui ## What manga-translator-ui actually takes off your plate The tedious part of scanlation is not the translation. It is finding every bubble, erasing the original glyphs cleanly enough that the artwork underneath survives, and then fitting a longer target-language string back into a shape that was drawn for a shorter one. manga-translator-ui exists to chain those steps in one desktop window. The README describes the chain as detect, OCR, translate, erase, letter, and the repository is organised around that: a manga_translator package for the pipeline, a desktop_qt_ui package for the editor, and a fonts directory for the typefaces you letter with. The intended user is a single translator or a small group working through chapters on their own machine, not a platform serving requests. That shows in the choices: the primary distribution channel is a portable Windows package, the editor is a Qt desktop application rather than a web form, and the Docker mode is labelled experimental in the README. If you want a hosted service where users upload a page and get a file back, this is the wrong shape of tool. ## The pipeline: detection, OCR, translation, inpainting, typesetting The stages are separable, and the README names the models behind several of them. Text detection and bubble segmentation are handled by models including MangaLens Bubble Segmentation, with YOLO OBB detection listed in pyproject.toml through the ultralytics dependency. OCR is not one engine but a choice: PaddleOCR, MangaOCR, or PaddleOCR-VL-1.5. Translation is likewise pluggable, with OpenAI, Gemini, Vertex and Sakura named as engines, and a separate high-quality path that uses multimodal models such as GPT-4o and Gemini. After translation comes the part most pipelines skip. The original text is erased and the region is repaired with inpainting models, and the README lists Real-CUGAN, MangaJaNai and YSG among the models involved. Then the translated string is laid back into the bubble. That lettering step has three modes named in the README: smart bubble, smart scaling, and strict boundary, plus toggles for centring inside the bubble and for bubble-driven layout. Line breaking is treated as its own problem. For Chinese output the project runs a local HanLP model to pick semantically sensible break points, and the README states that when the model is missing it falls back to ordinary line breaking. There is also an AI-based sentence splitting option that uses context. Vertical and horizontal writing is decided automatically per text block, which matters because a Japanese page and its English replacement rarely want the same orientation. None of this is a single model doing everything; it is a sequence of specialised stages with configuration between them. ## Installing on Linux or macOS and translating one page The README gives one shared install script for Linux and macOS. It downloads the script, makes it executable and runs it, which resolves the dependency group for your hardware. The README says Linux picks NVIDIA, AMD ROCm or CPU automatically, and Apple Silicon uses Metal/MPS. ```bash 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 ``` When the script finishes, start the application with the companion script. The same script is also the updater, so re-running it pulls new code and dependencies. ```bash ./Unix-Start.sh ``` On Windows the README recommends the portable package that bundles Python and the model files. You extract it, run Win-Install-or-Update.bat, then launch Win-Start.bat; updating means choosing option [2] in the install menu. Windows users are told to install the Microsoft Visual C++ redistributable first. The README also gives a hardware constraint worth reading before you download: GeForce 10 series must use CUDA 12.6, and RTX 50 series must use CUDA 13.0, with a driver update if the package does not match. For a first task, the README's Qt workflow is: open the program, choose source language, target language and translator, and fill in an API key if you picked an online engine. Then point it at a folder. Batch processing takes a whole directory at once. After the run, open the result in the visual editor, where you can move and rotate text boxes, adjust font size, colour, stroke and spacing per box, and compare against the original in a two-column view. The README lists the editor shortcuts, including A and D to move between images, V to toggle vertical or horizontal writing on the selected box, Ctrl+A to select all boxes, Ctrl+S to save project data and Ctrl+Q to export the image. ## Docker mode, and why the README calls it experimental There is a container path, and the README labels it experimental. The documented command maps port 8000 and attaches named volumes so that models, fonts, dictionaries, config, account data, logs and results survive container deletion. ```bash 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 ``` After it starts you reach a web interface at http://localhost:8000, and the README says the web UI provides account and quota management. The tag in the example is the CPU image. The README directs you to the deployment documentation if you need GPU access or want host directories instead of named volumes. Treat the experimental label as real. The desktop editor is the part of this project with the most surface area, and a browser session reached over port 8000 is not the same experience as the Qt application. If your goal is a shared instance for several people, the account and quota features suggest that is the direction, but the README does not document hardening, reverse proxying or backup for that deployment. ## Where the project gets thin: model downloads, GPU class and rollback The honest limitation is that this is a large local stack, and the README is explicit that the portable package ships Python dependencies and model files inside it. That is convenient on Windows and heavy everywhere else. On Linux and macOS the install script has to fetch and resolve those models, and the README does not document what happens when a download fails halfway or how to verify a model's integrity. The hardware matrix is another place where the tool is less forgiving than a hosted service. The README ties CUDA versions to GPU generations: GeForce 10 series to CUDA 12.6, RTX 50 series to CUDA 13.0. If your card falls outside those pairings, the documented answer is to update the NVIDIA driver, not to pick a different build. There is no documented CPU-only quality note either; the CPU group exists in pyproject.toml, but the README does not say how detection or inpainting quality changes without a GPU. Upgrade and rollback are the weakest documented area. The README explains how to update the portable package and how to switch versions, but it does not describe how to return to a previous release if a new one breaks your configuration, and it does not document a migration path for project files saved by an older version. The release cadence is fast, with v3.0.2, v3.0.3 and v3.0.4 all published within about three weeks in August and September 2026, so a saved project from one release meeting a later release is a realistic scenario. Back up your config and project files before updating. ## How it differs from running manga-image-translator directly The upstream project, manga-image-translator, is the obvious alternative, and the README states plainly that this tool is built on it. The difference is not the models. It is where the human sits in the loop. Upstream is a pipeline you drive from a command line or an API. You get translated images and, if you want to correct a bad line break or a bubble the detector missed, you take the output elsewhere. manga-translator-ui wraps that pipeline in a Qt application whose centre of gravity is the editor: region editing with move, rotate and transform, per-box typography, mask editing with brush, eraser and clone stamp, multi-select alignment and distribution, undo and redo, and export to PSD with the original, the repaired image and the text on separate layers. It also adds batch management that matches regions by condition, previews hits before applying, and backs up before writing back. That is a real trade. You take on a desktop dependency, a heavier install and a GUI codebase in exchange for being able to fix the output without leaving the tool. If your workflow already ends in Photoshop or Krita, the editor is less valuable and upstream is the lighter choice. If your workflow is one person correcting pages late at night, the editor is the reason to pick this fork. ## Licence and the cost of keeping it current The repository is GPL-3.0, stated in the README badge and in LICENSE.txt. For private use that changes nothing. For distribution it matters: if you ship a modified version, or bundle this into something you hand to other people, the GPL-3.0 obligations attach to that distribution. The README does not offer an alternative licence or a commercial exception, so there is no dual-licensing escape hatch documented here. This is a description of the licence, not legal advice; read LICENSE.txt and talk to someone qualified if you plan to redistribute. The maintenance cost is mostly disk and bandwidth rather than code. The portable package bundles Python and the models, and the Docker setup expects named volumes for models, fonts, dictionaries and config. Those volumes grow, and the README's update instructions replace code and dependencies without discussing volume cleanup. The last push to the repository was on 2026-09-06, and v3.0.4 was released the same day, so the project is being worked on, but that also means the configuration surface moves. The README points to a settings index page for per-option documentation, which is where you should look before assuming a setting means what its name suggests. ## Conclusion Adopt it if you translate Japanese, Korean or English pages yourself and want the detection, erasing and lettering steps in one window with a manual editor on top. Skip it if you need an unattended service that never asks a human to review a bubble, or if a GPL-3.0 obligation on your own distribution is a problem. Before committing, run the Linux or macOS installer on a single chapter and check whether the bundled HanLP segmentation model loads, because the README says the fallback is plain line breaking when it is missing. ## FAQ ### Is translating manga legal? The repository does not address the legality of translating or distributing manga. It ships under GPL-3.0, which covers the software, not the images you run through it. Whether you may translate or redistribute a given work is a separate question the project is silent on. ### What is the best manga translator? The README does not rank tools and makes no claim about being the best. It does document that translation engines are pluggable, naming OpenAI, Gemini, Vertex and Sakura, with a high-quality path for GPT-4o and Gemini. The right engine depends on which API keys you have. ### What font do manga translators use? The README does not prescribe a typeface. It states that font management supports system fonts and custom fonts placed in the fonts/ directory, and that the editor lets you set font size, colour, stroke and spacing per text box. ### Does a manga translator get paid? The repository contains no information about payment for translation work. The README mentions an optional donation link for the author and nothing about compensating translators who use the tool. ## Sources - [hgmzhn/manga-translator-ui on GitHub](https://github.com/hgmzhn/manga-translator-ui) - [Issues](https://github.com/hgmzhn/manga-translator-ui/issues) - [License: GPL-3.0](https://github.com/hgmzhn/manga-translator-ui/blob/main/LICENSE) - [README](https://github.com/hgmzhn/manga-translator-ui/blob/main/README.md) - [Releases](https://github.com/hgmzhn/manga-translator-ui/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hgmzhn-manga-translator-ui