📝 笔记摘要：漫画翻译工具本地部署

日漫看不懂又不想等汉化组，有个现成办法：让机器自己跑一遍「检测文字 → 识字 → 翻译 → 抹掉原文 → 补回画面 → 填字」这套流水线。这篇记两个能本地跑的工具——manga-image-translator 和 BallonTranslator——怎么把依赖装上、怎么把本地的 sakura 模型接进去、踩过的坑在哪。

原笔记是两个项目各记一小段，只写了步骤没写原因，而且用的是早期版本的做法。这里按现在官方文档校正过两处：manga-image-translator 已经内置 sakura 翻译器，不用再全项目搜源码手改；BallonTranslator 的 官方 GitHub 仓库已经 404，得从镜像站拉。

这篇有前置　翻译模型得先在本机跑起来
　　Python 装好、项目挂上 .venv、pip install -r requirements.txt 这一套，以及 sakura 模型从哪下、LM Studio 和 Ollama 怎么配、端口是 1234 还是 11434，全在 　　《Windows 本地开发环境搭建：Python、虚拟环境与本地大模型》里
　　那篇没配好的话，这篇第 3.3 节和 4.2 节填的地址都会连不上
　　这篇只讲两个翻译工具自己的依赖和接法

1. 这套东西在机器上怎么跑

翻译是逐行气泡独立发请求的
　　模型看不到上下文，一行就是一行，上下文对不上是常态
　　专用的日译中模型就是照这个场景训的，比通用大模型准得多
检测漏了，后面全白搭
　　低分辨率图里的小字最容易漏检，先放大再检能捞回不少
修复不干净会露原文
　　译文和原文能对上，说明是修复没抹干净，不是识别错
　　要往修复那一环调，不是往 OCR 那一环调

2. 两个工具怎么选

BallonTranslator　纯图形界面，拖图进去出结果，不用记参数
　　新手想快速看懂日漫，从它开始
manga-image-translator　命令行 + Web 服务 + Docker 三种形态
　　要批量翻整本、或者要单独调检测和修复的细项，用它
两边的共同前提
　　都要先把虚拟环境建好、依赖装齐
　　都要先把 sakura 模型跑起来，端口填对，怎么跑见 　　《Windows 本地开发环境搭建》
　　非 N 卡机器都得按 CPU 装依赖

3. manga-image-translator

地址 github.com/zyddnys/manga-image-translator，支持二十多种语言，主要针对日漫，也做图片修复和重新排版。

git clone https://github.com/zyddnys/manga-image-translator.git
cd manga-image-translator

# 建虚拟环境
python -m venv .venv

# 激活
.venv\Scripts\activate

# 装依赖，必须在项目根目录执行
pip install -r requirements.txt

Python 版本要 3.12 或更高
　　官方 README 现在明确写了这条，太老的版本装不上
Windows 上先装编译工具
　　有几个依赖需要现场编译，没装会直接报 C 编译错误
　　去 visualstudio.microsoft.com/vs 装 Microsoft C++ Build Tools
　　装「使用 C++ 的桌面开发」这一项就够了，不用装完整 Visual Studio
pip 卡在编译不动
　　先确认 Build Tools 装好，再 pip install -r requirements.txt
　　实在不行先换源再试

3.1 非 N 卡怎么装依赖

原笔记里踩的是这个：requirements.txt 里默认锁的是 paddlepaddle-gpu，那是 N 卡专用的，A 卡和核显根本下不下来对应的包。

症状
　　pip install -r requirements.txt 卡在 paddlepaddle-gpu，或者报找不到匹配的发行版
改法
　　把 paddlepaddle-gpu==x.x.x 换成不带 -gpu 的 paddlepaddle==x.x.x
　　就是走 CPU 推理，慢但能跑
版本号要对着自己的 Python 选
　　不是随便找个版本号，老版本可能已经撤下了
　　去 paddlepaddle.org.cn/install/quick 按自己的 Python 版本选
　　或者本地有 whl 包就直接 pip install 那个 whl 文件，绕开下载
装完确认装的是哪个
python -c "import paddle; print(paddle.__version__)"
python -c "import paddle; print(paddle.device.get_device())"　应该打印 cpu

3.2 启动

cd server

# 有 N 卡
python main.py --verbose --use-gpu --port 5003

# 没 N 卡
python main.py --verbose --port 5003

没有 GPU 就去掉 --use-gpu
　　这个参数会在 mps 和 cuda 之间自动切换，没 N 卡时带着它会直接失败
三种模式端口不一样
　　web 模式默认 8000，api 模式 8001，websocket 模式 5003
　　命令行里写了 --port 就以你写的为准
旧文档里的启动方式会失效
　　早期版本用 python main.py --use-gpu 直接跑，现在要先 cd server
web 模式要自己开实例
python main.py --verbose --start-instance --port 8000
批量翻译不启服务
python -m manga_translator local -v -i 图片目录
　　结果输出到同级的 xxx-translated 目录

3.3 接本地 sakura

现在的版本不用改源码。sakura 已经写在配置枚举里了，要在项目根目录建一个 .env 把接口地址填进去：

SAKURA_API_BASE=http://127.0.0.1:1234/v1
SAKURA_VERSION=0.9

这里填的 1234 是 LM Studio 的端口
　　用 Ollama 就改成 11434，模型怎么跑起来的见 　　《Windows 本地开发环境搭建》
　　端口填错这里就直接翻译失败，不是翻译出错，是压根不通

