Manhua Translation Pipeline

Manhua Translation Pipeline is a local-first Python application for converting Chinese manhua pages into translated English pages. It accepts CBZ, ZIP, or folders of images and processes them through detection, OCR, translation, editing, rendering, quality assurance, and optional packaging.

The project is intended for two groups:

• Readers and translators who want a guided workflow with the option to review or correct text manually.
• Developers who want an inspectable, rerunnable pipeline with replaceable detection, OCR, translation, and paraphrasing components.

The pipeline writes intermediate results as JSON files inside each chapter workspace. You can inspect or edit those files, rerun one stage, or resume from the last completed stage.

What the pipeline does

For each chapter, the application performs these steps:

1. Import - normalizes a CBZ, ZIP, or image folder into ordered PNG pages.
2. Detection - finds speech bubbles and narration regions.
3. OCR - extracts Chinese text and records confidence scores.
4. Translation - produces a literal Chinese-to-English translation.
5. Paraphrase - optionally turns the literal translation into natural dialogue while preserving the meaning and glossary terms.
6. Rendering - removes the original text and typesets English onto the page.
7. QA - reports missing text, untranslated regions, overflow, glossary conflicts, and rendering failures.
8. Package - optionally creates ZIP or CBZ output.

Packaging is an optional terminal operation. It does not change the chapter's pipeline stage in manifest.json.

Supported input and output

Supported inputs:

• CBZ archives
• ZIP archives
• Folders containing JPG, JPEG, PNG, or WEBP images

PDF import is not currently implemented.

Supported package formats:

zip and cbz. CBZ is the preferred comic-reader/upload format; ZIP is provided for generic archive compatibility. PDF and TAR are not produced by Stage 7.

How to choose a workflow

The translation and paraphrase stages can use different backends. Configure them independently in config.py.

| Backend | Description | Suitable when | | -------- | --------------------------------------------------------------- | --------------------------------------------------- | | manual | Writes a JSON prompt bundle. You provide and save the response. | You want full control or do not have a local model. | | mcp | Exposes pending work through the included MCP server. | You use an MCP-capable agent or client. | | ollama | Sends requests to a local Ollama server. | You want an automated local workflow. |

The current defaults are:

TRANSLATOR_BACKEND = "ollama"
PARAPHRASE_BACKEND = "mcp"

This combination uses Ollama for literal translation and an MCP client for language refinement. For a fully local workflow, set both backends to ollama. For a workflow without a GPU or agent integration, set one or both to manual.

Installation

Python 3.10 or newer is required.

git clone https://github.com/aklid01/manhua.git
cd manhua
python -m venv .venv

Activate the virtual environment, then install the core dependencies:

# macOS/Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

pip install -r requirements.txt

The core dependencies include the detection models, PaddleOCR, image processing, Transformers support, and the MCP server. Detection and OCR models may download from their model providers on first use and are then cached locally.

Optional GUI and touch-up editor

The guided runner and the standalone touch-up editor require PyQt6 and the additional packages in requirements-touchup.txt:

pip install -r requirements-touchup.txt

The touch-up editor can open a page or chapter, select regions, run OCR and translation, erase source text, position English text, and save the edited page.

Quick start

1. Choose the series output directory

The pipeline stores all chapter workspaces below one series directory. Set it once with:

python pipeline.py --set-output-dir "/path/to/series"

This saves the setting in settings.json. You can override it for one run with --output-dir.

2. Configure translation

For local translation and paraphrasing, make sure Ollama is installed and running, then pull the configured model:

ollama pull translategemma:4b

Set the backends in config.py:

TRANSLATOR_BACKEND = "ollama"
PARAPHRASE_BACKEND = "ollama"

Alternatively, keep PARAPHRASE_BACKEND = "mcp" or use manual for either stage. The pipeline pauses when external input is required and can be resumed after the response is supplied.

3. Process a chapter

python pipeline.py run-all --input "/path/to/chapter_001.cbz" --package cbz

You can also run the guided GUI:

python pipeline_gui.py

The GUI lets you choose the series directory and chapter input, run stages in order, resume pending handoffs, view logs, package output, and open a rendered page in the touch-up editor.

Command-line usage

pipeline.py provides a command for every processing stage. Each command operates on a chapter workspace and can be rerun independently.

Run individual stages

python pipeline.py import      --input chapter_001.cbz
python pipeline.py detect      --chapter chapter_001
python pipeline.py ocr         --chapter chapter_001
python pipeline.py translate   --chapter chapter_001
python pipeline.py paraphrase  --chapter chapter_001
python pipeline.py render      --chapter chapter_001
python pipeline.py qa          --chapter chapter_001

