语言 / Language: 简体中文 | English

一键翻译漫画图片中的文字，支持日漫、韩漫、美漫，黑白漫和彩漫均可识别。自动检测、翻译、嵌字，支持日语、中文、英语等多种语言，内置可视化编辑器可调整文本框。

💬 QQ 交流群：1079089991（密码：kP9#mB2!vR5*sL1） | 🐛 提交 Issue

---

📚 文档导航

文档	说明
安装指南	详细安装步骤、系统要求、分卷下载说明
使用教程	基础操作、翻译器选择、常用设置
命令行模式	命令行使用指南、参数说明、批量处理
API 配置	API Key 申请、配置教程
功能特性	完整功能列表、可视化编辑器详解
工作流程	7 种工作流程、AI 断句、自定义模版
设置说明	翻译器配置、OCR 模型、参数详解
调试指南	调试流程、可调节参数、问题排查
开发者指南	项目结构、环境配置、构建打包

---

📸 效果展示

---

✨ 核心功能

翻译功能

• 🔍 智能文本检测 - 自动识别漫画中的文字区域
• 📝 多语言 OCR（光学字符识别） - 支持日语、中文、英语等多种语言
• 🌐 多种翻译引擎 - OpenAI、Gemini、Vertex、Sakura（含高质量模式）
• 🎯 高质量翻译 - 支持 GPT-4o、Gemini 多模态 AI 翻译
• 📚 自动提取术语 - AI 自动识别并积累专有名词，保持翻译一致性
• 🤖 AI 智能断句 - 提升文本可读性，自动优化换行
• 🎨 智能嵌字 - 自动排版译文，支持多种字体
• 📥 PSD 导出 - 导出可编辑的 PSD 文件（原图/修复图/文本分层）
• 📦 批量处理 - 一次处理整个文件夹

可视化编辑器

• ✏️ 区域编辑 - 移动、旋转、变形文本框
• 📐 文本编辑 - 手动翻译、样式调整
• 🖌️ 蒙版编辑 - 画笔工具、橡皮擦
• ⏪ 撤销/重做 - 完整操作历史
• ⌨️ 快捷键支持 - 支持 A/D 切换图片，Q/W/E 切换工具，Ctrl+Q/W/E 进行文件操作
• 🖱️ 鼠标滚轮快捷键 - Ctrl+滚轮缩放文本框，Shift+滚轮调整画笔大小

完整功能特性 → doc/FEATURES.md

---

🚀 快速开始

📥 安装方式

方式一：使用安装脚本（⭐ 推荐，支持更新）

⚠️ 无需预装 Python：脚本会自动安装 Miniconda（轻量级 Python 环境）
💡 一键更新：已安装用户运行 步骤4-更新维护.bat 即可更新到最新版本

1. 下载安装脚本：

   • 点击下载 步骤1-首次安装.bat
   • 保存到你想安装程序的目录（如 D:\manga-translator-ui\）
   • ⚠️ 这个目录将作为安装的根目录，所有程序文件都会安装在此目录下
   • ⚠️ 清理提醒：使用清理功能会清空整个根目录的文件，但会保留 Python 配置和 Git 配置相关文件

2. 运行安装：

   • 双击 步骤1-首次安装.bat
   • 脚本会自动：
     • ✓ 检测并安装 Miniconda（如需要）
       • 提供下载源选择：清华大学镜像（国内推荐）或 Anaconda 官方
       • 自动下载安装（约 50MB）
       • 安装到项目目录，不占用C盘
     • ✓ 安装便携版 Git（如需要）
     • ✓ 克隆代码仓库
     • ✓ 创建 Conda 虚拟环境（Python 3.12）
     • ✓ 检测显卡类型（NVIDIA / AMD / 集显）
     • ✓ 自动选择对应的 PyTorch 版本
       • NVIDIA: CUDA 12.x 版本（需驱动 >= 525.60.13）
       • AMD: ROCm 版本（实验性支持，仅支持 RX 7000/9000 系列，RX 5000/6000 请使用 CPU 版本）
       • 其他: CPU 版本（通用，速度较慢）
     • ✓ 安装所有依赖

3. 启动程序：

   • 双击 步骤2-启动Qt界面.bat

方式二：下载打包版本