原文那个「全局搜索 validTranslators」是旧做法
　　早期版本 sakura 不在白名单里，得在 server/index.html 里全局搜 validTranslators 变量，照着已有翻译器加一行
　　现在配置文件的 Translator 枚举里已经有 sakura，改 .env 就行
　　机制一样，都是在已有翻译器写法旁边加一行，跟着截图能看明白原理：

改源码的另一个坑
　　项目一更新源码就冲掉了，git pull 之后要重新改
　　改 .env 不会被覆盖
版本号填 0.9 还是 0.10
　　要和你本地跑的模型版本对上，填错请求会被拒
密钥别写进 .env 后就忘了
　　这个文件里所有 API key 都是明文，.gitignore 里确认有它
　　用云端翻译器时尤其注意，别把 key 提交上去

3.4 改了之后拉不下来

如果改的正好是项目自带的配置文件，git pull 就会撞车：

别硬合并
　　这种配置文件本地和远程各改一处，手工挑一行就行
　　带密钥的文件冲突时更要用对比工具，别整块接受某一边
更省事的做法
　　配置全放 .env，这个文件项目默认不管，冲突就不会发生

4. BallonTranslator

纯 Windows 桌面程序，图形界面，拖图进去就能翻。

官方 GitHub 仓库已经打不开了
　　GaiZhenbiao/BallonTranslator 现在返回 404，只剩一个空壳 fork
　　搜到的其他同名仓库都不是原作者的，别乱装
　　镜像站上还能拉到完整的代码，Gitee 上有稳定的一份
装依赖的步骤和 manga-image-translator 一模一样
python -m venv .venv　→　.venv\Scripts\activate　→　pip install -r requirements.txt
　　《Windows 本地开发环境搭建》里已经讲透了，这里不重复

4.1 装 PaddleOCR

这个工具的 OCR 默认走 PaddleOCR，依赖清单里不一定带全，要单独补：

pip install paddleocr

报这个错就是 OCR 没装上
PaddleOCR is not installed, so the module will not be initialized.
　　按提示装核心库，再 pip install paddleocr
照抄日志里的 module 名称
　　启动日志会打印每个模块实际用的哪个模型：检测器、OCR、修复、上色、翻译器各一行
　　以后出问题先看这五行，比翻文档快
日志刷屏不用管
　　看到 TorchDynamo attempted to trace 和 compilation metrics 是在编译模型
　　第一次启动慢是因为这个，属于正常现象，第二次就快了

4.2 配 Sakura 翻译器

接口地址要和模型实际端口对上
　　用 LM Studio 就填 http://127.0.0.1:1234/v1，用 Ollama 填 http://127.0.0.1:11434/v1
　　图里这个 8080 是本地独立推理服务的默认端口，换成上面两个工具就要改
源语言要选日文
　　两个都选中文的话，等于让模型把中文翻成中文，出来的还是日文
version 填 0.9
　　和模型版本对上，请求才会被接受
low vram mode 显存不够就勾上
　　牺牲一点速度换能跑起来
这几个参数调大调小的作用
retry attempts　　单条文本重试几次，网络抖或者模型抽风时有用
timeout　　单次请求超时秒数，短文本很快，别设太小
max tokens　　单次最多出多少 token，气泡文本短，够用就行
repeat detect threshold　　相邻重复文本的合并阈值，字太小容易触发误合并

4.3 术语表

它认一个词典文件
　　把专有名词、角色名、人称代词的固定译法写进去，每次翻译都会套用
　　角色名不统一是漫画翻译最影响观感的问题，靠这个解决
文件名对不上会不生效
　　manga-image-translator 默认读项目里的 dict/sakura_dict.txt
　　文件名或者位置不对就静默不生效，不报错
规则和词典的区别
　　词典管「固定译名」，规则管「翻译前后的文本替换」
　　两者能配合用，规则还能用正则跳过不想翻的内容

💡 补充几个原文没写的：

翻译效果先看瓶颈在哪一环
　　原文没识别对，是 OCR 的问题，调翻译器没用
　　译文不通顺，才轮到换模型或者加词典
　　带 --verbose 跑一遍，中间结果都会存下来，能逐环节看
批量跑之前先拿单张试
　　参数调好之后，用 local -i 单张图片 验一遍再上整本
　　整本几十页跑一半发现参数不对，浪费的是时间
CPU 跑要留足时间
　　没有 N 卡时，检测和修复这两步是最慢的
　　整本漫画用 CPU 翻译，几个小时起步是正常的
云端翻译器是条退路
　　两边都支持接 DeepSeek、Groq 这类 API
　　本地机器带不动的时候，.env 里填上 key 就能换
　　注意 key 是明文存的，别提交进 Git
模型放本地才有隐私
　　整本漫画全发给云端 API，等于把内容传出去了
　　对内容敏感的图，用本地模型跑
虚拟环境别提交
　　两个项目都把 .venv/ 和 .env 加进 .gitignore
　　前者是机器相关的，后者有密钥，两个都不能进仓库

🔥 一句话总结：两个工具跑的是同一条「检测 → OCR → 翻译 → 修复 → 上色 → 渲染」流水线，环境准备完全一样——建 .venv、激活、pip install -r requirements.txt，非 N 卡把 paddlepaddle-gpu 换成 paddlepaddle；接模型这步 manga-image-translator 在根目录写 .env 的 SAKURA_API_BASE，BallonTranslator 在界面上填 api baseurl，两边都要把端口从默认的 8080 改成 LM Studio 的 1234 或 Ollama 的 11434，并确认源语言选的是日文。