manga-translator-ui 中文教程：先跑本地链路，再填 API Key
manga-translator-ui 把漫画处理拆成检测、OCR、翻译、消字修复和文字排版，并用 PyQt6 编辑器继续修正文框、蒙版、字体和贴片。它可以本地处理一部分步骤，也能接 OpenAI、Gemini、Vertex 等在线接口。是否上传页面内容，不由“开源”两个字决定，而由你选择的 OCR、翻译、上色和渲染后端决定。
v3.0.4 是最新稳定版。GitHub 显示 2026-09-06 发布，release 正文写版本日期 2026-08-29；本页同时保留两个日期。1. 五段流水线分别会错在哪里
检测决定哪些区域进入后续步骤；漏掉气泡时，翻译器根本看不到文字。OCR 可能把假名、标点或竖排读错。翻译会产生术语漂移。inpainting 可能擦掉线稿，renderer 又可能把正确译文挤出气泡。可视化编辑器的价值在于逐段修，而不是证明自动结果可以直接发布。
2. 安装时固定来源和硬件路线
Windows 可以使用官方 portable release；源码环境和 Unix 脚本会下载依赖与模型，先保存脚本再阅读。CPU、NVIDIA CUDA 和部分 Windows AMD ROCm 的依赖不同，不要在同一环境反复切换。
curl -fsSLo Unix-Install-or-Update.sh \
https://raw.githubusercontent.com/hgmzhn/manga-translator-ui/v3.0.4/Unix-Install-or-Update.sh
less Unix-Install-or-Update.sh
chmod +x Unix-Install-or-Update.sh
./Unix-Install-or-Update.sh3. 第一轮不要配置在线接口
选一页可公开使用的测试图，设置单独的 Output Directory。日漫 OCR 可从官方建议的 48px + mocr 组合开始；translator 先选 Original 或 None。这样能单独判断检测框、OCR、蒙版、消字和排版，不把 API 质量与本地问题混在一起。
CPU 包要在 Settings → General 关闭 Use GPU。先只处理一张图，保存日志、中间 JSON 和输出；没有足够显存时可用 tile 设置，但切块也可能带来边缘差异。
4. 再配置一个限额 API 通道
在线模式在 API Management 填 key、base URL 与模型。High Quality translator 会把图像上下文交给多模态模型；DeepSeek 等纯文本模型不能当作这类图像 translator。首次只配一个专用、低额度 key，确认 provider 的图片输入、数据保留与账单规则后再加故障切换。
项目 .gitignore 已忽略 .env 和 presets，因为其中可能有密钥。仍要检查备份、日志、截图和压缩包是否把这些文件带出去。
5. 九种 workflow 不要混用
Normal Translation 执行完整链路；Export Translation 和 Export Original Text 适合先导出校对；Translate JSON Only 只处理已有中间数据；Import Translation and Render 用审核后的译文回填；Colorize、Upscale、Inpaint 则各自只跑单步。v3.0.2 加入“只从本地 JSON 导出文本”，开启后不会重新 OCR 或调用翻译 API，适合保护已人工修改的工程。
6. Docker 的端口和密钥边界
官方 CPU 示例把容器的 8000 映射到主机。若 Web UI 要持久保存 API key，还要把一个主机文件绑定到 /app/.env。不要直接把 8000 暴露到公网；只绑定本机或可信网段，并在反向代理层加认证与 TLS。.env 要限制权限，不进入 Git。
touch manga-translator.env
chmod 600 manga-translator.env
docker run --rm --name manga-translator \
-p 127.0.0.1:8000:8000 \
-v "$PWD/manga-translator.env:/app/.env" \
hgmzhn/manga-translator:latest-cpulatest-cpu 会随时间变化；正式环境应改用官方当时提供的固定 tag 或 digest。上面的 loopback 绑定是收紧访问面的建议，仍需核对镜像文档。
7. 校对清单比“成功”提示更重要
每一批至少抽检：漏框、误框、人物名和地名、跨页上下文、竖排顺序、气泡断行、消字边缘、描边覆盖、贴片层级、原图未编辑区域。保留原图、工程 JSON 和使用的 prompt/config；输出 PSD 时核对文字层与字体授权。漫画本身的翻译和发布权限仍需由使用者确认。
8. 同类对比：manga-translator-ui 与 manga-image-translator
相比上游 manga-image-translator，本项目在相似的检测、OCR、翻译、修复和渲染核心上增加 PyQt6 富文本编辑、API 管理、工程文件、贴片、PSD 与多种桌面工作流；上游更偏 CLI、Web 推理核心和服务器接口。需要人工逐页精修时选 UI；要嵌入自建服务、减少桌面组件时先评估上游。
这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。
先判断这个项目是否适合你
近期变化与关注原因
v3.0.4 于 2026-09-06 发布，发布说明标注实际发布日期为 2026-08-29，增加贴片图层并修复 AVIF、EPUB、蒙版与 API 错误分类。3.0 系列还加入系统代理、更多 API 管理和编辑流程。仓库约 2.1k stars；
适合谁用
适合有合法素材、需要批量 OCR/翻译后继续精修气泡、文字和蒙版的人，也适合把 JSON/PSD 交给校对与排版流程。它不替用户解决漫画版权、翻译授权和在线模型的数据政策；只要选择在线 OCR、翻译、上色或渲染，页面内容就可能发送到相应服务。
采用建议
manga-translator-ui 可保留，项目没有严重商业漏斗；API 花费来自用户选择的外部模型。推荐先用公开页面和全本地路径验证 v3.0.4，再按功能逐个启用在线 OCR/翻译。任何批处理都应保留原图、中间 JSON、配置和少量人工抽检记录。
原教程未展开的系统信息
核心功能
完整漫画翻译流水线
按检测、OCR、翻译、inpainting 和文字渲染处理单页或整个目录，也可只运行 OCR、翻译 JSON、修复、上色或放大。
Qt 可视化编辑器
支持文本区域移动、旋转、形状与蒙版编辑、富文本、撤销重做、多选和贴片图层，自动结果可以继续人工修正。
本地与在线后端混合
OCR 和修复有本地模型，也支持 OpenAI/Gemini 等多模态 OCR、翻译、上色和渲染；在线通道需要用户自己的 API 配置。
桌面、CLI 与 Web/Docker
PyQt6 负责桌面编辑，manga_translator 模块提供 CLI 与 FastAPI server；官方文档给出 Windows 便携包、源码环境和 CPU/GPU Docker 镜像。
架构与数据流
输入图片先进入检测与 OCR，区域和文字写入中间 JSON；translator adapter 调用本地或在线翻译，inpainting 清除原文，renderer 按方向、气泡与字体规则回填。desktop_qt_ui 管理任务、配置和富文本编辑，manga_translator/server 暴露 FastAPI/WebSocket。模型、字体、prompt、API 通道和工程 JSON 分别存储，因此备份和泄露风险也不同。
常见问题
manga-translator-ui 可以完全离线使用吗？
检测、部分 OCR、消字和排版可用本地模型，但首次安装或下载模型仍可能联网。选择 OpenAI、Gemini、Vertex、在线 OCR、AI 上色或渲染后，文字或图片会发送到对应服务。
第一次应该选哪种 OCR 和翻译器？
先用公开测试页和本地 OCR，例如官方建议的 48px+mocr 日漫组合；translator 选 Original 或 None 验证检测、消字与排版。路径正常后，再为在线翻译配置限额 key。
Docker 里的 API key 怎么保存？
官方文档说明，若要让 Web UI 保存的 server API key 持久化，需要把主机上的空文件绑定到 /app/.env。该文件含敏感信息，应限制权限、备份加密并加入版本控制忽略。
翻译结果可以直接发布吗？
不建议跳过校对。应检查漏框、OCR 错字、术语、气泡内断行、消字边缘和未编辑区域，并确认你对原漫画、字体和译文拥有相应使用或发布权限。
v3.0.4 的发布日期为什么有两个？
GitHub 页面显示 release 于 2026-09-06 发布，release 正文写版本发布日期为 2026-08-29。两项都应保留，避免把说明中的版本日期误写成 GitHub 发布时间。