1. 下载程序：

   • 前往 GitHub Releases
   • 选择版本：
     • CPU 版本：适用于所有电脑
     • GPU 版本 (NVIDIA)：需要支持 CUDA 12.x 的 NVIDIA 显卡
     • ⚠️ AMD GPU 不支持打包版本，请使用"方式一：安装脚本"安装

2. 解压运行：

   • 解压压缩包到任意目录
   • 双击 app.exe

方式三：Docker 部署（实验性）

💡 说明：下面的命令适合临时体验。正式部署 Web UI 时，建议按下方“Web UI 持久化”说明挂载数据目录和配置文件。

快速启动：

# Windows CMD / PowerShell
docker run -d --name manga-translator -p 8000:8000 hgmzhn/manga-translator:latest-cpu

# Linux / macOS
docker run -d --name manga-translator -p 8000:8000 hgmzhn/manga-translator:latest-cpu

镜像仓库：

本项目的 Docker 镜像同时发布在两个镜像仓库，选择下载速度更快的即可：

• Docker Hub（推荐）：

  • CPU 版本：hgmzhn/manga-translator:latest-cpu
  • GPU 版本：hgmzhn/manga-translator:latest-gpu

• GitHub Container Registry（备用，国内可能更快）：

  • CPU 版本：ghcr.io/hgmzhn/manga-translator:latest-cpu
  • GPU 版本：ghcr.io/hgmzhn/manga-translator:latest-gpu

访问地址（默认端口 8000）：

• 🌐 用户界面：http://localhost:8000
• 🔧 管理界面：http://localhost:8000/admin

Web UI 持久化（推荐）：

• 必挂目录：/app/manga_translator/server/data、/app/examples、/app/dict、/app/fonts、/app/models
• 可选目录：/app/logs、/app/result
• 可选文件：/app/.env。如果你准备在 Web 管理界面里保存服务器 API Keys，必须额外挂这个文件
• server/data 现在会统一保存 admin_config.json、user_resources/、账号、会话、用户组、权限、配额、API Key 预设、用户配置和翻译历史元数据

📖 详细安装教程：Docker 部署文档
📖 使用教程：命令行使用指南

方式四：从源码运行（开发者）

适合开发者或想要自定义的用户。

1. 安装 Python 3.12：下载
2. 克隆仓库：

   git clone https://github.com/hgmzhn/manga-translator-ui.git
   cd manga-translator-ui
   

3. 安装依赖：

   # NVIDIA GPU
   pip install -r requirements_gpu.txt
   
   # AMD GPU（仅 RX 7000/9000 系列）
   pip install -r requirements_amd.txt
   
   # CPU 版本
   pip install -r requirements_cpu.txt
   

4. 运行程序：

   # 桌面 UI
   python -m desktop_qt_ui.main
   
   # Web UI（可选）
   python -m manga_translator web
   

📖 详细安装教程：安装指南
📖 使用教程：命令行使用指南

方式五：macOS 原生运行 (Apple Silicon)

专为 M1/M2/M3/M4 Mac 优化的原生运行方式，支持 MPS (Metal Performance Shaders) GPU 加速。

快速开始（推荐）：

1. 下载安装脚本：

   curl -O https://raw.githubusercontent.com/hgmzhn/manga-translator-ui/main/macOS_1_首次安装.sh
   chmod +x macOS_1_首次安装.sh
   

2. 运行安装：

   ./macOS_1_首次安装.sh
   

   脚本会自动完成：

   • 检查并安装必要组件（Xcode 命令行工具、Git）
   • 克隆项目代码
   • 安装 Miniforge 和 Python 环境
   • 配置 MPS GPU 加速支持

3. 启动程序：

   ./macOS_2_启动Qt界面.sh
   

4. 后续更新：

   ./macOS_4_更新维护.sh
   

或者手动克隆：

git clone https://github.com/hgmzhn/manga-translator-ui.git
cd manga-translator-ui
chmod +x macOS_*.sh
./macOS_1_首次安装.sh

⚠️ 注意：

• 优先支持 Apple Silicon (M1/M2/M3/M4) 芯片
• Intel Mac 也可运行，但会使用 CPU 模式
• 首次安装需要下载约 2GB 的依赖包，请确保网络畅通

---

📖 使用教程

🖥️ Qt 界面模式

安装完成后，请查看使用教程了解如何翻译图片：

使用教程 → doc/USAGE.md

基本步骤：