The import command also accepts a folder of images. When starting from import, you can add metadata such as --title-en, --title-romanized, and --source.

Run or resume the complete pipeline

# Start from import
python pipeline.py run-all --input chapter_001.cbz

# Resume an existing chapter at a later stage
python pipeline.py run-all --chapter chapter_001 --from-stage paraphrase

# Import while skipping trailing promotional or credit pages
python pipeline.py run-all --input chapter_001.cbz --skip-last 2

Use --fresh with import or run-all when you intentionally want to remove the existing stage artifacts for that chapter and start again.

Process a folder of chapters

python pipeline.py batch --input "/path/to/chapter-files" --package cbz

Batch processing accepts .cbz and .zip files, resumes incomplete chapter folders by default, skips completed chapters, and continues after an error. Use --no-resume to skip any chapter folder that already exists.

Package rendered pages

python pipeline.py package --chapter chapter_001 --package zip,cbz

The package command reads images from stage5_render/rendered/ and writes the requested files to stage7_package/.

Resolve manual overrides

QA creates an overrides.json file when a region needs attention. You can edit that file directly or use the interactive resolver:

python pipeline.py resolve-overrides --chapter chapter_001

After changing an override, rerun translate, paraphrase, render, and qa as appropriate.

Translation recovery and contextual retry

The local Ollama translator is best-effort. When it cannot produce a valid translation for a meaningful region, the original CJK text is handed to Stage 4, where the stronger paraphrase backend performs a combined translate-and-paraphrase recovery. This is the normal path when PARAPHRASE_BACKEND = "mcp".

Stage 3's extra one-region contextual retry is disabled by default because it duplicates work before the stronger Stage 4 backend runs. Enable OLLAMA_CONTEXTUAL_RETRY_ENABLED = True only when a local contextual retry is preferred or Stage 4 recovery is unavailable. Single-character CJK/SFX passthrough remains a separate route and is not affected.

Common options

| Option | Commands | Purpose | | ----------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------ | | --input PATH | import, run-all, batch | Input archive, image folder, or batch folder. | | --chapter NAME | Most stages, package, resolve-overrides | Chapter folder name below the series directory. | | --workspace PATH | Most stages | Use a specific relative or absolute workspace path. | | --output-dir PATH | Top level | Override the configured series directory for one run. | | --set-output-dir PATH | Top level | Persist the series directory and exit. | | --fresh | import, run-all, batch | Remove prior stage artifacts before importing. | | --skip-last N | import, run-all, batch | Mark the final N pages as skipped. | | --from-stage NAME | run-all | Resume from import, detect, ocr, translate, paraphrase, render, or qa. | | --package FORMATS | run-all, batch, package | Comma-separated zip and/or cbz. | | --no-resume | batch | Skip existing chapter folders instead of resuming them. |

Run python pipeline.py --help or python pipeline.py <command> --help for the complete parser help.

Chapter workspace

Each chapter is self-contained. A typical workspace looks like this:

your-series/
|-- glossary.json
`-- chapter_001/
    |-- manifest.json
    |-- overrides.json
    |-- pages/
    |-- stage1_detection/
    |   `-- detection.json
    |-- stage2_ocr/
    |   |-- ocr.json
    |   `-- ocr_review.json       # only when review items exist
    |-- stage3_translation/
    |   |-- translation.json
    |   |-- translation_prompt.json
    |   `-- translation_response.json
    |-- stage4_paraphrase/
    |   |-- paraphrase.json
    |   |-- paraphrase_prompt.json
    |   `-- paraphrase_response.json
    |-- stage5_render/
    |   |-- render.json
    |   `-- rendered/
    |-- stage6_qa/
    |   `-- qa.json
    |-- stage7_package/
    `-- logs/

Not every optional file is present in every run. manifest.json records the chapter metadata, page list, current stage, completed stages, and QA status. The JSON artifacts are the handoff points between stages and are intended to be readable for debugging or manual review.

The series-level glossary.json stores locked names and terms. Chapter-level overrides.json stores region-specific corrections.

Configuration

Most settings are in config.py. The most commonly changed values are:

| Area | Settings | | ------------ | --------------------------------------------------------------------------------------------- | | Translation | TRANSLATOR_BACKEND, OLLAMA_TRANSLATE_MODEL, OLLAMA_HOST | | Paraphrasing | PARAPHRASE_BACKEND, OLLAMA_PARA_MODEL, OLLAMA_PARA_HOST | | OCR | OCR_ENGINE, OCR_VERSION, OCR_CONFIDENCE_THRESHOLD,