MangaTranslator

MangaTranslator là công cụ dịch và render chữ cho manga/comic. Ứng dụng hỗ trợ xử lý từng ảnh, batch nhiều ảnh, xuất script để dịch thủ công bằng LLM, import lại script đã dịch để render, xử lý chữ ngoài bubble, upscale và decensor/inpaint.

Tính năng chính

• Dịch manga/comic bằng Google Gemini, OpenAI, Anthropic, xAI, DeepSeek, Z.ai, Moonshot AI, OpenRouter hoặc endpoint OpenAI-Compatible.
• Hỗ trợ Google-compatible proxy nếu bạn có proxy riêng.
• Web UI bằng Gradio.
• Xử lý single image, batch folder, batch ZIP.
• Advanced Mode: export script chưa dịch, sửa/dịch TXT thủ công, rồi import TXT + JSON để render lại.
• Chọn font pack riêng, chỉnh size, màu chữ, padding, hướng chữ.
• Xử lý chữ ngoài bubble bằng inpainting/Flux.
• Decensor: detect mask preview, sửa mask bằng brush, brush màu đen để xóa mask, restore bằng Flux Klein/Kontext.

Cài đặt

Khuyến nghị Python 3.10, 3.11 hoặc 3.12. Trên Windows nên tạo virtual environment riêng.

cd F:\tool\MangaTranslator
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

Nếu dùng GPU NVIDIA, cài PyTorch CUDA phù hợp với máy. Ví dụ CUDA 12.1:

pip install --index-url https://download.pytorch.org/whl/cu121 torch torchvision

Kiểm tra GPU:

nvidia-smi
python -c "import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU')"

Chạy Web UI

cd F:\tool\MangaTranslator
.\.venv\Scripts\Activate.ps1
python app.py --open-browser

Mặc định UI chạy tại:

http://127.0.0.1:7676

Đổi port:

python app.py --port 7860 --open-browser

Chạy CPU:

python app.py --cpu --open-browser

Font Pack

Nếu gặp lỗi thiếu font pack, tạo thư mục font theo cấu trúc:

fonts/
  Arial/
    arial.ttf
    arialbd.ttf
    ariali.ttf
    arialbi.ttf

Trong UI, chọn font pack trong phần font/rendering. Nếu dịch tiếng Việt, nên dùng font hỗ trợ dấu tiếng Việt như Arial, Noto Sans, Roboto, Inter hoặc font Việt hóa bạn tự thêm.

API Key Và Proxy

Trong UI, vào phần provider/API:

• Provider: Google, OpenAI, Anthropic, OpenRouter, hoặc provider bạn dùng.
• Model: ví dụ gemini-2.5-flash nếu dùng Google.
• Google API Key: dùng key Google trực tiếp.
• Google Proxy API Key: dùng key proxy nếu bạn có proxy Google-compatible.
• Google Proxy Base URL: dùng base URL proxy của bạn.

Nếu dùng Google-compatible proxy, nhập đủ 2 field:

Google Proxy API Key = <proxy-api-key>
Google Proxy Base URL = <proxy-base-url>

Khi có đủ proxy key và proxy base URL, project sẽ gọi Gemini qua proxy thay vì gọi trực tiếp Google.

Có thể dùng biến môi trường:

$env:GOOGLE_API_KEY="AIzaSy..."
$env:GOOGLE_PROXY_API_KEY="<proxy-api-key>"
$env:GOOGLE_PROXY_BASE_URL="<proxy-base-url>"

Các biến môi trường khác:

OPENAI_API_KEY
ANTHROPIC_API_KEY
XAI_API_KEY
DEEPSEEK_API_KEY
ZAI_API_KEY
MOONSHOT_API_KEY
OPENROUTER_API_KEY
OPENAI_COMPATIBLE_API_KEY

Không commit API key, token, config cá nhân, output ảnh, model cache hoặc venv lên git.

Nơi Lưu Config

UI lưu config cá nhân ngoài repo:

C:\Users\<TenUser>\AppData\Local\MangaTranslator\config.json

Trước khi push code:

git status --short

Workflow Khuyến Nghị Cho Batch

Với manga nhiều trang, nên dùng Advanced Mode để tách OCR/script và render.

Bước 1: Export Script

Trong Web UI:

1. Vào tab Batch.
2. Upload folder ảnh hoặc ZIP.
3. Chọn Advanced Mode (export untranslated script only).
4. Bấm Start Batch.

Sau khi xong, output thường có:

output/batch_output/manga_script.json
output/batch_output/manga_script_original.txt
output/batch_output/manga_script_translated.txt

Ý nghĩa:

• manga_script.json: dữ liệu bubble, bbox, orientation. Không sửa nếu không biết rõ.
• manga_script_original.txt: script OCR gốc.
• manga_script_translated.txt: file bạn sửa/dịch rồi import để render.

Bước 2: Dịch TXT

Chỉ sửa manga_script_translated.txt.

Giữ format:

=== PAGE: 03_02.png ===
1: Câu dịch tiếng Việt[direction:horizontal]
2: Câu tiếp theo[direction:horizontal]
3: [OCR FAILED]

Quy tắc:

• Giữ nguyên dòng === PAGE: file ===.
• Giữ nguyên số thứ tự 1:, 2:, 3:.
• Không xóa dòng.
• Không tách một câu thành nhiều dòng.
• Giữ tag [Bubble], [OSB] nếu có.
• Với tiếng Việt, ưu tiên thêm [direction:horizontal] để tránh chữ bị xếp dọc.

Bước 3: Import Và Render

