lemon-manga-translator

일본어 → 한국어 만화(망가) 자동 번역 파이프라인.

한 페이지를 받아 텍스트 영역을 검출하고, Vision LLM으로 SFX 분류 + 번역을 동시에 수행한 뒤, AOT 인페인팅으로 원문을 지우고 그 위에 한국어 텍스트를 렌더한다.

Quick Start

pip install lemon-manga-translator

from lemon_manga_translator import MangaTranslator
from PIL import Image

mt = MangaTranslator(
    openrouter_api_key="sk-or-...",
    openrouter_model="google/gemini-3.1-flash-lite-preview",
)
mt.prepare()  # HuggingFace에서 ONNX 모델 자동 다운로드

image = Image.open("page.jpg")
result = mt.translate(image)
result.save("output.png")

prepare() 호출 시 lemondouble/lemon-manga-translator에서 ONNX 모델(CTD 77 MB + AOT 23 MB)을 다운로드한다. 이후 캐시되어 재다운로드하지 않는다.

로컬 모델 사용

mt = MangaTranslator(
    openrouter_api_key="sk-or-...",
    openrouter_model="google/gemini-3.1-flash-lite-preview",
    model_source="/path/to/local/models",  # HF 대신 로컬 경로
)

파이프라인

원본 이미지 ──▶ 1) CTD 검출 ──▶ 2) 마스크 제한 ──▶ 3) Vision LLM ──▶ 4) SFX 드롭
                                                                         │
                                                                         ▼
   최종 이미지 ◀── 7) 텍스트 렌더 ◀── 6) 말풍선 확장 ◀── 5) AOT 인페인트

GPU 사용

device="cuda"를 지정하면 ONNX 추론(CTD, AOT)이 GPU에서 실행된다.

mt = MangaTranslator(
    openrouter_api_key="sk-or-...",
    openrouter_model="google/gemini-3.1-flash-lite-preview",
    device="cuda",
)

GPU 사용 시 onnxruntime 대신 환경의 CUDA 버전에 맞는 onnxruntime-gpu를 직접 설치해야 한다. 자세한 호환성은 onnxruntime 공식 문서 참고.

튜닝

각 단계의 하이퍼파라미터는 dataclass로 노출되어 있다. MangaTranslator 생성자에 주입하면 단계 동작을 바꿀 수 있고, 미지정 시 라이브러리 기본값을 사용한다.

from lemon_manga_translator import (
    MangaTranslator,
    CtdConfig,
    BubbleConfig,
    PipelineConfig,
    RenderConfig,
)

mt = MangaTranslator(
    openrouter_api_key="sk-or-...",
    openrouter_model="google/gemini-3.1-flash-lite-preview",
    ctd_config=CtdConfig(confidence_threshold=0.4),
    bubble_config=BubbleConfig(max_area_ratio=0.06),
    pipeline_config=PipelineConfig(expand_bubbles=True),
    render_config=RenderConfig(min_font_size=12, max_font_size=64),
    vision_system_prompt="path/to/custom_prompt.txt",  # 파일 경로 또는 문자열
)

기본 Vision 시스템 프롬프트는 lemon_manga_translator/prompts/vision_system.txt에 동봉되어 있다.

배경 마스킹

Vision LLM에 보내는 이미지에서 텍스트 bbox 바깥 영역을 마스킹할 수 있다. 배경 정보를 줄여 LLM이 텍스트에 집중하도록 유도하는 옵션.

from lemon_manga_translator import MangaTranslator

mt = MangaTranslator(
    openrouter_api_key="sk-or-...",
    openrouter_model="google/gemini-3.1-flash-lite-preview",
    bg_mask_mode="blur",  # "none" | "solid" | "blur" | "overlay"
)

테스트 스크립트에서도 --bg-mask 플래그로 사용 가능:

uv run python scripts/test_pipeline.py image.jpg --bg-mask blur

배치 번역

여러 페이지를 병렬로 번역할 수 있다. 내부적으로 ThreadPoolExecutor를 사용하며, 입력 순서가 보장된다.

images = [Image.open(p) for p in page_paths]
results = mt.translate_batch(images, max_workers=4)

