MangaTranslator Extension

Translate manga pages directly in your browser with the LLM provider you configure, a local FastAPI backend, batch page scanner, auto-translate mode, multilingual UI, and optional Flux inpainting.

Tiếng Việt · 中文

Showcase · Features · Download · Quick Start · Configuration · Optional Flux · Web App · Development

Overview

MangaTranslator Extension is a portable browser-extension stack for translating manga and comic pages. The browser extension scans images on the current page, sends them to a local backend, and replaces or previews the translated result. The backend runs locally, so the browser does not need to send manga images through a third-party extension server.

The extension uses the LLM, API key, model, and Base URL that you provide. You can connect it to Google, OpenAI, Anthropic, OpenRouter, DeepSeek, xAI, Z.ai, Moonshot AI, or any OpenAI-compatible endpoint, then keep the translation workflow inside the browser.

The default install stays lightweight: the backend downloads its (non-Flux) models automatically the first time you use it, and Flux Klein 4B is optional, installed later with setup.bat only if you need heavier outside-bubble inpainting.

Showcase

MangaTranslator Extension is built for people who want to keep reading, not copy text into separate tools. Open a chapter, scan the page, choose the images you want, and let your own LLM translate the dialogue back into the manga image.

Translation Result

• Bring your own LLM: use the provider, API key, model, and endpoint you trust.
• Read faster with auto-translate: pages are translated as you scroll, including lookahead pages.
• Keep the manga feel: original text is cleaned and translated text is rendered back into the image.
• Translate more than bubbles: SFX, narration, captions, and other outside-bubble text can be handled too.
• Stay lightweight by default: Flux Klein 4B is optional, so normal users do not need to download a workstation-sized package.

Auto-Translate As You Read

Click Auto-translate in the popup (or press Alt+Shift+A, ⌘+Shift+A on Mac) and just keep reading. Pages are translated as they come into view, plus a few pages ahead, so the next page is usually ready before you get there.

• Blue ••• badge: the page is being translated right now (bottom page above).
• Green MT badge: the page is done. A page that fails 3 times shows a red badge instead; click it to retry.
• Hover a bubble to magnify it, with the original text underneath to check the translation. A button on each page switches between the translated and original image.
• The Auto MT pill in the corner counts translated pages; click Stop to end the session.

Turn on Pre-translate to translate pages as soon as they load instead of when you scroll near them (faster reading, more API calls). The Extension Enabled switch at the top of the popup turns everything off, so nothing is ever sent by surprise.

Story DB and Help Chat

Fix What Auto-Translate Missed

Auto-translate left the "ピンポーン" sound effect untouched. Click ✂ Select text area, drag a box over it, and the text is read for you. Type a translation or click Translate with AI, then Apply to clean the spot and draw the new text into the page. For curved or diagonal text that a box can't isolate, use 🩹 Eraser to paint over it instead.

Features

Download

Latest release:

https://github.com/QuangTQV/Manga-Translator-Extension/releases/latest

Release assets:

Extract models (optional — pick the actual filename from the release you downloaded):

Expand-Archive .\manga-translator-models-no-flux-*.zip -DestinationPath .

Quick Start

1. Download the source or clone the repository.

git clone https://github.com/QuangTQV/Manga-Translator-Extension.git
cd Manga-Translator-Extension

2. Set up the backend (one time).

cd backend
python -m venv .venv
.\.venv\Scripts\pip install -e .
cd ..

Optional: download manga-translator-models-no-flux-*.zip from the latest release and extract it into the project root to restore backend/models/ ahead of time — otherwise the backend downloads the same models automatically the first time you translate a page.

3. Start the backend.

.\start-backend.bat

The backend should listen on:

http://localhost:7677

4. Load the browser extension.

cd extension
npm install
npm run build

Then open Chrome or Edge:

chrome://extensions/

Enable Developer mode, choose Load unpacked, and select extension/dist/.

Configuration

Open the extension popup and use the tabs:

Default backend URL:

http://localhost:7677

Provider keys can be entered in the popup or exposed through environment variables:

GOOGLE_API_KEY
OPENAI_API_KEY
ANTHROPIC_API_KEY

Local LLM (Ollama / LM Studio)

Translate offline with no API cost by pointing the OpenAI-Compatible provider at a model running on your own machine.

By default you need a vision model: the AI reads the text straight off the page image, so a text-only model (plain Llama, Qwen 2.5, ...) has nothing to translate. Examples that can see images: Qwen2.5-VL (qwen2.5vl:7b in Ollama), Gemma 3 (gemma3:12b), or any model LM Studio marks as vision-capable.

Text-only models work too if you set Translate tab → Text reading to manga-ocr (Japanese only) or PaddleOCR-VL: the text is read locally first and only text goes to the model. That is also cheaper and lighter for a local GPU, at the cost of the AI no longer seeing the bubble images.

Ollama

1. Install Ollama, then pull a vision model: ollama pull qwen2.5vl:7b (the server starts on port 11434).
2. Popup → LLM Config: Provider OpenAI-Compatible, Base URL http://localhost:11434/v1, Model qwen2.5vl:7b, API key: any text such as ollama (the field can't be empty; Ollama ignores it).
3. Click Test next to the key, then translate as usual.

LM Studio

1. Download a vision model in LM Studio, then in the Developer tab start the local server (port 1234).
2. Popup → LLM Config: Provider OpenAI-Compatible, Base URL http://localhost:1234/v1, Model: the model identifier LM Studio shows, API key: any text such as lm-studio.

Good to know