Trong Web UI:

1. Vào tab Batch.
2. Chọn Advanced Mode (import translated script and render).
3. Upload manga_script_translated.txt.
4. Upload manga_script.json.
5. Chọn font, size, màu chữ, padding.
6. Bấm Start Batch để render ảnh.

Tag Style Theo Dòng

Có thể thêm tag ở cuối dòng:

[font:TenFont,size:80,direction:horizontal]

Ví dụ:

=== PAGE: 40_038.jpg ===
1: Rầm![font:Arial,size:100,direction:horizontal]
2: A...[size:60,direction:horizontal]
3: Đợi đã[direction:horizontal]

Thuộc tính:

• font: tên thư mục font trong fonts/.
• size: cỡ chữ mong muốn.
• direction: horizontal hoặc vertical.

Với tiếng Việt, gần như luôn dùng:

direction:horizontal

Decensor / Restore

Tab Decensor dùng để detect vùng censor, sửa mask, rồi restore/inpaint.

Luồng khuyến nghị:

1. Upload ảnh vào ImageEditor.
2. Chọn mode auto hoặc hybrid.
3. Chọn target type: bar, mosaic, solid patch.
4. Bấm Detect Mask Preview.
5. Sửa mask trong editor:
   • Brush đỏ/xanh: thêm mask.
   • Brush đen: xóa mask khi bấm Detect Preview lại.
   • Eraser native có thể dùng, nhưng nếu ảnh lớn gây lag WebGL thì ưu tiên brush đen.
6. Bấm Detect Mask Preview lại để kiểm tra mask sau khi sửa.
7. Bấm Restore để chạy inpaint.

Gợi ý mask:

• Tô phủ hết thanh censor và lấn nhẹ ra ngoài 3-8px.
• Nếu ảnh rất lớn, có thể lấn 8-15px.
• Tô luôn mép blur/anti-alias của censor.
• Không tô quá rộng vào vùng chi tiết quan trọng nếu không cần.

Flux gợi ý:

• Máy VRAM thấp: dùng Flux Klein 4B, bật Low VRAM/CPU Offload, steps 6-8.
• Flux Klein 9B nặng hơn, chỉ nên thử với mask nhỏ.
• Flux Kontext nên ưu tiên backend SDNQ nếu máy ít VRAM.

Chạy CLI

Web UI là cách dễ dùng nhất. CLI phù hợp khi cần script hóa.

Dịch một ảnh:

python main.py --input "input\page.png" --output "output\page.png" --provider Google --google-api-key "AIzaSy..." --model-name "gemini-2.5-flash" --output-language Vietnamese --font-dir ".\fonts"

Dùng Google-compatible proxy:

python main.py --input "input\page.png" --output "output\page.png" --provider Google --google-proxy-api-key "<proxy-api-key>" --google-proxy-base-url "<proxy-base-url>" --model-name "gemini-2.5-flash" --output-language Vietnamese --font-dir ".\fonts"

Batch thư mục:

python main.py --input "input\chapter" --output "output\chapter" --batch --provider Google --google-api-key "AIzaSy..." --model-name "gemini-2.5-flash" --output-language Vietnamese --font-dir ".\fonts"

Khuyến nghị dùng biến môi trường thay vì ghi API key trực tiếp trong terminal nếu bạn quay màn hình hoặc chia sẻ log.

Lỗi Thường Gặp

OpenAI-Compatible gọi nhầm endpoint cũ

Nếu log có dạng:

OpenAI-Compatible API request to http://...

và bạn đang muốn dùng Google, vào UI chọn lại:

Provider = Google
Model = gemini-2.5-flash

Sau đó lưu config.

Không có file TXT sau batch

File TXT chỉ sinh ra khi dùng Advanced Mode export script. Kiểm tra:

output/batch_output/manga_script_original.txt
output/batch_output/manga_script_translated.txt
output/batch_output/manga_script.json

Import render không đổi chữ

Kiểm tra:

• TXT và JSON phải cùng một lần export.
• Tên page trong TXT phải khớp JSON.
• ID dòng phải khớp số bubble.
• Không xóa hoặc sửa dòng === PAGE: ... ===.
• Không sửa manga_script.json nếu chỉ muốn dịch text.

Thiếu VRAM

Thử:

• Giảm số ảnh chạy cùng lúc.
• Bật Low VRAM/CPU Offload cho Flux.
• Dùng Flux Klein 4B thay vì 9B.
• Tắt upscale hoặc dùng model nhẹ hơn.
• Chạy Advanced Mode để tách OCR và render.
• Đóng app khác đang dùng GPU.

ImageEditor bị WebGL context lost

Nếu console báo:

WebGL: CONTEXT_LOST_WEBGL

thường do canvas ImageEditor quá nặng khi ảnh lớn và dùng eraser lâu. Có thể:

• Dùng brush đen để xóa mask thay vì eraser native.
• Đóng tab/app khác dùng GPU.
• Reload browser sau khi lưu trạng thái cần thiết.
• Với ảnh rất lớn, cân nhắc resize ảnh trước khi chỉnh mask.

Cấu Trúc Thư Mục

MangaTranslator/
  app.py
  main.py
  requirements.txt
  README.md
  fonts/
  models/
  output/
  ui/
  core/
  utils/

Ghi Chú Git

Không push:

• API key/token.
• Config cá nhân.
• .venv/.
• Model cache.
• Output ảnh.
• File tạm hoặc log có dữ liệu nhạy cảm.

Nên kiểm tra trước khi commit:

git status --short
git diff --check