for i, r in enumerate(results):
    r.save(f"output_{i:03d}.png")

내부 컴포넌트가 stateless라 단일 인스턴스를 스레드 간 공유해도 안전하다.

진행 상황 콜백

on_progress를 넘기면 각 단계를 시작할 때 PipelineStage로 호출된다. 텍스트가 없는 페이지는 DETECT 이후 바로 끝난다.

from lemon_manga_translator import PipelineStage

def on_progress(stage: PipelineStage) -> None:
    print(stage)  # detect → translate → inpaint → render

result = mt.translate(image, on_progress=on_progress)

on_stage_done을 넘기면 각 단계가 끝날 때 StageResult로 중간 결과를 받는다.

번역 수정 후 다시 렌더

translations에 VisionBlockResult 목록을 넘기면 Vision LLM을 호출하지 않고 그 번역으로 인페인트·렌더만 다시 한다. 같은 이미지는 검출 결과가 같으므로 block_index가 그대로 유지된다. no_translate=True인 블록은 지우지 않고 원문을 남긴다.

from dataclasses import replace

first = []
mt.translate(image, on_stage_done=lambda result: first.extend(result.vision_results or []))

edited = [replace(first[0], ko_translation="수정한 번역")] + first[1:]
result = mt.translate(image, translations=edited)

로깅

라이브러리는 표준 logging 모듈로 단계별 진행 상황을 INFO 레벨로 기록한다. 호출자가 핸들러를 설정하면 실시간 로그가 보인다.

import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
    datefmt="%H:%M:%S",
)

mt = MangaTranslator(...)
mt.prepare()
mt.translate(image)

샘플 출력:

11:53:10 INFO lemon_manga_translator.pipeline: 페이지 처리 시작 (크기=1200x1800)
11:53:10 INFO lemon_manga_translator.pipeline: [1/7] CTD 검출 완료: 텍스트 12블록
11:53:11 INFO lemon_manga_translator.pipeline: [3/7] Vision LLM 완료 (시도=1회, 대사=11, SFX/제외=3)
11:53:13 INFO lemon_manga_translator.pipeline: [7/7] 텍스트 렌더 완료 (11블록)

Docker

pre_download()로 빌드 시 모델을 미리 캐싱하면 컨테이너 시작 시 다운로드 없이 바로 사용할 수 있다.

FROM python:3.11-slim

RUN pip install lemon-manga-translator

# 빌드 시 ONNX 모델을 캐시에 다운로드 (세션 로드 없음)
RUN python -c "from lemon_manga_translator import MangaTranslator; \
    MangaTranslator.pre_download()"

COPY server.py .
CMD ["python", "server.py"]

# server.py — prepare()는 캐시에서 즉시 로드
mt = MangaTranslator(
    openrouter_api_key=os.environ["OPENROUTER_API_KEY"],
    openrouter_model="google/gemini-3.1-flash-lite-preview",
)
mt.prepare()

Debug

from lemon_manga_translator.api.debug_translator import DebugTranslator

dt = DebugTranslator(
    openrouter_api_key="sk-or-...",
    openrouter_model="google/gemini-3.1-flash-lite-preview",
)
dt.prepare()

image = Image.open("page.jpg")
result = dt.translate(image, debug_dir="./debug/")

result.detection       # CTD 결과 (mask + text_blocks)
result.inpainted       # AOT 인페인트 결과
result.vision_results  # LLM 응답 (block_index, is_sfx, ko_translation)
result.save_all("./debug/")

debug_dir를 지정하면 각 단계의 중간 산출물이 파일명 prefix로 정렬되어 저장된다.

Dev Playground

파라미터를 바꿔가며 단계별로 결과를 확인하는 로컬 디버깅 GUI(dev-tools/playground)가 별도로 들어 있다 — 라이브러리 PyPI 패키지에는 포함되지 않는다. 사용법은 dev-tools/README.md 참고.

모델·코드·폰트 출처

모델 가중치는 lemondouble/lemon-manga-translator에서 PyTorch(safetensors) + ONNX 형태로 제공된다.

License

GPL-3.0