Manga Trans Studio

Translate manga through an MCP-connected AI host, then review and edit the pages in a local web app.

The host model reads and translates. The Python backend detects regions, runs local OCR, removes source text, fits the translation, and checks the rendered pixels. The backend does not need an LLM API key. Your host's model access and pricing still apply.

Install and run

Use Python 3.10 or newer. From the repository folder on Windows:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python -m uvicorn backend.server:app --host 127.0.0.1 --port 8000

Open Studio. On Windows, start_app.bat runs the same server with reload enabled; it uses the python on your PATH.

OCR models download on first use, so the first analysis can take longer. The web UI also loads some assets from CDNs. This project has been tested on Windows. Other systems may need additional fonts for scripts not covered by the bundled fonts.

Connect your AI host

Open the plug button in Studio for a configuration using this checkout's paths. Add the server to a client that supports MCP over stdio. For clients using a mcpServers JSON configuration, the entry looks like this:

{
  "mcpServers": {
    "manga-trans": {
      "command": "C:/path/to/manga-trans/.venv/Scripts/python.exe",
      "args": ["C:/path/to/manga-trans/backend/mcp_server.py"],
      "cwd": "C:/path/to/manga-trans",
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1",
        "PYTHONUTF8": "1",
        "MANGA_TRANS_DEVICE": "auto"
      }
    }
  }
}

Replace the example paths with your checkout and Python environment. On Linux or macOS, the virtual environment executable is .venv/bin/python. Clients with a different configuration format need the same command, arguments, working directory, and environment.

The client starts the MCP process. Start the web server separately to see the pages. Both processes must use the same checkout and workspace; by default, they share .manga_trans_cache/studio-workspace.json.

Related MCP server: i18n-tools

Translate a chapter

1. Give the host the raw chapter folder and target language. Ask it to call manga_analyze_chapter.

2. Have it translate the returned OCR regions by region_id. Keep the backend's coordinates. A model with vision can call manga_load_page to check reading order, speakers, and uncertain OCR.

3. Render through manga_render_page or manga_render_chapter. The pages and progress appear in Studio.

4. Review each page, correct text or positions, save a draft, then confirm it when finished.

A text-only model can translate the structured OCR output. It cannot visually check missing regions or speaker identity. For that, use a vision-capable host or inspect the page yourself.

OCR can miss vertical punctuation, furigana, stylized text, or entire balloons. A successful render does not mean the translation or OCR is correct.

Review in Studio

The page queue shows batch progress and lets you open a specific page. Use the original/translated comparison to check placement and artwork.

• Draw an omitted region to run OCR on it. Moving or resizing a region requests OCR again after the edit settles. The manual-region endpoint currently defaults to Japanese OCR.

• Enter translated text to trigger cleaning and a typeset preview. Adjust the box, font, size, alignment, or stroke as needed.

• Save stores an editable draft locally. Confirm marks the page as finished. Rendering alone does not confirm it.

• Download PNG exports the visible translation. JSON export preserves editable bubble data; it does not bundle all chapter assets.

• The trash icon removes a page from the review queue. It does not delete the raw image or rendered files.

The interface supports Vietnamese and English. Keep the workspace cache if you want to resume editing.

Balloon boundaries and overflow

Text fitting uses an inset pixel mask from the original balloon outline. This catches glyphs, accents, and strokes that fit a bounding rectangle but cross a curved edge.

If the first layout crosses that mask, the typesetter retries inside a rectangle contained by the mask, then reduces the font size if needed. Enclosed rectangular balloons retain their corners. Cleaning also uses a detected contour to protect the outline and surrounding art.

Open or unrecognized speech balloons use an elliptical fallback. SFX regions use a rectangular boundary. These fallbacks cannot prove where the real outline is: correct the region and check the preview when detection is uncertain. Dark or textured balloons may also need manual cleanup.

The final render clips to its allowed mask, but the pre-clipping overflow count is retained. Strict MCP QA rejects a page that needed clipping; Studio also rejects such a re-render instead of silently accepting cut-off text.

QA fields

Inspect the preview even when QA passes. These checks do not catch every wrong balloon, missed word, or damaged detail.

GPU and local data

Set MANGA_TRANS_DEVICE=auto to use CUDA when available, or cpu to force CPU OCR. CUDA requires a compatible PyTorch installation; installing the base requirements alone does not guarantee GPU support.

MANGA_OCR_BATCH_SIZE controls OCR batch size. The default is 8 on CUDA and 16 on CPU. Lower it if GPU memory is tight.

Downloaded models live under .models/; analysis files, workspace state, and Studio edits live under .manga_trans_cache/. Both are ignored by Git. Do not delete these folders as routine cleanup if you still need saved work or want to avoid downloading models again.

MCP tools

See AGENTS.md and the translation skill for the agent workflow.

Tests and code

Run from the repository root:

python -m unittest discover -s tests -v

Some regression tests use local chapter fixtures and skip when those files are absent. Curved-balloon tests use generated images and check all nine horizontal/vertical alignment combinations, including thick text strokes.

• backend/engine/: geometry, OCR, cleaning, typesetting, and pixel QA.

• backend/mcp_server.py: MCP stdio server and tool schemas.

• backend/server.py: Studio HTTP endpoints.

• backend/studio_workspace.py: persistent page queue and edit state.

• frontend/index.html: Studio interface.

• tests/: rendering and workspace regressions.