Translate Manga Locally: Free, Unlimited, Art Intact

One command translates a whole chapter offline: python -m manga_translator local -v -i ./chapter --use-gpu. manga-image-translator (10,308 stars, GPL-3.0, last pushed July 20, 2026) runs four local models in sequence — bubble detection, 48px vertical-Japanese OCR, lama_large inpainting, then re-rendering — and writes the results to <your-folder>-translated. There is no page cap and no queue, because there is no server. The inpainter is why the artwork survives: it rebuilds the panel underneath the Japanese text instead of pasting an English block on top of it.

Two things to set before you run it on a whole volume, both covered below: the default target language is Chinese, not English, and the official Docker image is about 15GB.

Everything on this page — flags, defaults, star counts, the translator table — is read from the upstream repositories on August 18, 2026 and attributed to them. Where the project publishes no number (VRAM is the big one), this page says so rather than inventing one.

---

How Does Local Manga Translation Work?

Detection → OCR → inpainting → rendering. Every stage is a separate model with its own config block, and every stage has its own characteristic failure.

The translator sits between stages 2 and 3 and is the one part that can be swapped for a cloud service. Everything else is local by construction.

That inpainting stage is the entire differentiator versus screenshotting a page into a generic OCR tool. Generic OCR gives you a wall of text detached from the panels — which is the failure the reader of this page has already hit. LaMa (large mask inpainting, Apache 2.0, 10,200 stars) reconstructs the screentone, the speed lines and the character art that were behind the speech bubble's text, and the renderer then lays English into the cleaned bubble with an estimate of the original alignment and direction.

The project is honest about its own maturity, and so are we: its README states it is "still in the early stages of development and has many shortcomings". Expect to fix pages by hand. The point is that you are fixing ten pages, not translating two hundred.

---

Should You Install With Pip or Docker?

Use pip if you care about disk space; use Docker if you care about not debugging PyTorch. The project publishes both and is blunt about the trade-off.

Pip route (models download to ./models at runtime, so you only fetch what your config uses):

# Python 3.10 or later; the very newest Python may not have PyTorch wheels yet
python --version

git clone https://github.com/zyddnys/manga-image-translator.git
cd manga-image-translator
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

For GPU you install PyTorch yourself, matched to your CUDA version, from pytorch.org — the repo deliberately does not pin it. Windows users need Microsoft C++ Build Tools installed before pip install, because several dependencies compile; this is issue #114 in the tracker and it is the number one Windows install failure.

Docker route. The image is zyddnys/manga-image-translator:main and the README describes it as "quite large (~15GB)" because it bundles every dependency and every model. It needs Docker 19.03+ and the NVIDIA Container Runtime for GPU. Batch translation via the container looks like this:

docker run --ipc=host --rm \
  -v <targetFolder>:/app/<targetFolder> \
  -v <targetFolder>-translated:/app/<targetFolder>-translated \
  zyddnys/manga-image-translator:main local -i=/app/<targetFolder> <cli flags>

There is also a web server mode (server/main.py --verbose --start-instance --host=0.0.0.0 --port=5003, add --gpus all and --use-gpu for GPU), which is the right choice if you want a drag-and-drop page in your browser rather than a terminal. Mind the two ports: --port 5003 is the translator service the README's docker command publishes, while the browser UI itself is served on 8000 by default (API docs at 127.0.0.1:8000/docs, API service on 8001). Open localhost:8000, not 5003.

If the container starts but ignores your GPU, check the NVIDIA Container Runtime is installed and that you passed --gpus all — those two account for nearly every case, and the container will silently fall back to CPU rather than erroring.

---

The One Command

Batch mode is the default mode, and it takes a folder:

python -m manga_translator local -v -i ./chapter-01 --use-gpu

Results land in ./chapter-01-translated. Flags worth knowing on day one, straight from the README's option list:

