AI 应用计算机视觉图像处理NLP桌面应用【免费下载链接】BallonsTranslator深度学习辅助漫画翻译工具, 支持一键机翻和简单的图像/文本编辑 | Yet another computer-aided comic/manga translation tool powered by deeplearning项目地址https://gitcode.com/gh_mirrors/ba/BallonsTranslator点击查看免费下载本篇技术指南围绕 BallonsTranslator 官方文档 doc/加别的翻译器.md 展开完整讲解如何通过实现BaseTranslator子类为这个深度学习辅助漫画翻译工具添加自定义翻译器。读完本文你将掌握本地扩展与内置翻译器的文件放置规则、惰性模块发现机制、_translate契约、语言映射与参数定义方式以及一套可直接运行的验证方法并能结合仓库源码理解翻译管线的底层调用链。概述翻译器在 BallonsTranslator 中的角色BallonsTranslator 的翻译环节由ballontranslator/modules/translators/目录下的多个模块提供每个模块以trans_name.py命名通过register_translator装饰器注册到全局TRANSLATORS注册表定义见 translators/base.py。仓库内已内置 Google、DeepL、Sakura、m2m100、Sugoi、EZTrans 等翻译器实现新增翻译器时只需要遵循同一套扩展约定即可被设置界面自动发现、被翻译管线自动调用无需修改主程序其他代码。文件放置与模块发现机制添加翻译器文件后需要重启应用才能生效。文件可以放在两个位置本地扩展custom_modules/trans_name.py放在程序运行目录下属于用户自建扩展不会随仓库更新被覆盖内置模块ballontranslator/modules/translators/trans_name.py作为仓库的一部分提交。模块命名遵循MODULE_SCRIPTS中定义的trans_(.*?).py正则模式见 modules/base.py也就是说文件名中间段name会成为模块的候选标识。同理OCR、文本检测、图像修复模块分别使用ocr_、detector_、inpaint_前缀。一个关键设计是模块发现只读取静态元数据不导入具体实现。启动时由 lazy_registry.py 通过ast语法树扫描_scan_file、_collect_class_attrs、_collect_translator_langs来解析装饰器注册键、params、语言列表等元信息具体翻译器类的导入被推迟到真正被选中使用时。因此不要在__init__.py中增加提前导入。例如 translators/init.py 只有一句from .base import *一旦加入from .trans_xxx import Xxx就会破坏启动不加载模块实现的惰性设计拖慢启动速度甚至在没有安装该模块依赖时导致整个应用无法启动。自定义模块若语法扫描失败只会产生日志警告见 lazy_registry.py不会影响其他模块。最小示例一个可运行的翻译器骨架英文主指南 how_to_add_new_translator.md 中给出了完整的最小模块示例。将以下代码保存为custom_modules/trans_example.pyfrom typing import List from ballontranslator.modules.translators.base import BaseTranslator, register_translator register_translator(example_copy) class ExampleTranslator(BaseTranslator): concate_text False params {description: Copy source text without a translation service.} def _setup_translator(self) - None: self.lang_map[日本語] ja self.lang_map[English] en def _translate(self, src_list: List[str]) - List[str]: return list(src_list)这个模块不做任何翻译直接把原文复制为结果因此无需 API、无需模型、无需任何网络请求非常适合用来验证三件事注册是否成功、语言选择是否生效、结果映射是否正确。真正可运行的完整代码以英文主指南为准维护中文文档与英文主指南保持同步引用。最小示例已经体现了所有核心约定register_translator(example_copy)把类注册到注册表注册键example_copy会被写入配置文件持久化因此必须选择唯一且稳定的名称——改名字会导致旧配置失效类级concate_text False告诉基类本实现是列表感知的不要帮我合并文本详见下文合并模式params中的description会在设置界面显示为模块说明_setup_translator()中通过self.lang_map[...] ...建立界面语言名到服务语言代码的映射。扩展约定Extension Contracts继承与注册翻译器必须继承BaseTranslator定义于 translators/base.py并用register_translator注册一个唯一且稳定的名称语言名称必须使用 translators/base.py 中LANGMAP_GLOBAL的键即界面显示的中英文语言名如简体中文、日本語、English、한국어等lang_map的值填写服务实际使用的语言代码如ja、en、zh-CN运行时可以通过self.lang_map[self.lang_source]和self.lang_map[self.lang_target]读取当前源语言/目标语言对应的服务代码这两个属性由基类构造函数根据初始化参数lang_source、lang_target设置见 translators/base.py。_translate契约与concate_text子类只需要实现_translate它接收一个字符串列表src_list必须返回数量相同、顺序一致的字符串列表。这是整个翻译管线对结果对齐的硬性要求——如果数量不一致基类的translate()会直接抛出断言异常并记录错误日志见 translators/base.py。关于文本合并模式concate_text列表感知的 API 和本地模型一律使用concate_text False例如 Google 翻译器逐条请求即可见 trans_google.py、Sakura 按换行拼接但内部自行处理对齐见 trans_sakura.py、m2m100 本地模型批量推理见 trans_m2m100.py只有当服务能保留分隔符时才使用合并模式基类默认concate_text True。合并模式把整页文本用textblk_break默认\n##\n见 translators/base.py连接成一个字符串发送给服务再按同样的分隔符切回列表textlist2text/text2textlist见 translators/base.py。选用##而非普通换行是为了避免某些服务自动剥离\n导致行数错位。公共translate()方法子类不应直接覆写公共管线方法而应优先覆写_translate。基类公共方法translate()见 translators/base.py统一负责处理单个字符串输入与空输入text_is_empty检查空文本直接原样返回不触发模型加载按需加载模型all_model_loaded()检查 load_model()触发判断是否启用合并模式合并模式仅在输入为列表 concate_textTrue 全局配置翻译上下文为整页三者同时成立时启用调用_translate并保证返回数量与输入一致。另外基类的translate()接受project、page_key、commit_history_window等可选关键字以透传页面上下文第三方翻译器如果覆写此公共方法应同样接受这些关键字见 translators/base.py。参数定义与读取配置字段放在类级params字典中支持两种形态普通字符串直接写值例如api baseurl: http://127.0.0.1:8080/v1Sakura 示例选择器使用{type: selector, options: [...], value: ...}结构例如 Sakura 的版本选择器version: {type: selector, options: [0.9, 1.0, galtransl-v1], value: 0.9}见 trans_sakura.py以及 m2m100 的设备选择器device: DEVICE_SELECTOR()见 trans_m2m100.py。运行时通过get_param_value(param_key)读取参数值见 modules/base.py。只有当参数变化确实需要更新运行时状态时才覆写updateParam()且必须先调用基类实现再执行额外逻辑。典型例子是 m2m100 在设备参数变化时重建 CTranslate2 运行时对象见 trans_m2m100.py以及 Sakura 在字典路径或版本变化时重载字典见 trans_sakura.py。惰性注册约束元数据必须静态可读这是本仓库最重要的架构约束之一。设置界面在列出模块时不能依赖构造、初始化、下载、模型加载或网络调用因此params和语言赋值必须是字面量或仅使用SafeEval支持的纯函数如list(...)、dict.keys()、DEVICE_SELECTOR()、copy.deepcopy、platform.system()等完整白名单见 lazy_registry.py惰性扫描器_collect_translator_langs会解析_setup_translator中的self.lang_map[...] ...赋值和self.lang_map.update({...})调用从中推导支持的语言列表见 lazy_registry.py无法静态求值的元数据会生成metadata_warnings并在validate_lazy_module_specs中提示见 lazy_registry.py。非对称语言支持源语言集合与目标语言集合不同可以覆写返回固定字面量列表的supported_src_list/supported_tgt_list属性。基类默认两者都等于valid_lang_list见 translators/base.py而 m2m100 就是一个典型它通过属性返回一百多种语言的字面量列表见 trans_m2m100.py并在构造函数里用check_language_support装饰器校验所选语言是否在支持列表内不合法时抛出InvalidSourceOrTargetLanguage见 translators/base.py。重型模型的加载生命周期如果翻译器依赖重型模型如本地推理模型应该把模型状态放入BaseModule提供的生命周期中用_load_model_keys声明模型属性名例如 m2m100 的_load_model_keys {translator, tokenizer}见 trans_m2m100.py在_load_model()中真正加载模型load_model()会先获取全局模型加载锁再调用它unload_model()负责释放all_model_loaded()用于判断模型是否已在内存见 modules/base.py。这套机制保证模型加载可以放在工作线程中执行且兼容无界面headless模式——翻译管线只依赖模块 API不依赖 Qt 界面。依赖与文件下载可选第三方依赖放在类级dependencies列表中例如 DeepLX 的[httpx[socks,brotli]]见 trans_deeplx_api.py、Sakura 的[openai2.8.1]见 trans_sakura.py、m2m100 的[ctranslate2, sentencepiece, transformers4.57.6]需要下载的模型文件通过download_file_list声明URL、文件名、SHA256、保存目录例如 m2m100 模型文件清单见 trans_m2m100.py。共享 LLM 上下文的归属如果集成需要共享 LLM 上下文记忆、术语表、历史窗口遵循 LLM 翻译器指南 中定义的归属边界不要自行在翻译器内部重复实现一套上下文管理。深入源码翻译结果的后处理管线理解BaseTranslator不止于_translate基类还负责文本块的预处理与结果后处理。translate_textblk_lst()见 translators/base.py是整页翻译的入口流程如下_prepare_textblock_sources()收集非空文本块并对原文应用pcfg.pre_mt_sublist关键词替换preprocess_translation_text→substitute_keywords见 translators/base.py调用translate()批量翻译对每个结果执行postprocess_translation_text()按顺序应用标准化、关键词替换、大小写处理letter_case目标语言为繁体中文且模块声明cht_require_convert True时还会用 OpenCC 做简转繁见 translators/base.py。也就是说子类只需保证_translate的输入输出契约繁简转换、关键词替换、大小写等通用逻辑由基类统一处理无需在子类中重复实现。这也解释了为什么 Sakura 声明cht_require_convert True后只需在lang_map中给出简体中文映射即可获得繁体中文支持。参考真实实现三类典型翻译器1. 在线 API 型Googletrans_google.py类TransGoogle注册键为googleconcate_text False在_setup_translator中建立了从界面语言名到 Google 服务代码如zh-CN、ja、en的完整映射见 trans_google.py_translate逐条调用内部 provider 并把异常收敛为同长度的空字符串列表见 trans_google.py。2. 自建端点型DeepLX APItrans_deeplx_api.py注册键DeepLX API通过用户提供的api_url参数params中带display_name请求自建的 DeepLX 翻译服务_translate对每条文本 POST 请求并解析data字段失败时返回空串见 trans_deeplx_api.py。它展示了参数驱动端点 失败返回空串的常见写法。3. 本地模型型m2m100trans_m2m100.py注册键m2m100使用 CTranslate2 加载 1.2B 多语种模型concate_text False_translate中批量编码、批量推理、批量解码见 trans_m2m100.py。它同时展示了设备参数、模型下载清单、_load_model_keys生命周期和非对称supported_*_list的完整用法。4. 本地 LLM 型Sakuratrans_sakura.py注册键Sakura通过 OpenAI 兼容接口调用本地 Sakura 翻译模型params中同时包含复选框、选择器、文本输入等多种控件类型并在_translate中实现了术语表注入、重复文本检测、行数对齐检查与自动重试等质量保障逻辑见 trans_sakura.py是参数复杂度和运行期状态管理方面的最佳参考。验证方法英文主指南 how_to_add_new_translator.md#verification 提供了两条可以直接复制的验证命令在仓库根目录、使用应用的 Python 环境执行# 1) 语法编译检查 python -m py_compile custom_modules/trans_example.py # 2) 注册检查 语言选择 字符串/列表输入 结果映射 python -c from ballontranslator.modules import TRANSLATORS; t TRANSLATORS.get(example_copy)(日本語, English); assert t.translate([one, two]) [one, two]; assert t.translate(one) one第二条命令做了四件事从TRANSLATORS注册表取出模块类、以源语言日本語/ 目标语言English实例化、验证列表输入[one, two]得到等长同序输出、验证单字符串输入one得到one。真实翻译器还需要额外验证初始化前的元数据语言列表与params在未实例化时即可由惰性注册器静态读取确认设置界面不会因此触发构造/下载/网络调用输入形态字符串、列表、空输入空输入应被基类短路返回不触发模型加载输出对齐结果数量与输入一致、顺序一致失败路径服务错误、网络异常、模型加载失败时的行为参考内置实现普遍采用失败返回同长度空串或原文的降级策略自动化测试应模拟网络服务不要真实请求外部 API同时遵守 AGENTS.md 的验证规范见 AGENTS.md#verification与数据安全规则见 AGENTS.md#changes-and-data-safety。常见问题与注意事项改注册键会导致配置失效注册键会持久化到配置文件改名后旧配置指向的模块将无法解析因此务必从一开始就确定稳定的键名lang_map键必须来自LANGMAP_GLOBAL界面语言下拉框的数据源基于LANGMAP_GLOBAL使用其键才能保证语言选择器正常工作自定义键不会被惰性扫描器识别也无法在界面上出现不要在_setup_translator里做无法静态解析的赋值例如self.lang_map[lang] some_dynamic_value这类写法会产生惰性元数据警告导致设置界面无法预先显示支持语言不要覆写公共管线方法translate()、translate_textblk_lst()已封装空输入、模型加载、合并拆分、后处理等通用逻辑覆写它们容易破坏契约确需覆写时如需要上下文关键字应保持相同的方法签名与行为边界避免在导入期执行重活模块文件顶层只做导入与类定义任何需要构造、下载、联网的逻辑都应放到_setup_translator/_load_model/_translate中否则会拖慢应用启动并被惰性扫描器拒绝确认打开设置不会加载模型或访问服务这是仓库对设置界面的硬性要求见 AGENTS.md新增翻译器时应验证仅打开设置面板、切换翻译器、查看参数都不会触发模型加载或网络请求。小结添加翻译器的完整流程可以概括为四步选位置建文件custom_modules/trans_name.py→写最小骨架继承BaseTranslatorregister_translator_setup_translator_translate→按需扩展params参数、concate_text合并模式、_load_model_keys模型生命周期、supported_*_list非对称语言→验证语法编译 注册表断言 元数据与失败路径检查。坚持惰性元数据、静态可读这一核心约束你的翻译器就能与内置模块一样被 BallonsTranslator 的设置界面、翻译管线和配置文件无缝集成。相关英文主指南与更多实现细节可继续阅读 how_to_add_new_translator.md、LLM 翻译器指南 以及 translators 目录 下的内置实现源码。赞分享AI 应用计算机视觉图像处理NLP桌面应用【免费下载链接】BallonsTranslator深度学习辅助漫画翻译工具, 支持一键机翻和简单的图像/文本编辑 | Yet another computer-aided comic/manga translation tool powered by deeplearning项目地址https://gitcode.com/gh_mirrors/ba/BallonsTranslator点击查看免费下载相关推荐BallonsTranslator开发者指南如何添加新的翻译器模块BallonsTranslator开发者指南如何添加新的翻译器模块 BallonsTranslator是一个强大的深度学习辅助漫画翻译工具支持一键机翻和简单AI 应用计算机视觉图像处理NLP桌面应用Windows终极优化方案Atlas-OS让你的电脑性能飙升30%Windows终极优化方案Atlas OS让你的电脑性能飙升30% 你是否厌倦了Windows系统的卡顿、隐私泄露和臃肿体验Atlas OS作为一款开源透明操作系统隐私合规BallonsTranslator翻译器全解析从Google到Sakura-13B的AI翻译革命BallonsTranslator翻译器全解析从Google到Sakura 13B的AI翻译革命 BallonsTranslator是一款革命性的深度学习辅助AI 应用计算机视觉图像处理NLP桌面应用上一篇终极免费音频神器3分钟解锁macOS专业音质体验 下一篇FanControl终极指南5分钟让Windows风扇控制变得简单高效创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考