Manga/Image Translator (English Readme)

Last Updated: 2025/05/10

One-click translation of text in various images\ 中文说明 | Changelog \ Welcome to join our Discord https://discord.gg/Ak8APNy4vb

This project aims to translate images that are unlikely to be professionally translated, such as comics/images on various group chats and image boards, making it possible for Japanese novices like me to understand the content. It mainly supports Japanese, but also supports Simplified and Traditional Chinese, English and 20 other minor languages. Supports image repair (text removal) and typesetting. This project is v2 of Qiú wén zhuǎn yì zhì.

Note: This project is still in the early stages of development and has many shortcomings. We need your help to improve it!

📂 Directory

• Showcase
• Online Version
• Rust Version
• Installation
  • Local Setup
    • Using Pip/venv (Recommended)
    • Notes for Windows Users
  • Docker
    • Run Web Server
      • Using Nvidia GPU
    • Use as CLI
    • Build Locally
• Usage
  • Local (Batch) Mode
  • Web Mode
    • Old UI
    • New UI
  • API Mode
    • API Documentation
  • Config-help Mode
• Option and Configuration
  • Recommended Options
    • Tips to Improve Translation Quality
  • Command Line Options
    • Basic Options
    • Additional Options
      • Local Mode Options
      • WebSocket Mode Options
      • API Mode Options
      • Web Mode Options
  • Configuration File
    • Render Options
    • Upscale Options
    • Translator Options
    • Detector Options
    • Inpainter Options
    • Colorizer Options
    • OCR Options
    • Other Options
  • Language Code Reference
  • Translator Reference
  • Glossary
  • Replacement Dictionary
  • Environment Variables Summary
  • GPT Configuration Reference
  • Rendering with Gimp
• Future Plans
• Support Us
  • Thanks to all contributors
• Star Growth Curve

Showcase

The following examples may not be frequently updated and may not represent the effect of the current main branch version.

Original Image	Translated Image
(Source @09ra_19ra)	(Mask)
(Source @VERTIGRIS_ART)	--detector ctd (Mask)
(Source @hiduki_yayoi)	--translator none (Mask)
(Source @rikak)	(Mask)

Online Version

Official demo site (maintained by zyddnys): https://touhou.ai/imgtrans/\ Browser script (maintained by QiroNT): https://greasyfork.org/scripts/437569

• Note: If the online version is inaccessible, it might be due to Google GCP restarting the server. Please wait a moment for the service to restart.
• The online version uses the latest version from the main branch.

Rust Version

Manga Image Translator Rust may be easier to setup as its a compiled binary

• Note: stable diffusion is not rewritten yet & only a cli version is available

Installation

Local Setup

Using Pip/venv (Recommended)

# First, ensure you have Python 3.10 or later installed on your machine
# The very latest version of Python might not be compatible with some PyTorch libraries yet
$ python --version
Python 3.10.6

# Clone this repository
$ git clone https://github.com/zyddnys/manga-image-translator.git

# Create a venv (optional, but recommended)
$ python -m venv venv

# Activate the venv
$ source venv/bin/activate

# If you want to use the --use-gpu option, please visit https://pytorch.org/get-started/locally/ to install PyTorch, which needs to correspond to your CUDA version.
# If you did not use venv to create a virtual environment, you need to add --upgrade --force-reinstall to the pip command to overwrite the currently installed PyTorch version.

# Install dependencies
$ pip install -r requirements.txt

Models will be automatically downloaded to the ./models directory at runtime.

Notes for Windows Users:

Please install Microsoft C++ Build Tools (Download, Instructions) before performing the pip install, as some pip dependencies need it to compile. (See #114).

To use CUDA on Windows, install the correct PyTorch version as described on https://pytorch.org/get-started/locally/.

Docker

Requirements:

• Docker (19.03+ for CUDA / GPU acceleration)
• Docker Compose (Optional, if you want to use the files in demo/doc folder)
• Nvidia Container Runtime (Optional, if you want to use CUDA)

This project supports Docker, with the image being zyddnys/manga-image-translator:main. This Docker image contains all the dependencies and models required for the project. Please note that this image is quite large (~15GB).

Run Web Server

You can start the Web Server (CPU) using the following command:

Note that you need to add the required environment variables using -e or --env

docker run \
  --name manga_image_translator_cpu \
  -p 5003:5003 \
  --ipc=host \
  --entrypoint python \
  --rm \
  -v /demo/doc/../../result:/app/result \
  -v /demo/doc/../../server/main.py:/app/server/main.py \
  -v /demo/doc/../../server/instance.py:/app/server/instance.py \
  -e OPENAI_API_KEY='' \
  -e OPENAI_API_BASE='' \
  -e OPENAI_MODEL='' \
  zyddnys/manga-image-translator:main \
  server/main.py --verbose --start-instance --host=0.0.0.0 --port=5003

Or use the compose file

Note that you need to add the required environment variables in the file first

docker-compose -f demo/doc/docker-compose-web-with-cpu.yml up

The Web Server starts on port 8000 by default, and the translation results will be saved in the /result folder.

Using Nvidia GPU

To use a supported GPU, please read the Docker section above first. You will need some special dependencies.

You can start the Web Server (GPU) using the following command:

Note that you need to add the required environment variables using -e or --env

docker run \
  --name manga_image_translator_gpu \
  -p 5003:5003 \
  --ipc=host \
  --gpus all \
  --entrypoint python \
  --rm \
  -v /demo/doc/../../result:/app/result \
  -v /demo/doc/../../server/main.py:/app/server/main.py \
  -v /demo/doc/../../server/instance.py:/app/server/instance.py \
  -e OPENAI_API_KEY='' \
  -e OPENAI_API_BASE='' \
  -e OPENAI_MODEL='' \
  -e OPENAI_HTTP_PROXY='' \
  zyddnys/manga-image-translator:main \
  server/main.py --verbose --start-instance --host=0.0.0.0 --port=5003 --use-gpu

Or use the compose file (for Web Server + GPU):

Note that you need to add the required environment variables in the file first

docker-compose -f demo/doc/docker-compose-web-with-gpu.yml up

Use as CLI

To use Docker via CLI (i.e., Batch Mode):

Some translation services require API keys to run, pass them to your docker container as environment variables.

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

Note: If you need to reference files on your host, you will need to mount the relevant files as volumes into the /app folder inside the container. The CLI paths will need to be the internal Docker path /app/... and not the path on your host.

Build Locally

To build the docker image locally, you can run the following command (you need to have make tool installed on your machine):

make build-image

Then test the built image, run:

Some translation services require API keys to run, pass them to your docker container as environment variables. Add environment variables in the Dockerfile.

make run-web-server

Usage

Local (Batch) Mode

# Replace <path> with the path to your image folder or file.
$ python -m manga_translator local -v -i <path>
# The results can be found in `<path_to_image_folder>-translated`.