• -v, --verbose — prints debug messages and saves intermediate images into the results folder. Leave this on. When a page comes out wrong, the intermediate mask tells you whether detection or inpainting failed.
• --use-gpu — automatically switches between CUDA and MPS, so this is also the flag Apple Silicon users want.
• --use-gpu-limited — GPU for everything except offline translators. Useful when the translation model is what is blowing up your VRAM.
• -o, --dest — output folder, if you do not want the -translated sibling.
• --skip-no-text — do not save pages with no detected text. Good for chapters with full-page splashes.
• --overwrite — re-process pages that already have output. Without it, re-runs skip finished pages, which is exactly what you want when a batch dies halfway.
• --ignore-errors — skip the page that crashed instead of stopping the volume at 3am.
• -f, --format — png, webp, jpg, jpeg, xcf, psd, pdf. The psd and xcf outputs are the underrated ones: layered files you can open in Photoshop or GIMP with the text as an editable layer.
• --save-text / --load-text — dump the extracted text and translations to a file, edit that file, load it back. This is the cheapest way to fix translation quality without re-running OCR.

---

Which Translator Backend Should You Choose?

For Japanese to English, the project's own recommendation is Sugoi, and it is also the default in the config schema. Here is the offline field of the translator reference table, quoted from the README:

How to choose, in one line each. Sugoi is a JA→EN specialist and it is what the maintainers point at; the multilingual models (NLLB, M2M100, mBART-50) are the answer when your source is Korean or Chinese rather than Japanese; custom_openai pointed at a local LLM is the only option that can carry context and a glossary across pages.

What this page will not do is publish a side-by-side quality score. Doing that honestly means a fixed panel set, a fluent Japanese reader grading honorifics, SFX and register, and a repeatable rubric — and anything less is a made-up number dressed up as a benchmark. What it can give you is the structural difference, which is what actually decides it: Sugoi and NLLB translate one text region at a time with no memory of the previous panel, so a character's name and speech register can drift across a chapter. An LLM backend can see context. That is the axis, and it is why the LLM route exists at all despite being slower.

The AMD note in that table is not decorative: m2m100 and m2m100_big are marked as requiring NVIDIA/CTranslate2, while the _hf variants explicitly work on ROCm. If you are on Radeon, use the _hf ones.

---

How Do You Wire It to Ollama?

custom_openai speaks the OpenAI API shape, and Ollama serves that shape at http://localhost:11434/v1 — so the two connect with three environment variables and no adapter. From the project's own environment-variable table:

# .env in the project root
CUSTOM_OPENAI_API_BASE=http://localhost:11434/v1
CUSTOM_OPENAI_MODEL=qwen2.5:7b
CUSTOM_OPENAI_API_KEY=ollama

The README notes the key is "not needed for Ollama, but possibly required for other tools", and that the model must be pulled and running before you use it. CUSTOM_OPENAI_MODEL_CONF lets you tell the pipeline which prompt convention the model follows (for example qwen2).

One real limitation to know before you commit to this route: the README states that custom_openai cannot load the glossary file — only OpenaiTranslator can. If a consistent glossary of character names and technique names is the thing you care about, that is an argument for doing the LLM pass in BallonsTranslator instead, which has its own glossary system (covered below).

New to running a local model server? Start with our complete Ollama guide, or the Windows installation walkthrough if that is your platform. For picking a model that fits your card, the 8GB Ollama model picks are the right starting point — a 7B at Q4 is plenty for sentence-level translation.

---

The Config File That Matters

Two defaults will bite you, and both live in the JSON config rather than the CLI.

# Dump the full documented schema so you can see every option
python -m manga_translator config-help >> config-info.json

The first trap: target_lang defaults to "CHS" — Simplified Chinese. Run the tool with no config and English speakers get a perfectly executed Chinese translation. The second: the translator itself defaults to sugoi, which is right for Japanese source but wrong if you are translating Korean webtoons.

A working English config for Japanese manga:

{
  "translator": {
    "translator": "sugoi",
    "target_lang": "ENG"
  },
  "detector": {
    "detector": "default",
    "detection_size": 2048,
    "det_auto_rotate": true
  },
  "ocr": {
    "ocr": "48px",
    "ignore_bubble": 8
  },
  "inpainter": {
    "inpainter": "lama_large",
    "inpainting_size": 2048
  },
  "render": {
    "renderer": "manga2eng"
  },
  "mask_dilation_offset": 30
}

python -m manga_translator local -v -i ./chapter-01 --use-gpu --config-file ./manga-en.json

