Tính Năng Cốt Lõi

1. Cơ Chế Xử Lý Streaming Thời Gian Thực (Time-to-First-Read ~1.5s)

• Trang đầu tiên được tải, định vị khung thoại và hiển thị bản dịch tiếng Việt sau khoảng 1.5 giây.
• Xử lý bất đồng bộ đa luồng (tối đa 10 workers song song). Dữ liệu được ghi đĩa và gửi lên giao diện ngay khi từng trang hoàn thành, không bắt buộc tải toàn bộ chương truyện.

2. Hỗ Trợ Đa Mô Hình OCR (Torchless Architecture)

Sử dụng 3 mô hình ONNX chuyên dụng chạy qua DirectML, không phụ thuộc vào thư viện PyTorch:

• Manga-OCR (Tiếng Nhật): Chuyên biệt nhận diện chữ Hán (Kanji), chữ dọc (Tate-gaki), Furigana và chữ viết tay trong Manga gốc.
• RapidOCR (Tiếng Anh / Ký tự Latinh): Tối ưu bóc tách các font Comic in hoa nghệ thuật, bảo toàn dấu cách và cấu trúc câu scanlation.
• RapidOCR (Tiếng Trung): Nhận diện chữ Hán Giản thể và Phồn thể trong Manhua Trung Quốc.

3. Tự Động Nhận Diện Ngôn Ngữ & Khóa Cứng Thủ Công

• Smart Auto-Detect: Tự động đọc mã ngôn ngữ chương truyện trên MangaDex để chuyển đổi mô hình OCR phù hợp (ja sang Manga-OCR, zh sang RapidOCR Trung, en sang RapidOCR Anh).
• Manual Override: Cho phép cố định một mô hình OCR trên thanh điều khiển để loại trừ lỗi gán sai cờ ngôn ngữ từ phía người đăng tải.

4. Hai Nhánh Pipeline Linh Hoạt (Dual-Pipeline Architecture)

• Pipeline 1: OCR + Dịch:
  • Dịch tự động qua Google Translate API (miễn phí, không cần API Key, phản hồi ~150ms/trang).
  • Hoặc dịch qua LLM Text-only (Qwen 3.5, Gemini 2.0 Flash, Claude, GPT-4o) nhằm tiết kiệm hơn 90% chi phí token so với mô hình Vision.
• Pipeline 2: Image + Vision LLM: Đánh số khung thoại Set-of-Mark [1], [2] trên ảnh gốc và gửi tới Vision Multimodal AI để dịch bám sát biểu cảm nhân vật.

5. Giao Diện Sổ Tay Độc Bản (Hand-Drawn Notebook Design System)

• Thiết kế theo phong cách sổ tay phác thảo truyện tranh:
  • Bảng màu giấy ấm #fdfbf7, hoa văn chấm bi giấy ghi chú, nét chì mềm #2d2d2d, bút dạ đỏ #ff4d4d.
  • Toàn bộ khung viền, nút bấm mang hình dáng wobbly hữu cơ bất đối xứng kết hợp bóng đổ cứng (hard offset shadow 4px).
  • Hệ thống icon vector SVG nét chì vẽ tay đồng bộ, loại bỏ hoàn toàn emoji hệ điều hành.
  • Tích hợp Trình Đọc và Cài Đặt trên cùng một ứng dụng SPA (Single-Page App), chuyển đổi không làm mới trang và bảo lưu trạng thái đọc.

6. An Toàn & Bảo Mật Cục Bộ

• Toàn bộ khóa API và dữ liệu cá nhân được lưu trữ cục bộ trên máy trạm.
• Tự động che mờ API Key trên giao diện, hỗ trợ quản lý nhiều cấu hình độc lập (Multi-Profile).

Kiến Trúc Hệ Thống

flowchart TD
    subgraph Frontend["FRONTEND CLIENTS"]
        MD["MangaDex Userscript<br/>(Tampermonkey Overlay)"]
        WR["Local Web Reader<br/>(Hand-Drawn Sketchbook SPA)"]
    end

    subgraph Server["LOCAL BACKEND SERVER (overlay_server.py:8765)"]
        API["REST Endpoints & Static Files Routing"]
    end

    subgraph Pipeline["STREAMING PIPELINE (mangadex_batch_translator.py)"]
        Fetcher["1. MangaDex Prefetcher<br/>(Async Image Fetching)"]
        Detector["2. Comic-Text-Detector ONNX<br/>(DirectML GPU AMD/NVIDIA/Intel)"]
        
        subgraph BranchA["Pipeline A: OCR + Dịch (Tối ưu tốc độ)"]
            OCR["3. OCR Engine Selector<br/>├─ Manga-OCR (Tiếng Nhật)<br/>├─ RapidOCR (Tiếng Anh)<br/>└─ RapidOCR (Tiếng Trung)"]
            Translator["4. Bộ Dịch Thuật<br/>├─ Google Dịch (Free ~150ms)<br/>├─ LLM Text (Qwen/Gemini/OpenAI)<br/>└─ Raw OCR (Giữ nguyên gốc)"]
            OCR --> Translator
        end

        subgraph BranchB["Pipeline B: Multimodal Vision"]
            SoM["3. Set-of-Mark Annotator<br/>(Đánh số [1], [2] lên tranh)"]
            VisionLLM["4. Vision LLM<br/>(Gemini 2.0 / Qwen 3.5 VL)"]
            SoM --> VisionLLM
        end

        Dispatcher["5. Real-Time Dispatcher<br/>(Lưu file JSON & Gửi dữ liệu từng trang)"]
    end

    MD <-->|HTTP REST / CORS| API
    WR <-->|HTTP REST / CORS| API
    API --> Pipeline
    Fetcher --> Detector
    Detector --> BranchA
    Detector --> BranchB
    BranchA --> Dispatcher
    BranchB --> Dispatcher
    Dispatcher -->|Render tức thì ~1.5s| Frontend

Hướng Dẫn Cài Đặt (Windows)

Bước 1: Yêu Cầu Môi Trường

1. Cài đặt Python (phiên bản khuyến nghị: 3.10, 3.11 hoặc 3.12) từ python.org.

   [!IMPORTANT] Trong quá trình cài đặt, bắt buộc tích chọn ô: "Add python.exe to PATH".

2. Cài đặt tiện ích mở rộng Tampermonkey trên trình duyệt (Chrome / Edge / Brave | Firefox).

Bước 2: Tải Mã Nguồn & Cài Đặt Tự Động

1. Clone mã nguồn về máy:

   git clone https://github.com/thailong2103/manga-translator-mvp-demo.git
   cd manga-translator-mvp-demo
   

2. Khởi chạy file cài đặt tự động:
   • Nhấp đúp vào install_requirements.bat.
   • Script sẽ thiết lập môi trường ảo .venv, cài đặt thư viện cần thiết và tải sẵn 3 mô hình AI (comic-text-detector.onnx, manga-ocr-onnx, rapidocr).

Bước 3: Khởi Động Hệ Thống

1. Nhấp đúp vào file start_server.bat:
   • Máy chủ cục bộ sẽ chạy tại http://127.0.0.1:8765.
   • Trình duyệt tự động mở giao diện MangaStream Web Reader.
2. Cài đặt Userscript cho MangaDex:
   • Trên thanh điều hướng của Web Reader, bấm chọn MangaDex Script.
   • Chọn Cài Đặt Userscript (1-Click) và xác nhận trên tab Tampermonkey.

Hướng Dẫn Sử Dụng

1. Đọc Trực Tiếp Trên MangaDex

• Mở bất kỳ chương truyện nào trên mangadex.org.
• Thanh công cụ điều khiển xuất hiện ở góc dưới bên phải màn hình:
  • Bấm Dịch Chapter Này để kích hoạt pipeline xử lý.
  • Sử dụng phím tắt T để bật hoặc tắt lớp phủ bản dịch tiếng Việt.
  • Chọn trực tiếp mô hình OCR (Manga JP hoặc Rapid EN) trên thanh công cụ nếu truyện bị gán sai nhãn ngôn ngữ.

2. Đọc Truyện Scan Cục Bộ (Local Web Reader)

• Truy cập http://127.0.0.1:8765 trên trình duyệt.
• Bấm Thêm Truyện hoặc kéo thả thư mục ảnh (.jpg, .png, .webp) trực tiếp vào màn hình.
• Tùy chọn chế độ hiển thị:
  • Cuộn: Phù hợp cho định dạng Webtoon cuộn dọc liên tục.
  • Lật trang: Đọc từng trang với phím điều hướng ← / → hoặc A / D.
• Sử dụng nút tinh chỉnh hiển thị để điều chỉnh độ mờ nền bong bóng và tỷ lệ cỡ chữ.

3. Cấu Hình Dịch Thuật & API

• Chuyển sang tab Cài Đặt trên thanh điều hướng chính.
• Mặc định hệ thống sử dụng Google Translate miễn phí, không yêu cầu API Key.
• Khi sử dụng các mô hình LLM (Qwen, Gemini, Claude, OpenAI):
  1. Chọn nhà cung cấp từ danh sách mẫu (xKiro API, Google Gemini, OpenRouter, Groq, Ollama).
  2. Điền khóa API và kiểm tra kết nối qua nút Kiểm Tra Kết Nối.
  3. Bấm Lưu Cấu Hình Ngay để áp dụng thay đổi.

Bảng So Sánh Kỹ Thuật

So Sánh Các Engine OCR

So Sánh Các Nhà Cung Cấp Dịch Thuật

Bảng Phím Tắt Điều Khiển

Yêu Cầu Phần Cứng & Khả Năng Tương Thích

• Hệ điều hành: Windows 10 hoặc Windows 11 (yêu cầu hỗ trợ DirectX 12).
• Bộ xử lý đồ họa (GPU):
  • AMD Radeon (Card rời RX 5000/6000/7000 hoặc đồ họa tích hợp Radeon 680M/780M).
  • NVIDIA GeForce (GTX 10-series, RTX 20/30/40 series).
  • Intel Arc hoặc Intel Iris Xe Graphics.
• Dự phòng CPU: Tự động chuyển đổi sang xử lý bằng CPU nếu hệ thống không có GPU tương thích.
• Bộ nhớ RAM: Tối thiểu 4 GB RAM khả dụng.

Khắc Phục Sự Cố (Troubleshooting)

.\.venv\Scripts\python.exe download_models.py --check

Đóng Góp & Giấy Phép

Dự án được phát hành theo giấy phép mã nguồn mở MIT License. Chi tiết vui lòng xem tại file LICENSE.

Mọi đóng góp, báo cáo lỗi và đề xuất tính năng xin vui lòng gửi về: GitHub Issues.