• The Base URL is called by the backend, not the browser. If the backend runs in Docker, use http://host.docker.internal:11434/v1; if the model runs on another machine, use that machine's LAN address (for Ollama, start it with OLLAMA_HOST=0.0.0.0).
• By default a page sends one combined full-page image (Pro tab's Combine into one page image, on by default); turning that off sends one image per bubble instead, which can be several at once. Either way, Ollama's default context window can be too small for a full manga page, which shows up as missing or garbled translations — start it with a bigger one, e.g. OLLAMA_CONTEXT_LENGTH=16384 ollama serve. Economy mode also helps (smaller images).
• 7-12B local models are noticeably weaker than large cloud models on small or stylized text, and a page can take tens of seconds without a strong GPU. If a small model breaks the numbered answer format (bubbles show a translation error), try a larger model or a lower temperature.
• Every other feature (Story DB, replacement dictionary, lettering, manual tools) works the same with a local model.

Optional Flux

Flux is not bundled in the normal release because it adds several GB. The default outside-bubble mode uses lightweight cleanup and does not require Flux.

To install Flux Klein 4B on demand:

.\setup.bat

Choose:

2. Download optional Flux Klein 4B model

The script downloads to:

backend/models/flux/

Use Flux only when you explicitly configure outside-text inpainting to a Flux mode such as flux_klein_4b. For most users, the default auto behavior is lighter and faster.

In between: LaMa Manga (default). Inpainting quality → LaMa Manga needs no GPU and no manual setup: the ~200MB model (anime/manga-finetuned big-lama TorchScript export, by the IOPaint/lama-cleaner author) downloads to backend/models/lama/ the first time it's used and runs on CPU in a couple of seconds per region. It reconstructs panel borders and screentone far better than the default cleanup, and cleaner than the generic (photo-trained) LaMa also offered in the same dropdown — though not as well as Flux on large painted areas.

No GPU? Run Flux on a remote GPU. The popup's Inpainting quality setting also offers Flux Klein 4B (remote) and Flux Klein 9B (remote): run backend/flux_worker.py on a free Kaggle GPU (or any GPU box), expose it with a cloudflared tunnel, and paste the URL into the popup — nothing heavy is installed locally. Protect the worker with --token / FLUX_WORKER_TOKEN and put the same value in the popup's Token field. If the worker is down or rejects the token, the page still translates (outside-bubble text is left as-is), a warning toast explains why, and the backend stops retrying the dead worker for ~60 seconds. Step-by-step guide (Vietnamese): docs/HUONG-DAN-CHAY.md.

Web App (no extension needed)

For raw image files you already have on disk (scans that were never published to any web page — the extension can only translate <img> elements it finds on a page you're browsing) run the backend as usual, then open http://localhost:7677/app in any browser. Drag files in (or use the file picker), configure the provider/key/languages in the sidebar (saved in that browser's own storage), click Translate All, then Export ZIP or Export CBZ.

It is deliberately minimal — no Story DB, no provider/key rotation, no manual region/eraser/font tools, no auto-translate — for that, use the extension. It talks to the same local backend over a plain fetch(), so nothing beyond the backend needs to be running.

Usage Workflow

1. Start the backend with start-backend.bat.
2. Open a manga/comic chapter in Chrome or Edge.
3. Click the MangaTranslator extension icon.
4. Choose source and target language.
5. Click Scan & Translate Page to choose images manually, or Auto-translate to translate as you scroll.
6. Review translated images on the page.

Tip: On manga sites that use lazy-load and prevent the extension from scanning the whole chapter at once, scan and translate the next 4-5 pages first, then turn on Auto-MT for the smoothest reading experience.

Project Layout

manga-translator-extension/
  backend/                         FastAPI backend and MangaTranslator integration
  backend/main.py                  Backend entry point
  backend/core/                    Detection, cleanup, translation, rendering
  backend/models/                  Model files restored from release assets
  backend/pipeline/                Wrapper around the core pipeline
  extension/                       Manifest V3 browser extension
  extension/src/background/        Service worker and backend requests
  extension/src/content-script/    Page scanner and auto-translate overlay
  extension/src/popup/             Popup UI
  extension/src/shared/            Types, constants, i18n
  docs/                            API docs and localized READMEs
  setup.bat                        Optional setup helper, including Flux download
  start-backend.bat                Backend launcher

Development

Build the extension:

cd extension
npm install
npm run build

Compile-check backend files:

cd ..\backend
python -m py_compile pipeline\wrapper.py

Regenerate the popup/tool screenshots in docs/assets/ after UI changes (the backend is mocked, so nothing else needs to be running):

cd extension
npm run build
node scripts/readme-screenshots.mjs

Check backend health:

Invoke-RestMethod http://localhost:7677/health

Release Packaging

Do not commit generated runtime, models, caches, or extension build output. They are intentionally ignored:

backend/runtime/
backend/models/
extension/dist/
extension/node_modules/
release-assets/

Use GitHub Releases for runtime/model archives. GitHub blocks files over 100 MB in normal Git history, and large runtime archives should be split so each release asset stays below GitHub's release asset limit.

FAQ

Q: How good is the translation quality?

A: Translation quality depends on the LLM model you use. Stronger models usually produce more natural wording, better context handling, and fewer mistranslations.

Q: Some pages have text outside speech bubbles and the result shows white/black boxes. What should I do?

A: Use the optional Flux Klein 4B model to improve inpainting quality for text outside bubbles, SFX, narration, and messy backgrounds.

Q: Why does the popup show Backend Offline?

A: Start .\start-backend.bat, wait until the backend is ready, then confirm that http://localhost:7677/health opens successfully. Also check that the Backend URL in the Config tab matches your local server.

Q: Why are some manga images not detected?

A: Wait for the reader page to finish lazy-loading, then run Scan & Translate Page again. If the site loads pages only while scrolling, scroll through the chapter once or use Auto-collect in the scanner.

Q: I set up a Story DB and selected it, but the translation doesn't seem to use it. Why?

A: Turn on the Use Story DB toggle on the Translate tab — selecting a story on the Story DB tab alone doesn't apply it, by design, so you can translate a one-off page without it even while a story is selected.

Q: I don't understand how to set something up — is there help built in?

A: Click the ? button in the popup header to ask a question. It's answered by your own configured LLM using this project's own documentation, not a canned script — so it costs a small amount of your API quota, same as any other AI feature here.

Troubleshooting

Security

Never commit API keys, private backend URLs, generated caches, model artifacts, node_modules, dist, or a full Python runtime. Keep secrets in the extension popup or environment variables.

License

This portable build includes code derived from MangaTranslator. Keep upstream license requirements with any redistribution.