Notes on the non-default choices in there. det_auto_rotate is documented as rotating the image "to prioritize detection of vertical text lines" — that is exactly the Japanese case. ignore_bubble at 8 sits in the README's recommended 5-10 band for filtering text outside bubbles; too low and real bubbles get dropped, too high and background signage gets treated as dialogue. manga2eng is the renderer that "will try to fit the detected text bubble rather than detected textline area", which is the single best fix for English text coming out unreadably small. mask_dilation_offset at 30 is already the schema default and the README suggests the 10-30 range to better wrap the source text.

The README's own recommended settings, for the record: detector default for black-and-white manga (with tuned parameters — it notes ctd "can increase the number of text lines detected"), OCR 48px for Japanese and Korean, translator Sugoi for JPN→ENG, inpainter lama_large, colorizer mc2. Several of the recommended-detector rows in that table are literally left as "??" by the maintainers, which is a refreshingly honest way to say "nobody has tested this properly".

---

How Do You Batch a Whole Volume?

-i takes a folder, so a volume is a loop over chapter folders. The pattern that survives an overnight run:

#!/usr/bin/env bash
set -uo pipefail

for chapter in ./volume-01/*/; do
  echo "=== $chapter"
  python -m manga_translator local \
    -v --use-gpu --ignore-errors --skip-no-text \
    --config-file ./manga-en.json \
    --save-text \
    -i "$chapter"
done

Why each flag is there:

• --ignore-errors so one corrupt JPEG does not end the run at page 40 of 400.
• --skip-no-text so splash pages and chapter dividers do not get pointlessly rewritten.
• --save-text so you get a text dump per chapter. Read that file, fix the twelve lines that are wrong, and --load-text them back in — vastly cheaper than re-running detection and OCR on the whole volume.
• No --overwrite, so re-running after a crash resumes rather than restarts.
• --attempts N is also available if you want automatic retries on transient errors.

If your raws are low-resolution, the README's own tip applies before anything else: "small resolutions can sometimes trip up the detector", and upscale_ratio 2 (upscalers available: waifu2x, esrgan, 4xultrasharp) fixes detection more often than any detector tuning does. revert_upscaling scales the page back down afterwards. Our local image upscaling guide covers doing that as a separate pre-pass if you would rather keep the upscaled masters.

---

What Do You Do When the Auto Pass Fails?

Five failures cover almost everything, and the intermediate images from -v tell you which one you have. Ordered by how often each is the real cause.

1. Output is in Chinese. Cause: target_lang defaults to "CHS". Fix: set "target_lang": "ENG" in your config. This one is first because it is the most common and the most annoying to discover after a 200-page batch.

2. Vertical text lines are missed entirely. Symptom: whole bubbles left untranslated, and the debug mask shows no region over them. Fix, in order of what to try: set det_auto_rotate: true (documented as prioritising vertical text line detection), then det_rotate, then lower detection_size if the page is low-resolution or raise it if the page is very high-resolution — the README is explicit that the correct direction depends on your source resolution. det_invert and det_gamma_correct are the next two levers for pages with inverted or washed-out contrast.

3. Ghost pixels of the Japanese text remain after inpainting. Symptom: faint outlines of the original characters visible inside the bubble. Cause: the mask does not fully cover the source text. Fix: raise mask_dilation_offset (README suggests 10-30 to "better wrap the source text") and raise kernel_size, documented as the convolution kernel for the text-erasure area "to completely clear residual text". If it still ghosts, change the inpainter.

4. Translated text is too small to read, or overflows the bubble. Fix: switch renderer to manga2eng, which fits the bubble rather than the textline box. If it is still small, use font_size_offset (positive increases size) or set font_size outright. Supply a comic-appropriate face with --font-path fonts/anime_ace_3.ttf; the default system font is a big part of why untuned output looks wrong.

5. Out of memory. Cause, almost always: inpainting_size, which the README annotates directly as "too large can cause out of memory". Fix, in order: drop inpainting_size from 2048, set inpainting_precision to bf16 (an explicitly documented option for lama), then drop detection_size, then move the translator to CPU with --use-gpu-limited so only detection/OCR/inpainting use the GPU.

Bonus, for garbled output: the README suggests increasing box_threshold to "filter out gibberish from OCR error detection". If OCR is reading noise as text, that is the dial.

---

The Manual-Fix Loop

Some panels will always need a human, and BallonsTranslator (5,038 stars, GPL-3.0, pushed August 18, 2026 — today) is the editor for them. It is the most actively maintained tool in this space right now, which is worth knowing on its own.

What it gives you that the CLI does not:

• Mask editing and an inpainting brush — fix the one bubble where lama smeared the artwork, without re-running the chapter.
• WYSIWYG rich-text editing with font style presets, text warping, and find-and-replace across the whole project or just the source/target text.
• Word document import and export, if a human translator is doing a pass outside the tool.
• LLM translation with context and a glossary. Setting LLM context to include translation history makes its LLMTranslator reference previously completed pages, which is what keeps character names, terminology and tone consistent across a volume. The glossary accepts UTF-8 .json, .txt or .tsv — the text format is source->target # optional note or tab-separated — and files are read-only, so one glossary works across projects. The README warns that "match only" sends just the entries that appear on the page while "full table" sends everything and can significantly increase token usage. On a local model, a bigger history budget means noticeably more RAM and VRAM; the default budget is 4096 tokens and the docs call that a deliberately conservative choice.
• Webtoon support for vertical-scroll strips.

Install on Windows is a one-liner:

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

Or download Ballonstranslator_win_minium.zip (32MB, release v1.5.11, published August 10, 2026) from Releases and run launch_win.bat. Neither path supports Windows 7.

The workflow that works: batch the chapter with manga-image-translator, flick through the output, and open only the broken pages in BallonsTranslator. If you know in advance a chapter is going to need heavy hand-work, run the CLI with --prep-manual, which outputs blanked and inpainted images plus copies of the originals for reference — the art is cleaned for you and you do the typesetting.

---

How Much VRAM Does This Need?

The project publishes no VRAM figures, and there is no trustworthy public number to quote, so this page does not print one. What it can give you is the shape of the problem and the exact knobs that control it.

Four models are resident during a run: the detector, the 48px OCR model, lama_large, and — if you chose an offline translator — the translation model. Their peak memory is dominated by two config values, both defaulting to 2048: detection_size and inpainting_size. Those are the numbers to lower first on a small card, and inpainting_precision: bf16 is the documented precision escape hatch.

What to check on your own machine, in the order that costs you the least time: run one page with -v while watching nvidia-smi (or Activity Monitor on a Mac); if it fits, run ten pages; if that fits, run the chapter. Ten minutes of that gives you a real number for your config, which is worth more than any published figure taken on different hardware with different settings.

CPU-only works. Omit --use-gpu and everything runs on the processor — that is the documented default. No timing figure for a full CPU chapter is published anywhere reliable, and inventing one would be worse than useless, but the shape is predictable: LaMa inpainting at 2048px is the expensive stage and it is the one to shrink first if you are CPU-bound. Run a single page, time it, multiply. If it is unusable, --use-gpu-limited is the middle setting — GPU for the vision models, CPU for the offline translator.

Apple Silicon is covered: --use-gpu "automatically switches between mps and cuda", so Mac users use the same flag.

For sizing a machine around this and the rest of a local stack, our hardware hub and the VRAM calculator are the practical next stops. If your interest is text documents rather than panels, translating documents offline is the sibling page, and local AI document scanner covers paper-to-text OCR.

---

Sources

All figures verified against upstream on August 18, 2026:

• zyddnys/manga-image-translator — 10,308 stars, GPL-3.0, last pushed July 20, 2026. All CLI flags, config defaults, the translator reference table, environment variables and the ~15GB Docker image size are quoted from its README
• dmMaze/BallonsTranslator — 5,038 stars, GPL-3.0, last pushed August 18, 2026; release v1.5.11 (August 10, 2026), Ballonstranslator_win_minium.zip 32MB
• advimman/lama — 10,200 stars, Apache 2.0, the inpainting model behind lama_large
• Sugoi V4.0 is created by mingshiba; the manga-image-translator README asks users to support the author at patreon.com/mingshiba

---

FAQ