Manga Translator UI调试教程debug文件夹结构与日志阅读方法【免费下载链接】manga-translator-ui基于manga-image-translator 实现的开源漫画AI翻译桌面工具。支持日、韩、英文漫画自动处理集成OpenAl、Gemini等多翻译引擎实现OCR文字检测、原文擦除、AI翻译、图像修复、译文排版完整链路自带可视化编辑器支持自定义文本样式一键部署开箱即用。项目地址: https://gitcode.com/gh_mirrors/man/manga-translator-uiManga Translator UI 是一款基于 manga-image-translator 的开源漫画 AI 翻译桌面工具集成 OCR 文字检测、原文擦除、AI 翻译、图像修复与译文排版的完整链路并自带可视化编辑器。当翻译效果不理想或程序报错时靠猜很难定位问题——本文教你3 分钟读懂 result/ 目录下的 debug 文件夹结构与运行日志快速找到出错的环节并调整参数。核心关键词Manga Translator UI、漫画AI翻译、调试debug、详细日志、日志阅读 长尾关键词如何开启详细日志、debug 子文件夹命名规则、result 目录结构、翻译报错排查流程一、一键开启详细日志排查问题的第一步是开启详细日志只需 3 步打开左侧设置 → 通用打开详细日志开关见下图第一项重新运行一次翻译任务。开启后每次运行会生成两类调试产物result/log_时间戳.txt—— Qt UI 运行日志检测/OCR/渲染的完整时间线result/时间戳-图片名-目标语言-翻译器/—— 每张输入图一个debug 子文件夹保存各阶段的中间图片。命令行模式同样支持加-v/--verbose参数即可。详细说明见 doc/DEBUGGING.md。 建议仅在排查问题时开启日常使用关闭可减少日志噪音和磁盘占用。二、看懂 result/ 目录结构与文件夹命名规则调试产物统一写在项目根目录打包版为可执行文件同级目录的result/下结构如下result/ ├─ log_20260807120000.txt # 运行日志yyyyMMddHHmmss 时间戳 └─ 1785860417472-3415b69c-2048-CHS-openai/ # 每张图一个 debug 子文件夹 ├─ input.png # 处理前的原图 ├─ bboxes.png # 最终文本框可视化 ├─ mask_final.png # 擦除用最终蒙版 ├─ inpainted.png # 擦除文字后的图 ├─ final.png # 最终翻译结果 └─ ocrs/ # 每个文本框的 OCR 输入裁剪图 ├─ 0.png └─ 1.png子文件夹名的 5 段式命名debug 子文件夹的命名规则为{毫秒时间戳}-{图片MD5前8位}-{检测大小}-{目标语言}-{translator}生成逻辑见 manga_translator/manga_translator.py字段示例含义毫秒时间戳1785860417472保证目录名唯一用于定位哪一次运行图片 MD5 前 8 位3415b69c相同内容的图片哈希相同用于定位哪张图检测大小2048当次运行的 detector 检测尺寸目标语言CHS如 CHS、EN 等语言代码翻译器openai使用的翻译引擎标识✅ 记住时间戳定位哪一次MD5 定位哪张图。批量任务中每张图都有自己的子文件夹对照日志中的图片路径即可一一匹配。三、debug 子文件夹里的核心文件按阶段按流水线顺序各阶段文件含义一目了然阶段文件看什么输入input.png处理前的原图确认输入正确检测detection_raw_boxes.png、bboxes_unfiltered.png原始/筛选后文本框判断漏检还是误检检测mask_raw.png检测置信度热力图带颜色条OCRocrs/0.png…每个文本框的透视校正裁剪图垂直文字已旋转为水平OCRbboxes.png成功识别出文字的最终文本框含阅读顺序编号擦除修复mask_final.png、inpaint_input.png最终擦除蒙版与修复模型输入擦除修复inpainted.png文字擦除、背景修复后的结果渲染final.png渲染译文后的最终图片⚠️ 两个易踩的坑缺少文件 ≠ 出错无文本页会提前结束日志中出现skip-no-regions/skip-no-text此时bboxes.png等文件本就不会生成balloon_fill_boxes.png、hybrid_detection_boxes.png等也只在特定设置下出现。final.png是调试副本真正保存的输出图片由输出设置/保存到源目录决定两者内容应一致不一致说明是保存环节的问题。各文件的触发条件与条件性产物完整清单可查阅 doc/wiki/en/debugging/folder-naming-and-overview.md 与 doc/DEBUGGING.md。四、日志阅读方法4 步排查流程推荐的阅读顺序是先读日志定位阶段 → 再按流水线顺序看 debug 文件 → 最后比对输出。第 1 步先读 log 文件定位出错阶段运行日志始终写入result/log_*.txt且文件内固定为 DEBUG 级别即使没开详细日志也存在配置逻辑见 desktop_qt_ui/main.py。打开后重点找ERROR/WARNING行直接指向异常与堆栈每张图片的处理时间线确认流程走到了哪一步停下skip-no-regions/skip-no-text说明是没检测到文字而非崩溃。如果翻译失败弹出翻译错误对话框直接点打开日志文件夹按钮即可跳转到result/目录。第 2 步打开对应图片的 debug 子文件夹按顺序看图顺序固定为input.png → 检测产物mask_raw/bboxes 系列→ ocrs/ → mask_final/inpaint_input → inpainted.png → final.png在哪一步和预期不符问题就出在那一步。第 3 步比对最终输出把final.png与任务实际保存的结果图对比再进入可视化编辑器人工复核译文、蒙版与文本框位置。第 4 步调参数重跑验证症状优先检查调整方向检测不到文本bboxes_unfiltered.png降低文本置信度/框生成置信度或增大检测大小误检非文本区域bboxes_unfiltered.png提高上述两个置信度OCR 识别错误/漏字ocrs/裁剪图 bboxes.png降低 OCR 置信度或调大 Unclip 比例擦除不干净mask_final.png、inpainted.png增大遮罩扩张偏移或换 lama_large 修复模型参数调节位置与完整排查示例见 doc/DEBUGGING.md。五、排查完成后清理与分享注意事项先完全关闭程序否则 Windows 下日志文件被占用删除会失败手动删除result/下不再需要的log_*.txt和以时间戳开头的调试目录保留仍需回溯的问题样本分享前务必脱敏debug 文件夹里可能包含整页原图、识别出的原文/译文、本地绝对路径甚至 API Key——不要整个打包上传只分享最小复现集版本号 复现步骤 脱敏后的日志片段与调试文件夹。清理命令与脱敏清单参考 doc/DEBUGGING.md。小结详细日志开关在设置 → 通用命令行用-v/--verboseresult/下 运行日志 每图一个 5 段式命名的 debug 子文件夹排查口诀先日志定阶段再按 检测→OCR→擦除→渲染 顺序看图最后比对输出排查完记得清理result/分享前做好脱敏。掌握这套方法后绝大多数翻译效果不对的问题都能在第 2~3 轮重跑内定位到具体环节。【免费下载链接】manga-translator-ui基于manga-image-translator 实现的开源漫画AI翻译桌面工具。支持日、韩、英文漫画自动处理集成OpenAl、Gemini等多翻译引擎实现OCR文字检测、原文擦除、AI翻译、图像修复、译文排版完整链路自带可视化编辑器支持自定义文本样式一键部署开箱即用。项目地址: https://gitcode.com/gh_mirrors/man/manga-translator-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考