manga-translator-ui: a desktop pipeline for manga text replacement

The gap manga-translator-ui fills between OCR output and a finished page

Raw OCR plus a translation API gets you a list of strings. It does not get you a page where the original lettering is gone and the replacement sits inside the bubble. That gap is where most of the manual labour in scanlation lives: erasing the source text without smearing the artwork, then fitting a translated line into a shape that was drawn for a different language.

manga-translator-ui is built on manga-image-translator, which the README credits as the base project. The upstream library handles detection, OCR, translation and rendering. This project adds the parts a person actually sits in front of: a Qt interface, a visual editor for boxes and masks, batch operations across a folder, and a command line mode for scripting. The README describes the flow as detect, OCR, translate, erase, typeset, with a rich text editor built in.

It is for people who will look at the output and fix it. The editor exposes per-box font size, colour, stroke and spacing, plus mask painting, an eraser and a clone stamp. If your goal is unattended translation of thousands of pages with no review step, the editor is dead weight and you are paying for a GUI you will not open.

How the pipeline is assembled, from text detection to bubble fitting

The chain runs in stages. Text detection finds regions, then OCR reads them. The README lists PaddleOCR, MangaOCR and PaddleOCR-VL-1.5 as OCR backends, and states support for Japanese, Chinese and English among others. Translation goes through a selectable engine: OpenAI, Gemini, Vertex, or Sakura, with what the README calls a high quality mode. After translation, the original text is erased and the area repaired, then the translated text is rendered back into the page.

Typesetting is where the project has made specific choices. The README describes three bubble layout modes (smart bubble, smart scaling, strict boundary) plus centring inside the bubble. Line breaking for Chinese can use a local HanLP model to decide breaks semantically, and the README states that when the model is missing it falls back to ordinary line breaking. There is also an AI line-breaking option that uses context. Horizontal and vertical text direction is decided automatically.

The dependency list in pyproject.toml matches this description: ultralytics is present for YOLO OBB and MangaLens bubble detection, hanlp for the semantic line breaking, and the README also credits Real-CUGAN, MangaJaNai and YSG as models. Translation credentials are handled with API key rotation and cooldown, which the README frames as a way to reduce the impact of rate limiting when you have several keys.

Installing manga-translator-ui on Windows, Linux and macOS

Windows users are told to install the Microsoft Visual C++ redistributable first. The recommended path is the portable bundle, which does not require a preinstalled Python. Download the portable archive from the releases page, extract it, run the install-or-update batch file, then start the application with the start batch file. Updates go through option [2] in the install menu.

The README also documents a from-source route for developers, pointing to a separate Windows source install page rather than repeating the steps in the README itself. Linux and macOS share one script. The README gives these commands:

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 it finishes, the README says to start with `./Unix-Start.sh`, and to rerun the same install script to update code and dependencies. On Apple Silicon the project uses Metal/MPS; on Linux the script picks an NVIDIA, AMD ROCm or CPU dependency group. The pyproject.toml mirrors this with mutually exclusive dependency groups, and documents the uv equivalents:

uv sync --no-default-groups --group cpu
uv sync --no-default-groups --group rocm7.2.1
uv sync --no-default-groups --group metal

The default `uv sync` target is NVIDIA CUDA 13.0 plus packaging and test tooling. The project requires Python 3.12 and pins it below 3.13. Note the GPU split in the README: GeForce 10 series must use CUDA 12.6, RTX 50 series must use CUDA 13.0, and the README tells you to update your NVIDIA driver if your card is not supported by the bundle you picked. Get that wrong and the application will not start usefully.

For a first real run in the Qt interface, the README's instruction is to choose source language, target language and translator, then fill in an API key if you are using an online engine. Then point it at an image or a folder. The Docker path is one command:

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 results, so removing the container does not delete them. The README labels Docker deployment as experimental and says GPU or custom host directories require the deployment documentation. Access is at `http://localhost:8000`.

Where manga-translator-ui breaks down or is the wrong tool