1. 填写 API（如使用在线翻译器）→ API 配置教程
2. 关闭 GPU（仅 CPU 版本）
3. 设置输出目录
4. 添加图片
5. 选择翻译器
   • 首次使用推荐：高质量翻译 OpenAI 或 高质量翻译 Gemini
   • 如需单独管理 Google 官方 Key，也可使用 高质量翻译 Vertex
   • 需要配置 API Key，参考 API 配置教程
6. 开始翻译

⌨️ 命令行模式

适合批量处理和自动化脚本：

命令行指南 → doc/CLI_USAGE.md

⚠️ 重要提示：使用命令行前，请先在项目目录激活虚拟环境：

# Windows
conda activate manga-env

# Linux/macOS
conda activate manga-env

快速开始：

# Local 模式（推荐，命令行翻译）
python -m manga_translator local -i manga.jpg

# 或简写（默认 Local 模式）
python -m manga_translator -i manga.jpg

# 翻译整个文件夹
python -m manga_translator local -i ./manga_folder/ -o ./output/

# Web 服务器模式（带管理界面和 API）
python -m manga_translator web --host 127.0.0.1 --port 8000 --use-gpu

# 查看所有参数
python -m manga_translator --help

---

📋 工作流程

本程序支持多种工作流程：

1. 正常翻译流程 - 直接翻译图片
2. 导出翻译 - 翻译后导出到 TXT 文件
3. 导出原文 - 仅检测识别，导出原文用于手动翻译
4. 导入翻译并渲染 - 从 TXT/JSON 导入翻译内容重新渲染

工作流程详解 → doc/WORKFLOWS.md

---

⚙️ 常用翻译器

在线翻译器（需要 API Key）

• OpenAI - 使用 GPT 系列模型
• Gemini - 使用 Google Gemini 模型
• Vertex - 使用固定 Google 官方 Gemini host，独立读取 VERTEX_API_KEY / VERTEX_MODEL
• Sakura - 专门针对日语优化的翻译模型

高质量翻译器（推荐）

• 高质量翻译 OpenAI - 使用 GPT-4o 多模态模型
• 高质量翻译 Gemini - 使用 Gemini 多模态模型
• 高质量翻译 Vertex - 使用固定 Google 官方 Gemini host 的多模态路径
• 📸 结合图片上下文，翻译更准确

完整设置说明 → doc/SETTINGS.md

---

🔍 遇到问题？

翻译效果不理想

1. 在"基础设置"中勾选 详细日志
2. 查看 result/ 目录中的调试文件
3. 调整检测器和 OCR 参数
4. 排查完成后按文档清理旧日志（避免 result/ 目录过大）

调试流程指南 → doc/DEBUGGING.md

---

⭐ Star 趋势

---

🙏 致谢

• zyddnys/manga-image-translator - 核心翻译引擎
• bilibili/ailab - Real-CUGAN 超分辨率模型
• the-database/MangaJaNai - MangaJaNai/IllustrationJaNai 超分辨率模型
• lhj5426/YSG - 提供模型支持
• huyvux3005/manga109-segmentation-bubble - MangaLens Bubble Segmentation 气泡分割模型
• PaddleOCR - 提供 OCR 模型支持
• kha-white/manga-ocr - MangaOCR 模型支持
• PaddlePaddle/PaddleOCR-VL-1.5 - 官方 PaddleOCR-VL-1.5 模型页
• 所有贡献者和用户的支持

---

❤️ 支持作者

如果这个项目对你有帮助，欢迎请作者喝杯奶茶 🧋

---

📝 许可证

本项目基于 GPL-3.0 许可证开源。

模型协议声明

本项目代码采用 GPL-3.0 协议。

本项目支持使用 MangaJaNai/IllustrationJaNai 模型进行图像超分辨率处理。这些模型权重文件采用 CC BY-NC 4.0 协议（署名-非商业性使用 4.0 国际），仅供非商业用途使用。

• 模型来源：MangaJaNai
• 模型协议：CC BY-NC 4.0
• 使用限制：仅限非商业用途

---

⚠️ 特别声明

本项目仅提供技术演示与个人学习交流用途，不构成任何法律、商业或合规建议。
你在安装、配置、调用和分发本项目相关功能时，应自行确认并持续遵守所在地法律法规、平台规则、内容来源许可及第三方服务条款。

免责与责任限制

