BallonsTranslator: a PyQt6 workbench for deep-learning manga translation

The four-stage pipeline behind one Run button

The README describes the one-click translation path as four modules working in sequence: text detection, text recognition, text removal (inpainting), and machine translation. The rendered result depends on the combined performance of all four, which is the honest framing of the whole project. A miss in detection means a line never gets translated. A miss in inpainting leaves ghost strokes behind the new text. A weak translation model produces fluent-looking output that is wrong.

The README states that text detection currently supports Japanese (the reasoning given is that CJK block characters are similar enough) and English only. That is a narrower base than the feature list implies, and it is the first thing to check against your source material. Detection training code and notes live in a separate repository, dmMaze/comic-text-detector, so the detector is not something you retrain from inside BallonsTranslator itself.

BallonsTranslator leans heavily on manga-image-translator, which the README credits and asks users to support financially. That dependency matters for planning: the online server and model training behind that project cost money, so availability of hosted components is not something this repository controls.

How translated text gets placed back into the balloon

Refilling is not a fixed overlay. The README says the translated text placement references an estimate of the original layout, including color, outline, angle, orientation and alignment. The extracted background bubble is the reference for text layout, which is why the tool can put a translation into a slanted or irregular balloon without you drawing a box first.

Language-pair behaviour differs. English to Chinese and Japanese to English layout are described as optimized. Chinese line breaking uses pkuseg for segmentation. Japanese to Chinese vertical text is explicitly listed as still needing improvement, so a vertical Japanese page translated into Chinese is the case where you should expect manual work.

When you do want control, the settings panel has a lettering menu where you can switch to global settings instead of per-block decisions. The README defines the global font format as whatever the font panel on the right shows when no text block is selected. The title bar Run menu lets you disable any automation module; with all of them disabled, Run re-renders text using the global font style and lettering settings. That is a useful escape hatch: it turns the tool into a pure typesetting renderer for text you have already corrected.

Installing on Windows, macOS and Linux

Windows has two documented routes. Route A runs a PowerShell installer that places BallonsTranslator in the current directory:

irm https://raw.githubusercontent.com/dmMaze/BallonsTranslator/dev/scripts/install.ps1 | iex

From cmd.exe the README gives:

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/dmMaze/BallonsTranslator/dev/scripts/install.ps1 | iex"

Route B downloads Ballonstranslator_win_minium.zip from GitHub Releases, extracts it, and runs launch_win.bat. Neither route supports Windows 7; the README directs those users to install Python 3.8 and run from source.

On macOS and Linux the documented sequence is:

curl -fLO https://raw.githubusercontent.com/dmMaze/BallonsTranslator/dev/scripts/install.sh && chmod +x install.sh && ./install.sh

After installation the program starts automatically; later launches use cd BallonsTranslator && ./launch.sh. If curl is missing, wget -O is offered as a substitute.

Optional dependencies are handled at runtime: on startup the program checks core dependencies, and when you select a module that needs extra libraries it prompts you to install them. Auto-install can also be enabled in settings. The README also lists concrete Windows error strings (msvcp140.dll, c10.dll, WinError 1114) and points to the Microsoft Visual C++ Redistributable x64 as the fix. That level of specificity in an install section usually means users hit it often.

Headless runs and the config file they depend on

There is a documented command-line mode with no GUI:

python -m ballontranslator --headless --exec_dirs "[DIR_1],[DIR_2]..."

All settings, including the detection model and the source and target languages, are imported from config/config.json. If rendered font sizes come out wrong, the README says to pass --ldpi with the logical DPI, typically 96 or 72.

The important constraint is that headless mode reads configuration rather than exposing flags for it. You prepare config.json through the GUI or by hand, then batch over directories. That is workable for scheduled runs, but it means your batch behaviour is coupled to a file the GUI also writes. The README also recommends running the program from a terminal in general, which suggests console output carries information the window does not surface.

The LLM translator, token budgets and glossary files

The most developed part of the documentation covers LLM translation. Setting LLM context to include translation history makes LLMTranslator reference previously completed pages, which the README says helps keep names, terminology and tone consistent. A token budget controls how much earlier translation is included, with newer pages kept preferentially. The default is 4096.

The README is unusually candid about the cost curve. Its own table, described as a rough estimate for a typical comic page using DeepSeek, lists a relative total cost of 1.65x at a 2048 budget, 1.79x at 4096, 2.10x at 8192 and 2.66x at 16384, against using no history. It notes that caching interacts with this: as history grows within budget, consecutive requests keep the same prefix, and services such as OpenAI and DeepSeek can reuse those input tokens at a discount. When the budget forces old pages out, the shared prefix changes and cache reuse resets. Larger budgets reduce resets but send more history, so total cost is not necessarily lower. The README suggests roughly 70 percent of a model's context limit as a reasonable ceiling, about 90000 for a 128K model.

