lemon-manga-translator

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

학습된 검출 모델로 글자와 말풍선을 찾고, Vision LLM으로 읽기와 번역을 함께 처리합니다. 번역문을 배치할 수 있는 영역의 원문을 지우고 한국어를 그립니다.

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",
)
mt.prepare()  # HuggingFace에서 ONNX 모델 자동 다운로드

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

prepare()는 Koharu Layout ONNX의 글자·말풍선 검출 모델과 AOT를 내려받아 캐시합니다. 검출 모델 버전은 고정되어 있습니다. 모델의 사용 조건은 각각의 모델 카드를 확인해야 합니다.

• 기본 번역 범위는 대사·내레이션·제목·이름표·표지판입니다. 색상이 있거나 손글씨·장식체여도 이 범위에 해당하면 번역합니다.
• 효과음·저작권 표시·읽을 수 없는 글자와 상품 포장에 인쇄된 상품명·작은 장식 글자는 보존합니다. 포장의 상품명·작은 장식 글자는 읽혀도 no_translate=true, ko_translation=null로 처리합니다.
• 작은 글자와 검출이 누락된 글자의 번역은 보장하지 않습니다. 원문 색상은 자동 복원하지 않습니다.
• 기존 CTD 검출은 detector="ctd"로 선택할 수 있습니다.

로컬 모델 사용

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

로컬 모델은 onnx/layout/rfdetr-seg-2xlarge.onnx, onnx/aot-inpainting/aot_folded.onnx, pytorch/aot-inpainting/config.json에 둡니다. CTD를 선택하면 검출 모델 경로는 onnx/comic-text-detector/ctd.onnx입니다.

파이프라인

원본 → 글자·말풍선 검출 → Vision 읽기·번역 → 응답·배치 검증 → 원문 삭제 → 한국어 합성

GPU 사용

device="cuda"를 지정하면 ONNX 추론을 GPU에서 실행합니다. CUDA provider 초기화에 실패하면 오류를 반환합니다.

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

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

튜닝

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

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

mt = MangaTranslator(
    openrouter_api_key="sk-or-...",
    openrouter_model="google/gemini-3.1-flash-lite",
    layout_config=LayoutConfig(text_confidence_threshold=0.25),
    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에 동봉되어 있다.

• 기본 openrouter_response_mode="standard"는 각 블록의 id, text_kind, no_translate, ko_translation을 받습니다. openrouter_response_mode="compact_reading"는 같은 호출에서 일본어를 먼저 읽고 [id, text_kind, ja_source, ko_translation] 배열을 JSON schema로 받습니다. 번역할 때 일본어 원문도 비어 있지 않아야 하며, 보존할 때는 번역을 null로 반환합니다. 공개 결과 형식은 같습니다.
• 사용자 정의 프롬프트는 선택한 모드의 응답 형식을 따라야 합니다. text_kind는 기본 프롬프트의 분류 값 중 하나이며, 포장 상품명·장식 글자·효과음·기타·불확실한 글자는 코드에서 원문을 보존합니다. 수동 번역의 VisionBlockResult 형식은 세 필드를 유지합니다.

배경 마스킹

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",
    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인 블록은 지우지 않고 원문을 남긴다.

text_boxes로 추가하거나 바꾼 박스는 해당 사각형을 삭제·배치 영역으로 사용합니다. 좌표를 바꾸지 않은 박스는 학습 검출의 mask를 유지합니다. block_index는 박스 순서입니다. 수동 번역에서 no_translate=False와 빈 번역문을 함께 보내면 해당 원문만 지웁니다.

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",
)
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",
)
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