• 使用本项目产生的一切行为与后果（包括但不限于内容处理、发布、传播、二次分发、商业化使用），均由使用者独立承担责任。
• 你应自行确保输入内容、输出内容及数据来源具备合法授权，不得用于侵犯著作权、商标权、隐私权、肖像权等合法权益的场景。
• 严禁将本项目用于任何违法违规用途，包括但不限于盗版传播、未授权批量抓取与搬运、绕过平台限制、诈骗、诽谤、侵害他人合法权益等行为。
• 本项目依赖第三方模型、API、数据与库（含 OCR、翻译、超分模型等）；相关可用性、准确性、稳定性、费用、风控与合规要求由对应服务方负责，使用者需自行承担相应风险与成本。
• 对于因使用或无法使用本项目导致的任何直接或间接损失（包括但不限于数据损失、业务中断、收益损失、账户风险、第三方索赔等），项目作者与贡献者在适用法律允许范围内不承担责任。
• 若你将本项目用于团队或组织环境，应自行完成权限管理、日志审计、内容审核与合规评估，并建立必要的人工复核流程。

请在使用前审慎评估风险；继续使用即视为你已阅读、理解并同意上述声明。

manga-translator-ui 快速上手指南

环境准备

系统要求

• Windows：Windows 10/11（推荐）
• macOS：macOS 12+（Apple Silicon M1/M2/M3/M4 芯片最佳）
• Linux：Ubuntu 20.04+ 或其他主流发行版
• 显卡支持：
  • NVIDIA GPU（驱动 ≥ 525.60.13，支持 CUDA 12.x）
  • AMD RX 7000/9000 系列（实验性支持）
  • CPU 模式适用于所有设备（速度较慢）

前置依赖（推荐使用安装脚本自动处理）

• 无需手动安装 Python、Git 或 Conda
• 安装脚本会自动配置 Miniconda（轻量级 Python 环境）并选择国内镜像源（清华大学源）

---

安装步骤

✅ 推荐方式：使用安装脚本（自动配置国内源）

Windows / Linux

1. 下载安装脚本：

   # 或直接点击下载：https://github.com/hgmzhn/manga-translator-ui/raw/main/步骤1-首次安装.bat
   

2. 将 步骤1-首次安装.bat 保存到目标目录（如 D:\manga-translator-ui\）
3. 双击运行该脚本，自动完成：
   • 安装 Miniconda（使用清华镜像加速）
   • 安装便携版 Git
   • 克隆代码并创建虚拟环境（Python 3.12）
   • 根据显卡类型自动安装对应 PyTorch 版本
4. 安装完成后，双击 步骤2-启动Qt界面.bat 启动程序

macOS（Apple Silicon）

# 下载并运行安装脚本
curl -O https://raw.githubusercontent.com/hgmzhn/manga-translator-ui/main/macOS_1_首次安装.sh
chmod +x macOS_1_首次安装.sh
./macOS_1_首次安装.sh

# 启动程序
./macOS_2_启动Qt界面.sh

📦 备选方式：下载打包版（仅限 Windows）

1. 访问 GitHub Releases
2. 根据显卡选择：
   • CPU 版本：通用
   • GPU 版本：仅限 NVIDIA 显卡
3. 解压后直接运行 app.exe

🐳 Docker 方式（实验性）

# 使用 CPU 镜像（国内可尝试 ghcr.io 源）
docker run -d --name manga-translator -p 8000:8000 hgmzhn/manga-translator:latest-cpu

# 访问 Web UI
http://localhost:8000

---

基本使用

Qt 图形界面（推荐新手）

1. 启动 步骤2-启动Qt界面.bat
2. 配置 API Key（如使用在线翻译）：
   • 菜单栏 → 设置 → API 配置
   • 填写 OpenAI / Gemini 等密钥（获取教程）
3. 设置输出目录
4. 拖入漫画图片或文件夹
5. 在“翻译器”下拉菜单中选择：
   • 高质量翻译 OpenAI（推荐）
   • 高质量翻译 Gemini
6. 点击“开始翻译”

💡 首次使用建议勾选“详细日志”便于调试

命令行模式（适合批量处理）

# 激活虚拟环境（首次使用需先安装）
conda activate manga-env

# 单张图片翻译
python -m manga_translator -i manga.jpg

# 批量翻译文件夹
python -m manga_translator local -i ./input/ -o ./output/

# 查看所有参数
python -m manga_translator --help