Glossaries are reusable files in UTF-8 with .json, .txt or .tsv extensions. The README shows a Sakura-style line format (source->target # optional note), a tab-separated form, and a JSON array of objects with src, dst and info keys. Only-match sends entries whose source term appears on the relevant page; whole-table sends everything and can increase token use noticeably. Matching is case-insensitive and literal. The README states that conflicting entries, malformed files, unsupported extensions or a missing file stop translation before any LLM request is sent. History and glossary injection apply only to LLMTranslator; other translators ignore those settings.

A separate feature adds vision, page summaries and a project-level memory. Summaries record characters and relationships, scenes, events, speaker cues and unresolved references. When old summaries no longer fit the budget, or when the last page is processed, a separate text-only request merges them into memory, and later translations reuse that compressed result as stable context.

Where the tool stops being the right choice

The README's own warning is the clearest limitation: if you plan to share machine-translated output publicly without a complete pass by an experienced translator or proofreader, you are asked to mark it visibly as machine translation. That is a statement about reliability, not modesty.

The inpainting section is equally direct. Two removal methods are offered, and the README calls both of them somewhat unpredictable, describing them as handling most simple text on simple backgrounds, some complex-background simple-text and simple-background complex-text cases, and few complex-background complex-text cases. The advice is to draw a box slightly larger than the text and try repeatedly. If your pages are heavy with stylized sound effects or text over detailed art, this is where the workflow becomes manual retouching.

Text detection limited to Japanese and English rules out other source languages at the detection stage. Vertical Japanese to Chinese is flagged as unfinished. And the tool is a desktop application: the GUI is PyQt6, and although headless mode exists, it consumes a config file rather than offering a full scripting API. If you want translation embedded in a service pipeline rather than a workstation, this is the wrong shape.

How it differs from calling manga-image-translator directly

The obvious alternative is manga-image-translator, the project BallonsTranslator itself credits and depends on. The difference is in what each gives you. manga-image-translator is the translation pipeline; BallonsTranslator is an editor built around a pipeline, adding a canvas with mask editing and a healing brush, rich text editing with style presets, text effects and deformation, find and replace across original and translated text, Word document import and export, and undo and redo across most operations.

That editor layer is the reason to pick BallonsTranslator. The README's workflow descriptions, from switching to text edit mode with T and creating blocks with W, to adjusting lettering and original-image opacity with the 0-9 keys, all describe interaction with a canvas. A pure pipeline gives you an output image; this gives you a place to fix it. The cost is that you take on a desktop application, its dependency checks and its configuration file. If you never intend to touch a page by hand, the editor is weight you are carrying for nothing.

One detail worth noting for anyone comparing the two: the README states that BallonsTranslator's detection training code lives in a separate repository, comic-text-detector, so the detector is shared lineage rather than something unique to this project.

Licence, maintenance and what to verify before adopting

BallonsTranslator is GPL-3.0. If you distribute modified versions, the licence's terms apply to that distribution, and this article is not legal advice; read the licence text and, if you are shipping a product, get proper review. The README's machine-translation labelling request is separate from the licence and is a courtesy norm the project asks for.

The repository is active rather than archived, with a dev default branch and releases v1.5.15, v1.5.14 and v1.5.13 dated within days of each other in early September 2026. That cadence tells you fixes arrive quickly, and equally that the interface and behaviour can move between versions. Pin a release if you depend on config.json keys staying stable, since headless mode reads that file and a settings change can alter batch behaviour.

Upgrade cost is dominated by models and optional dependencies, not by the Python code. The program checks core dependencies at startup and prompts for missing optional libraries when you enable a module, so an upgrade can surface a new prompt mid-workflow. On the LLM side, cost scales with the history budget you choose, and the README's own table shows the multiplier rising from 1.65x to 2.66x as the budget grows.

What to verify first, concretely: run the install script for your platform, confirm your source language is covered by the Japanese and English detection limit, and test one page end to end with each automation module enabled in the title bar Run menu. If inpainting is the weak link on your material, the README's advice to draw a slightly larger box and retry applies, and the rectangle tool's right-click clears the repair result inside the box.

Editorial conclusion

Adopt BallonsTranslator if you translate comics in volume and want detection, OCR, inpainting and translation in one PyQt6 window, with a headless path for batches. Do not adopt it if you need a polished result with no human pass, or if GPL-3.0 redistribution terms do not fit how you ship the output. Before committing, run the install script for your platform, open a small folder of pages, and check the four stages separately, because the README states the final result depends on detection, recognition, inpainting and translation together. Also check whether your target language pair is one of the optimized ones: English to Chinese and Japanese to English layout are described as tuned, while Japanese to Chinese vertical text is listed as still needing improvement.

Official sources

1. dmMaze/BallonsTranslator on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases