[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-82170":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":20,"hasPages":20,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":15,"starSnapshotCount":15,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},82170,"my_manga_translator","mranex\u002Fmy_manga_translator","mranex","Chưa có thời gian viết hướng dẫn mn ơi T-T","",null,"Python",31,12,28,0,1,3,3.34,"GNU Affero General Public License v3.0",false,"main",[],"2026-06-12 02:04:23","# ⚡ MANGA TRANSLATOR STUDIO - BUỒNG LÁI DỊCH THUẬT TRUYỆN TRANH ĐA BƯỚC\n\n```text\n   __  ___                               ________                               __      __\n  \u002F  |\u002F  \u002F___ _____  ____ _____ _       \u002F_  __\u002F \u002F_  ____ _____  _____  \u002F \u002F___ _\u002F \u002F_____\u002F \u002F_\n \u002F \u002F|_\u002F \u002F __ `\u002F __ \\\u002F \u002F \u002F \u002F __ `\u002F  ______\u002F \u002F \u002F __ \\\u002F __ `\u002F __ \\\u002F ___\u002F \u002F \u002F __ `\u002F __\u002F __  \u002F __\u002F\n\u002F \u002F  \u002F \u002F \u002F_\u002F \u002F \u002F \u002F \u002F \u002F_\u002F \u002F \u002F_\u002F \u002F  \u002F_____\u002F \u002F \u002F \u002F \u002F \u002F \u002F_\u002F \u002F \u002F \u002F (__  ) \u002F \u002F \u002F_\u002F \u002F \u002F_\u002F \u002F_\u002F \u002F \u002F_  \n\u002F_\u002F  \u002F_\u002F\\__,_\u002F_\u002F \u002F_\u002F\\__, \u002F\\__,_\u002F        \u002F_\u002F \u002F_\u002F \u002F_\u002F\\__,_\u002F_\u002F \u002F_\u002F____\u002F \u002F_\u002F\\__,_\u002F\\__\u002F\\__,_\u002F\\__\u002F  \n                  \u002F____\u002F                                                                      \n            [ BUỒNG LÁI XỬ LÝ & DỊCH THUẬT TRUYỆN TRANH TOÀN DIỆN CHO WIBU CHUYÊN NGHIỆP ]\n```\n\n**Manga Translator Studio** là một bộ công cụ dịch thuật truyện tranh (manga\u002Fcomic) chuyên nghiệp được xây dựng trên nền tảng **PyQt6** dành cho các dịch giả và editor khó tính nhất. \n\nKhác biệt hoàn toàn so với các công cụ dịch tự động một nút bấm cẩu thả làm biến dạng art và xô lệch khung thoại, dự án này áp dụng triết lý dịch thuật **Human-in-the-loop** (con người kiểm soát quy trình) đa tầng. Công cụ này được thiết kế để đập tan mọi nỗi ác mộng của một dịch giả truyện tranh thực thụ: **nhận diện sai bong bóng thoại, OCR dịch láo thiếu chữ, văn phong AI freestyle vô tội vạ, inpaint (xóa chữ) lem nhem phá art gốc, và render chữ Việt hóa thô kệch thiếu tính nghệ thuật.**\n\n> [!WARNING]\n> **ĐÂY KHÔNG PHẢI LÀ MỘT CÔNG CỤ ĂN SẴN KHÔNG NÃO.**\n> Dự án này không tự tiện gọi API vô tội vạ hay tạo ra những sản phẩm dịch thuật mì ăn liền cẩu thả. Hệ thống hoạt động như một **Môi trường Studio (Workbench)** giúp lưu trữ cache dữ liệu thô trung gian sạch sẽ, tự động xử lý các tác vụ lặp đi lặp lại tẻ nhạt, đồng thời cung cấp giao diện trực quan cho phép bạn can thiệp, chỉnh sửa thủ công và kiểm soát chất lượng tuyệt đối ở từng giai đoạn (Stage).\n\n---\n\n## 📸 Giao Diện Thực Tế (Visual Showcase)\n\n| 🖥️ Giao Diện Điều Khiển Stage | 📝 Trình Tinh Chỉnh Dữ Liệu |\n| :---: | :---: |\n| ![Giao Diện Điều Khiển Stage](Screenshot\u002FMain_UI.png) | ![Trình Tinh Chỉnh Dữ Liệu](Screenshot\u002FEditor_UI.png) |\n\n> [!TIP]\n> *Hãy chụp những bức ảnh chụp màn hình tuyệt đẹp về giao diện ứng dụng của bạn và lưu vào thư mục `Screenshot\u002F` để làm sáng bừng file README này nhé!*\n\n---\n\n## 🧭 Các Trụ Cột Trong Buồng Lái\n\nGiao diện chính được xây dựng bằng **PyQt6** với thiết kế màu đêm tối Cyberpunk tuyệt đẹp, giảm mỏi mắt tối đa khi dịch giả cày cuốc truyện lúc 2 giờ sáng. \n\n### 1. Cây Điều Hướng Cấp Độ & Tiến Độ (Project Stage Navigator)\nCây điều hướng lề trái là xương sống giúp bạn kiểm soát dòng chảy công việc của toàn bộ dự án:\n- **📁 Quản lý Project**: Khởi tạo cấu trúc dự án chuẩn chỉ với `project.json` riêng biệt, import ảnh gốc nhanh chóng.\n- **📋 Theo dõi Tiến độ**: Hiển thị trạng thái hoàn thành trực quan của từng trang theo các mã màu neon rực rỡ: `Done` (Hoàn tất) | `Partial` (Đang xử lý) | `Not Started` (Chưa chạm vào).\n\n### 2. Các Stage Xử Lý Độc Lập (Modular Pipeline Stages)\nPipeline được chia nhỏ thành các module tách biệt hoàn toàn để bạn dễ dàng sửa lỗi và tối ưu hóa từng bước:\n- **🔍 Detection**: Quét toàn bộ trang truyện để phát hiện chính xác vùng chữ (Text Region) và bong bóng thoại (Speech Bubble).\n- **📝 OCR & Translation**: Tích hợp các công cụ nhận diện chữ gốc (PaddleOCR, Llama.cpp, Chrome Lens) và dịch thuật thông minh (Gemini, OpenAI, DeepSeek, Google, NLLB...).\n- **🎨 Masking & Inpainting**: Tạo mask che phủ tự động và ứng dụng thuật toán **LaMa Manga Inpainting** để tẩy sạch chữ gốc mà vẫn bảo toàn nét vẽ art cực kỳ mượt mà.\n- **✍️ Typesetting & Render**: Tự động dàn trang, tính toán kích thước, xuống dòng và render bản dịch tiếng Việt bằng font chữ chuyên dùng cho truyện tranh thay vì chèn text thô sơ lỗi thời.\n\n### 3. Trình Soạn Thảo Tương Tác Trực Quan (Visual Interactive Editor)\nCho phép dịch giả can thiệp sâu vào dữ liệu trung gian:\n- Loại bỏ các vùng phát hiện sai hoặc khôi phục các bong bóng thoại bị sót.\n- Chỉnh sửa trực tiếp văn bản OCR nhận diện lỗi trước khi đưa đi dịch.\n- Tinh chỉnh bản dịch thủ công để đảm bảo văn phong mượt mà, đậm chất Việt hóa.\n- Thay đổi kích thước, màu sắc, vị trí và font chữ của văn bản render trực tiếp ngay trên giao diện preview thời gian thực.\n\n---\n\n## 🔄 Luồng Làm Việc Tiêu Chuẩn (Core Pipeline Workflow)\n\nMỗi trang truyện đi qua một quy trình chế tác nghiêm ngặt gồm 10 bước khép kín để đảm bảo chất lượng thành phẩm cao nhất:\n\n```mermaid\ngraph TD\n    Start([🖼️ Ảnh Manga Nguồn]) --> Stage1[1. Detection \u003Cbr>Phát hiện Layout\u002FBong bóng]\n    Stage1 --> Stage2[2. OCR Prepare \u003Cbr>Chuẩn hóa & Crop ảnh vùng chữ]\n    Stage2 --> Stage3[3. OCR \u003Cbr>Nhận diện chữ gốc trên vùng crop]\n    Stage3 --> Stage4[4. Translation Init \u003Cbr>Khởi tạo dữ liệu dịch thuật]\n    Stage4 --> Stage5[5. Translation \u003Cbr>Dịch nghĩa qua AI\u002FTranslator]\n    Stage5 --> Stage6[6. Mask Prepare \u003Cbr>Tạo mặt nạ che phủ chữ gốc]\n    Stage6 --> Stage7[7. Inpaint \u003Cbr>Tẩy sạch chữ bằng LaMa Manga]\n    Stage7 --> Stage8[8. Render Prepare \u003Cbr>Chuẩn bị đối tượng dàn chữ]\n    Stage8 --> Stage9[9. Render \u003Cbr>Dàn font truyện tranh lên ảnh sạch]\n    Stage9 --> Stage10[10. Export \u003Cbr>Xuất bản ảnh dịch hoàn chỉnh]\n    Stage10 --> End([🏆 Tác Phẩm Việt Hóa Hoàn Mỹ])\n```\n\n### Các Mức Độ Vận Hành Linh Hoạt:\n1. **Tự động hoàn toàn (Automatic Mode)**: Chạy một chạm xuyên suốt từ bước 1 đến bước 9 cho một trang hoặc toàn bộ project. Phù hợp khi bạn đã có cấu hình API dịch thuật ưng ý và muốn xem nhanh kết quả nháp.\n2. **Bán tự động (Semi-Automatic Mode)**: Chạy từng bước và dừng lại để tinh chỉnh thủ công các dữ liệu thô trung gian (ví dụ: sửa lỗi nhận diện chữ của OCR trước khi gửi đi dịch để tránh AI dịch sai ngữ cảnh).\n3. **Thủ công hoàn toàn (Manual Workbench)**: Sử dụng ứng dụng như một bảng vẽ kỹ thuật để tự tay edit, dịch và dàn chữ trên nền tảng quản lý dự án tối ưu.\n\n---\n\n## 🧠 Cơ Chế Quản Lý Cache & Workspace Siêu Bền Bỉ\n\nĐiểm vượt trội của **Manga Translator Studio** so với các script chạy dòng lệnh thô sơ là kiến trúc lưu vết và bảo vệ dữ liệu tuyệt đối:\n\n### 1. Dữ liệu trung gian tách biệt (Stage Cache Separation)\nToàn bộ dữ liệu của từng bước xử lý trên mỗi trang được lưu trữ độc lập dưới dạng file JSON trong thư mục `cache\u002F`.\n- Nếu bước **Inpaint** bị lỗi hoặc bạn muốn đổi font render, bạn **không cần phải chạy lại bước OCR và Translation**. Hệ thống chỉ việc lôi cache cũ ra xử lý tiếp. Tiết kiệm 100% chi phí token API và thời gian chờ đợi vô lý!\n\n### 2. Định dạng lưu trữ siêu bền bỉ\nCác cấu hình và liên kết trang được ghi đè an toàn vào `project.json`. Dữ liệu tọa độ, mask, văn bản thô được phân tách rạch ròi, giúp bạn dễ dàng đóng gói, sao lưu hoặc thậm chí chỉnh sửa trực tiếp bằng tay qua text editor ngoài nếu muốn.\n\n---\n\n## 📂 Bản Đồ Thư Mục Dự Án (Project Anatomy)\n\nMã nguồn được tổ chức khoa học, phân định rõ ràng giữa giao diện hiển thị (GUI), lõi xử lý (Core) và các backend độc lập:\n\n```text\nManga-Translator\u002F\n├── mmt_gui\u002F                    # 🖥️ Giao diện desktop PyQt6 chuyên nghiệp\n│   ├── main.py                 # Entrypoint khởi động giao diện chính\n│   ├── stages\u002F                 # Các bảng điều khiển riêng cho từng stage\n│   └── workers\u002F                # Các luồng xử lý nền (QThread) chống treo GUI\n├── mmt_core\u002F                   # 🧠 Lõi điều phối pipeline và quản lý cache\n│   ├── project.py              # Xử lý I\u002FO cấu trúc project\n│   └── pipeline.py             # Bộ điều phối thứ tự chạy các stage\n├── detectors\u002F                  # 🔍 Backend phát hiện layout và bong bóng thoại\n├── ocr\u002F                        # 📝 Backend tích hợp các công cụ OCR\n├── inpainting\u002F                 # 🎨 Backend xử lý mặt nạ tẩy chữ (LaMa Manga)\n├── translator\u002F                 # 🌐 Backend dịch thuật đa nền tảng\n├── text_rendering\u002F             # ✍️ Công cụ tính toán bố cục dàn chữ & render\n├── fonts\u002F                      # 🔠 Kho font chữ truyện tranh được chọn lọc\n├── model\u002F                      # 🤖 Thư mục chứa các checkpoint model local (nếu có)\n├── tools\u002F                      # 🛠️ Các công cụ nhị phân bổ trợ (llama.cpp...)\n├── pj\u002F                         # 📁 Thư mục chứa các Project mẫu làm việc\n├── logs\u002F                       # 📝 Log runtime phục vụ debug hệ thống\n├── PyQt_run.bat                # ⚡ Script chạy nhanh ứng dụng trên Windows\n├── requirements.txt            # 📦 Danh sách thư viện Python cốt lõi\n└── README.md                   # 📖 Bản hướng dẫn sử dụng siêu ngầu này\n```\n\n---\n\n## 🛠️ Hướng Dẫn Kích Hoạt Buồng Lái\n\n### 1. Chuẩn Bị Môi Trường Cực Nhanh\nYêu cầu hệ thống cài đặt sẵn **Python 3.11** (khuyến nghị để đảm bảo tính tương thích tốt nhất của các thư viện AI). Clone repository này về máy của bạn:\n\n```bash\ngit clone \u003Curl-repository-cua-ban>\ncd my_manga_translator\n```\n\n### 2. Thiết Lập Môi Trường Ảo (Virtual Environment)\n\n#### 💻 Trên Windows (PowerShell):\n```powershell\n# Khởi tạo môi trường ảo chuyên biệt\npy -3.11 -m venv .venv\n\n# Kích hoạt môi trường ảo\n.venv\\Scripts\\Activate.ps1\n\n# Nâng cấp pip và cài đặt toàn bộ gói phụ thuộc\npython -m pip install --upgrade pip\npip install -r requirements.txt\n```\n\n#### 💻 Trên Windows (Command Prompt - CMD):\n```cmd\npy -3.11 -m venv .venv\n.venv\\Scripts\\activate.bat\npython -m pip install --upgrade pip\npip install -r requirements.txt\n```\n\n---\n\n## 🚀 Khởi Chạy Ứng Dụng\n\nSau khi quá trình cài đặt hoàn tất, bạn có thể khởi chạy buồng lái bằng một trong hai cách:\n\n1. **Nhấp đúp chuột** trực tiếp vào tệp **`PyQt_run.bat`** ở thư mục gốc của dự án.\n2. **Chạy trực tiếp từ dòng lệnh** (khi môi trường ảo đã được kích hoạt):\n\n```powershell\npython -m mmt_gui.main\n```\n\n---\n\n## ⚙️ Kho Model & Cấu Hình Khuyến Nghị (Model Zoo & Hardware Guidelines)\n\nManga Translator Studio hỗ trợ kết hợp cực kỳ linh hoạt giữa các tác vụ chạy offline (Local Deep Learning) và gọi API Cloud (Online) giúp bạn cân bằng hoàn hảo giữa chi phí, tốc độ và chất lượng dịch thuật. Dưới đây là thông số chi tiết của các model đang được tích hợp:\n\n### 1. Trình Phát Hiện Vùng Chữ (Detectors)\n*   **`PP-DoclayoutV3 + YOLOv8m (Manga Bubble version)`**:\n    *   *Đặc điểm*: Model thuộc phân khúc tầm trung, được tinh chỉnh (fine-tuned) đặc biệt cho bong bóng thoại manga.\n    *   *Đánh giá*: Vẫn còn tồn tại một vài bug nhỏ khi nhận diện bố cục phức tạp, nhưng là một lựa chọn cực kỳ đáng giá cho các cấu hình phần cứng tầm trung. Chạy bằng CPU cho tốc độ tạm ổn, không quá nặng nề.\n*   **`Manga RT-DETR`**:\n    *   *Đặc điểm*: Hàng ngon đỉnh cấp, được thiết kế chuyên biệt và tối ưu hóa ở mức cao nhất cho tác vụ phát hiện bong bóng manga.\n    *   *Đánh giá*: Tốc độ nhận diện real-time cực nhanh, độ chính xác gần như hoàn hảo. Đây là model được tác giả cực kỳ yêu thích và khuyên dùng làm mặc định.\n\n### 2. Trình Nhận Diện Chữ (OCR Engines)\n*   **`Online LLM (Claude, GPT, Gemini)`**:\n    *   *Đặc điểm*: Gửi trực tiếp ảnh crop qua API của các mô hình ngôn ngữ lớn có khả năng thị giác (Vision).\n    *   *Đánh giá*: Chất lượng nhận diện và xử lý ngữ cảnh đỉnh cao, tùy thuộc vào ngân sách của bạn. \"Giàu thì cứ Claude mà vã\", chất lượng sẽ không làm bạn thất vọng.\n*   **`Online Google Lens`**:\n    *   *Đặc điểm*: Sử dụng engine nhận diện miễn phí vô cùng mạnh mẽ của Google Lens thông qua các helper API.\n    *   *Đánh giá*: Chất lượng cực tốt, độ chính xác sánh ngang với các mô hình LLM thương mại lớn. Điểm yếu duy nhất là dễ bị giới hạn request (limit) hoặc khóa IP tạm thời nếu lạm dụng quét batch số lượng lớn trong thời gian ngắn.\n*   **`DeepSeek-OCR`**:\n    *   *Đặc điểm*: Model offline cực khủng, nặng, mạnh và cực kỳ ngon.\n    *   *Đánh giá*: Nhận diện text siêu tốt, là model offline hiếm hoi có khả năng sánh ngang với các mô hình ngôn ngữ lớn chạy online. Yêu cầu phần cứng: Cần tối thiểu **4GB VRAM** để chạy ổn định và mượt mà.\n*   **`PaddleOCR-VL`**:\n    *   *Đặc điểm*: Siêu phẩm offline gọn nhẹ nhưng sức mạnh đáng kinh ngạc.\n    *   *Đánh giá*: Tốc độ nhận diện nhanh như chớp, độ chính xác cực tốt. Đây là model tác giả yêu thích và sử dụng nhiều nhất. Điểm đặc biệt: Hiểu cực tốt văn bản xếp dọc đặc trưng của khu vực CJK (Trung - Nhật - Hàn). Cực kỳ thân thiện với phần cứng, chỉ cần **1GB VRAM** là chạy phăm phăm.\n\n### 3. Trình Dịch Thuật (Translators)\n*   Không giới hạn backend dịch thuật, hỗ trợ hoàn toàn theo khả năng tài chính và nhu cầu cá nhân.\n*   Chỉ cần tương thích với chuẩn kết nối **OpenAI API** hoặc các API phổ biến (Gemini, DeepSeek, Google, NLLB, Baidu, Bing...).\n\n### 4. Trình Xóa Chữ Nền (Inpainting)\n*   **`LaMa Inpaint (Trained for Manga)`**:\n    *   *Đặc điểm*: Phiên bản đặc chế chuyên biệt cho cấu trúc nét vẽ, screentone và các đường line art của truyện tranh.\n    *   *Đánh giá*: Đỉnh cao của nghệ thuật xóa chữ. Từ khi tích hợp model này vào hệ thống, tác giả đã quyết định dừng việc tìm kiếm các model inpaint khác. Hiệu năng xử lý quá tốt, tẩy chữ sạch sẽ không tì vết mà lại cực kỳ nhẹ nhàng, chỉ tiêu tốn vỏn vẹn **200MB VRAM**.\n\n---\n\n## 🔬 Kiến Trúc Kỹ Thuật Hệ Thống (Deep Technical Architecture)\n\nĐể giúp các nhà phát triển và người dùng kỹ thuật hiểu sâu hơn về cơ chế hoạt động của repository:\n\n### 1. Mô hình Phân Tách Vai Trò (GUI vs Core)\n*   **Giao diện (mmt_gui\u002F)**: Đóng vai trò là tầng hiển thị (Presentation Layer) điều phối trạng thái và tương tác người dùng. Giao diện được thiết kế dạng Stage-based (Panel rời cho từng bước), cho phép nạp\u002Fxuất trạng thái từ Cache Core.\n*   **Lõi Nghiệp Vụ (mmt_core\u002F)**: Đóng vai trò điều phối pipeline (Orchestrator). Toàn bộ logic nghiệp vụ, quản lý cache, đọc ghi tệp tin, chuẩn hóa dữ liệu giữa các stage đều diễn ra tại đây, độc lập hoàn toàn với giao diện đồ họa.\n*   **Các Backend (detectors\u002F, ocr\u002F, inpainting\u002F, translator\u002F, text_rendering\u002F)**: Được đóng gói thành các package độc lập, có thể tái sử dụng dễ dàng trong các dự án CLI hoặc ứng dụng khác mà không bị ràng buộc bởi PyQt6.\n\n### 2. Xử Lý Bất Đồng Bộ & Luồng Nền (Asynchronous Workers)\nCác tác vụ Deep Learning nặng (Detection, Inpaint, OCR) và gọi API dịch thuật (Translation) dễ gây nghẽn giao diện chính (Main GUI Thread). \n*   Hệ thống giải quyết triệt để bằng cách đóng gói các tác vụ này vào các **`QThread Workers`** chạy nền dưới sự quản lý của `mmt_gui\u002Fworkers\u002F`.\n*   Tương tác giữa luồng nền và giao diện được thực hiện an toàn qua hệ thống **Signals & Slots** của PyQt6, đảm bảo ứng dụng luôn mượt mà, phản hồi ngay lập tức và hiển thị thanh tiến trình trực quan.\n\n### 3. Các Thư Viện Học Máy Cốt Lõi (AI Stack)\nHệ thống sử dụng các thư viện AI hàng đầu hiện nay, tối ưu hóa chạy tốt trên cả CUDA (GPU Nvidia) lẫn CPU:\n*   `torch` & `torchvision`: Nền tảng tensor chạy các model deep learning.\n*   `ultralytics`: Sử dụng trực tiếp để suy luận các model YOLO và RT-DETR phát hiện bong bóng thoại.\n*   `transformers`: Tải và chạy các mô hình ngôn ngữ hoặc OCR offline.\n*   `llama.cpp` wrapper: Tương tác trực tiếp với llama-server để xử lý cục bộ siêu tốc.\n\n---\n\n## 📂 Cách Tổ Chức Một Project Tiêu Chuẩn\n\nKhi bạn tạo một project mới từ GUI, ứng dụng sẽ tự động sinh ra cấu trúc thư mục sạch đẹp như sau tại thư mục project của bạn:\n\n```text\nTên_Project_Của_Bạn\u002F\n├── project.json                 # Trạng thái, danh sách trang và liên kết cấu hình\n├── source\u002F                      # Thư mục chứa các ảnh manga gốc đã import\n└── cache\u002F                       # Toàn bộ \"bộ não\" dữ liệu trung gian của bạn\n   ├── detection\u002F                # Tọa độ các hộp thoại và layout phát hiện được\n   ├── ocr\u002F                      # Văn bản gốc đã nhận diện kèm tọa độ chi tiết\n   ├── ocr_crops\u002F                # Các ảnh cắt nhỏ chứa chữ phục vụ OCR\n   ├── translation\u002F              # Kết quả dịch thuật gốc và bản dịch tiếng Việt\n   ├── masks\u002F                    # File ảnh mặt nạ đen trắng phục vụ xóa chữ\n   ├── inpaint\u002F                  # Ảnh sạch sau khi đã tẩy toàn bộ chữ gốc\n   ├── render\u002F                   # Cấu hình dàn trang, font chữ và màu sắc render\n   └── render_sprites\u002F           # Ảnh sprite các khối chữ được render đè lên\n```\n\n> [!IMPORTANT]\n> **KHÔNG XÓA THƯ MƯC `cache\u002F`**\n> Thư mục `cache\u002F` là linh hồn giúp bạn tiếp tục làm việc ở lần mở app sau mà không bị mất tiến độ cũ. Nếu bạn đổi cấu hình dịch thuật hoặc chỉnh sửa chữ thủ công, hệ thống sẽ tự động cập nhật các file cache tương ứng ở các stage phía sau một cách thông minh.\n\n## 💻 Ghi Chú Cho Nhà Phát Triển (Developer Notes)\n\nNếu bạn muốn tham khảo sâu hơn hoặc tiếp tục phát triển codebase của **Manga Translator Studio**:\n*   **Trục chạy chính**: Tránh chỉnh sửa trực tiếp các script đơn lẻ ở thư mục gốc (như `add_text.py`, `detect_bubbles.py`, `process_bubble.py`). Chúng chỉ đóng vai trò làm mã tham chiếu kỹ thuật hoặc tool helper cũ. Luồng chạy thực tế của ứng dụng hoàn toàn nằm trong gói **`mmt_gui\u002F`** (giao diện điều khiển) và **`mmt_core\u002F`** (lõi xử lý và quản lý cache).\n*   **Cơ chế đa luồng (Multi-threading)**: Khi tích hợp thêm OCR hoặc Translator mới, hãy kế thừa lớp `QThread` hoặc sử dụng cơ chế Worker của `mmt_gui\u002Fworkers\u002F` để đảm bảo tác vụ nặng không gây nghẽn luồng xử lý giao diện chính (Main UI Thread).\n\n---\n\n## 🛠️ Xử Lý Sự Cố Thường Gặp (Troubleshooting)\n\nTrong quá trình vận hành buồng lái, nếu gặp sự cố kỹ thuật, bạn có thể tham khảo các bước chẩn đoán nhanh dưới đây:\n\n### 1. Ứng dụng không khởi chạy được hoặc crash ngay khi mở\n*   **Nguyên nhân**: Môi trường ảo chưa được kích hoạt đúng hoặc thiếu thư viện.\n*   **Cách khắc phục**:\n    1.  Đảm bảo bạn đang sử dụng **Python 3.11** (chạy `python --version` để kiểm tra).\n    2.  Xóa thư mục `.venv` cũ và cài đặt lại từ đầu theo đúng hướng dẫn PowerShell\u002FCMD.\n    3.  Kiểm tra logs chi tiết trong thư mục `logs\u002F` cấp workspace để tìm nguyên nhân crash.\n\n### 2. OCR Local (DeepSeek-OCR qua llama.cpp) báo lỗi hoặc không hoạt động\n*   **Nguyên nhân**: Lỗi cấu hình đường dẫn hoặc cổng mạng của server cục bộ.\n*   **Cách khắc phục**:\n    1.  Đảm bảo tệp nhị phân `llama-server` (hoặc `llama-server.exe` trên Windows) tồn tại trong thư mục `tools\u002Fllama.cpp\u002F` hoặc đã được thêm vào biến môi trường `PATH`.\n    2.  Kiểm tra file model GGUF và tệp mmproj tương ứng có khớp định dạng và đúng vị trí cấu hình trên giao diện hay không.\n    3.  Đảm bảo cổng mặc định `8080` không bị ứng dụng khác chiếm dụng (chạy `netstat -ano | findstr 8080` trên Windows để kiểm tra).\n\n### 3. Tốc độ xử lý quá chậm (Detection, Inpaint, OCR)\n*   **Nguyên nhân**: Hệ thống đang chạy bằng CPU hoặc cấu hình model quá nặng.\n*   **Cách khắc phục**:\n    1.  Kiểm tra xem PyTorch đã nhận GPU CUDA chưa bằng cách chạy lệnh: `python -c \"import torch; print(torch.cuda.is_available())\"`.\n    2.  Nếu hiển thị `False`, bạn cần cài đặt phiên bản PyTorch hỗ trợ CUDA tương thích với driver card đồ họa của bạn.\n    3.  Nếu buộc phải dùng CPU, hãy ưu tiên các model siêu nhẹ như **PaddleOCR-VL** thay vì các model offline hạng nặng.\n\n### 4. Kết quả nhận diện chữ hoặc render chữ lên ảnh chưa ưng ý\n*   **Cách khắc phục**:\n    1.  Sử dụng **Trình Soạn Thảo Tương Tác** của GUI để vẽ lại\u002Fđiều chỉnh các hộp thoại (box) bị lệch ở bước Detection trước khi chạy OCR.\n    2.  Sửa đổi thủ công các đoạn văn bản OCR bị nhận diện sai chính tả trước khi gửi đi dịch để AI có ngữ cảnh tốt nhất.\n    3.  Đảm bảo font chữ bạn muốn sử dụng đã được copy vào thư mục `fonts\u002F` và được cấu hình đúng trong phần Render.\n\n### 5. Lệch dữ liệu Cache hoặc kết quả không đồng bộ\n*   **Nguyên nhân**: Bạn đã chỉnh sửa thủ công dữ liệu ở stage trước nhưng chưa chạy lại (re-run) các stage phía sau.\n*   **Cách khắc phục**: Khi bạn thay đổi mạnh cấu hình hoặc vẽ lại box detection thủ công, hãy nhớ chạy lại các bước tiếp theo (OCR -> Translation -> Render) để cập nhật và đồng bộ tệp tin cache.\n\n---\n\n## 🧠 Triết Lý Thiết Kế\n\n> *\"Dịch thuật truyện tranh không chỉ thuần túy là dịch chữ. Đó là nghệ thuật tái tạo lại linh hồn của tác phẩm dưới một ngôn ngữ mới, tôn trọng tuyệt đối từng nét cọ, từng mảng màu và phong cách dàn trang của tác giả gốc.\"*\n\n**Manga Translator Studio** sinh ra để xóa bỏ sự thống trị của những công cụ dịch tự động cẩu thả đang tàn phá giá trị thẩm mỹ của manga. Bằng cách trao cho dịch giả quyền kiểm soát tối thượng ở từng giai đoạn xử lý, kết hợp cùng sức mạnh tự động hóa ưu việt của AI, chúng tôi tin rằng bạn sẽ tạo nên những tác phẩm Việt hóa hoàn hảo nhất, mang lại trải nghiệm đọc truyện tuyệt vời nhất cho độc giả nước nhà.\n\n---\n\nChúc bạn có những giờ phút dịch thuật thật thăng hoa bên những bộ truyện yêu thích cùng **Manga Translator Studio**! 🚀\n","Manga Translator Studio 是一个专为漫画和漫画翻译设计的专业工具集，基于 PyQt6 构建。其核心功能包括采用“人机协同”理念的多步骤翻译流程，旨在解决自动翻译工具常出现的问题，如对话框识别错误、OCR 翻译不准确、AI 生成文本风格不符等。该项目通过提供一个工作室环境帮助用户高效地管理和控制整个翻译过程中的数据缓存与重复任务，并允许在每个阶段进行手动干预以确保高质量输出。适用于对翻译质量有高要求的专业翻译人员或编辑者，在处理复杂且需要精细调整的漫画内容时尤为有用。",2,"2026-06-11 04:07:57","CREATED_QUERY"]