The Docker path is the weakest part of the documented surface. The README calls it experimental, and the Web UI is described in terms of account and quota management rather than as a full replacement for the desktop editor. If your plan is to run this as a service behind an API for other people, the README does not promise you that. The CLI mode is mentioned as suitable for batch processing and automation, but the README does not document its flags.

Model downloads are the second constraint. The portable and release bundles ship with Python dependencies and model files, which is convenient but means the download is large and the on-disk footprint grows with the models you enable. Source installs pull their own. The README does not document a rollback procedure for updates, so if a new version regresses on your pages, the documented recovery is limited to version switching described in the install documentation.

Quality is bounded by the engine you choose. Local Sakura avoids sending pages to a third party but the README presents it alongside the cloud engines rather than as an equivalent. Cloud engines send page images or text to OpenAI, Gemini or Vertex, which is a privacy decision, not a technical one, and it is the user's to make. Bubble layout will also fail on pages where the text is not in a bubble at all: sound effects, signage, margin notes and text drawn over artwork. The editor exists precisely because automatic placement does not always land, and the README's own feature list treats manual adjustment as a first-class part of the workflow rather than an exception.

manga-translator-ui against running manga-image-translator yourself

The honest alternative is the upstream project, manga-image-translator, which this one is based on. The difference is not the translation quality, since the engines and models overlap. It is the interface and the correction loop.

Running upstream directly means you supply your own way to inspect results and fix them, typically by editing JSON output or re-rendering with changed parameters. That can be fine for a scripted pipeline where you accept the output as-is, and it keeps you closer to the upstream code. What you give up is the editor: moving and rotating text boxes, painting masks with a brush, eraser or clone stamp, comparing against the original side by side, multi-select alignment and distribution, and undo history. You also give up the batch management features the README describes, where you match regions by condition, preview which regions will be hit before applying changes, and back up before writing back.

There is a second option worth naming. The README links MTU-JSON-GUI, a separate web-based typesetting tool built for this project's JSON output, which adds a geometry layout engine for alignment, spacing and perspective in Japanese manga layout. If you like the pipeline but prefer to typeset in a browser, that is the documented split: this project produces the JSON, and that tool handles the lettering.

Maintenance, release cadence and the GPL-3.0 obligation

The repository is not archived, and the last push was on 2026-09-06, the same day v3.0.4 was released. The two previous releases, v3.0.3 and v3.0.2, landed on 2026-08-27 and 2026-08-19, so the project is shipping on a roughly weekly cadence across those three versions. That is a real signal about maintenance, and it is the only one this article will use. The README also directs bug reports to the issue tracker and asks for environment, reproduction steps and logs, and it points contributors at a PR contribution guide before submitting changes.

Upgrade cost is mostly download size and model handling. The portable bundle supports updating through the install menu, and the Unix script doubles as the updater, so the mechanical part is cheap. The expensive part is re-verifying your pipeline after a version bump, because the renderer and layout behaviour are the things most likely to shift between minor versions, and the README does not describe a compatibility policy for saved project data.

The licence is GPL-3.0, stated in the README badge and the LICENSE.txt file at the repository root. That matters if you intend to redistribute a modified build or wrap the tool inside something you ship. GPL-3.0 is a copyleft licence, so distributing derivative work generally carries source disclosure obligations. This is a description of what the licence is, not legal advice; if you plan to ship a modified version, read LICENSE.txt and get proper counsel.

Editorial conclusion

Adopt manga-translator-ui if you are doing scanlation or fan translation and you want the detection, OCR, inpainting and typesetting chain in one desktop application you can correct by hand, with a CLI for folders. Do not adopt it if you need a headless service with a documented API contract: the README describes Docker as experimental and documents a Web UI only in terms of account and quota management. Before committing, verify GPU compatibility against your card, since the README ties GeForce 10 series to CUDA 12.6 and RTX 50 series to CUDA 13.0, and confirm that GPL-3.0 fits how you intend to distribute anything you build on top of it.

Frequently asked questions

Official sources

1. hgmzhn/manga-translator-ui on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases