LunaTranslator 功能全景指南HOOK 文本提取、内嵌翻译、OCR 与大模型翻译一站式解读【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslatorLunaTranslator 是一款面向视觉小说Galgame的翻译工具其官方文档首页 docs/vi/index.md 以功能卡片的形式概括了软件的八大核心能力HOOK 文本提取、内嵌翻译、HOOK 模拟器、OCR、丰富翻译接口、语言学习、语音合成与语音识别。本文以这份功能矩阵为主线逐项展开对应子文档的实操细节并引入仓库源码佐证实现原理帮助读者从知道有什么功能进阶到知道怎么配置、为什么这样配置。一、功能矩阵文档首页在讲什么与常见的 VitePress 文档一样docs/vi/index.md 是文档站首页采用layout: home布局通过 hero 区的三个动作按钮软件下载与常见问题、基本用法、Github和八个 feature 卡片快速导航全站。八个功能卡片构成了 LunaTranslator 的能力全景功能一句话定位对应子文档HOOK以 HOOK 方式提取游戏文本兼容绝大多数常见与冷门视觉小说hooksettings.md内嵌翻译部分游戏可直接将译文嵌入游戏内获得沉浸式体验embedtranslate.mdHOOK 模拟器对 NS/PSP/PSV/PS2 上的大部分游戏直接读取游戏文本emugames.mdOCR内置高精度 OCR 模型并支持大量在线/离线 OCR 引擎useapis/ocrapi.md丰富翻译接口支持几乎所有翻译引擎含大语言模型翻译与离线翻译guochandamoxing.md语言学习日语分词与假名注音支持 AnkiConnect 与 Yomitan 插件qa1.md、yomitan.md语音合成支持大量在线与离线 TTS 引擎ttsengines.md语音识别在 Windows 10 / 11 上使用 Windows 语音识别sr.md在仓库层面这些能力可以一一对应到src/LunaTranslator下的源码模块textio/textsource/texthook.pyHOOK 文本源、ocrengines/OCR 引擎目录、translator/翻译引擎目录、cishu/词典目录、tts/语音合成目录可见首页功能矩阵并非宣传文案而是对代码结构的直接映射。二、下载、启动与更新把软件跑起来功能再丰富第一步也是正确下载与启动。docs/vi/README.md 明确了系统支持范围与启动注意事项。2.1 系统支持与下载主推版本Windows 11 与 Windows 101803的 64 位版本提供一键下载按钮。旧系统兼容版Windows 732/64 位、Windows XP 与 Vista32 位也有对应构建。但文档明确警告这些旧版本性能较差、运行不稳定、缺失部分功能、容易被杀毒软件误报除非有特殊需求否则不推荐使用。2.2 启动方式与目录要求解压后有三个启动入口可执行文件说明LunaTranslator.exe普通模式启动LunaTranslator_admin.exe以管理员权限启动HOOK 部分游戏必需仅必要时使用LunaTranslator_debug.bat附带命令行窗口便于查看日志一个非常关键的目录约束不要将软件放在C:\Program Files等特殊路径否则即使有管理员权限也可能无法保存配置与缓存文件甚至无法运行程序。这背后的原因是配置文件写入权限与 UAC 虚拟化值得所有用户在第一时间规避。2.3 更新机制软件默认自动更新自动更新失败时可手动更新——直接下载新版本解压覆盖旧目录即可。特别强调卸载重装时不要删除userconfig目录否则将丢失所有既有设置。从仓库结构看用户配置与软件本体分离的设计gobject.thisuserconfig指向独立用户配置目录见 mecab.py 中对用户配置目录的引用正是为了支持这种覆盖更新保留配置的工作流。2.4 常见启动错误排查README 整理了四类高频错误其根因大多指向杀毒软件误报缺少重要组件 / Missing embedded Python3杀软拦截了内置 Python 运行时。解决方法是关闭杀软或将软件目录加入白名单后重新下载解压。等待注入 DLL 到游戏中…与上一项同因。HOOK 机制需要向游戏进程注入LunaSubprocess32.exe/LunaHost32.dll等文件这种注入行为极易被启发式引擎判为病毒。文档给出的判断依据是软件由 GitHub Actions 自动构建除非构建服务器被感染否则不可能携带病毒可放心加白。Error / FileNotFoundError运行一段时间后出现通常意味着关键组件已被杀软静默删除处理方式同上。Error / PermissionError通常是因为软件被放置在C:\Program Files等受保护目录。在源码侧DLL 注入与文本提取的实现位于 NativeImpl/LunaHost 与 NativeImpl/LunaHook 两个原生模块中其中LunaHostDll.cpp、injector.cpp承担进程注入职责这正是杀软关注点的来源。三、基本用法三种文本获取方式docs/vi/basicuse.md 给出了上手软件最核心的三条路径分别对应视觉小说的三种典型文本来源。3.1 HOOK 模式首选对已经启动的游戏切换至 HOOK 模式 → 打开进程选择窗口 → 选中游戏进程。确认后游戏会加入软件列表并被注入随后弹出文本选择窗口。此时让游戏继续运行一段时间产生文本文本选择窗口中会列出候选文本行选中与游戏画面一致的那一行即可开始翻译。若该游戏支持内嵌翻译文本行所在列会同时出现嵌入按钮否则只有显示按钮。HOOK 模式的文本流式更新与候选行过滤对应源码 textio/textsource/texthook.py 与 HOOK 原生端的文本线程实现。3.2 OCR 模式兜底部分游戏无法 HOOK 时可切换至 OCR 模式框选识别区域软件将自动循环识别画面文本并翻译。文档特别提醒不要误用按钮——工具栏中外观相似的另一按钮只做一次性截图识别不会持续跟踪画面。3.3 拖拽启动与自动 HOOK更快捷的路径将游戏程序直接拖入软件窗口软件会自动完成添加游戏 → 以转区方式启动 → 自动 HOOK三步随后弹出文本选择窗口后续操作与 HOOK 模式一致。这对需要加载区域语言Locale Emulator / NTLEA 式转区才能运行的日文游戏尤为方便。四、HOOK 设置详解从提取到输出的调优HOOK 是 LunaTranslator 的主战场hooksettings.md 将配置分为通用设置与游戏专属设置两层这一分层与配置系统中默认配置 覆盖配置的设计一一对应。4.1 通用设置5 个核心参数代码页Code Page仅当引擎提取出的是编码未知的多字节字符串时该设置才生效若引擎已确定代码页或文本为 UTF-16/UTF-32 字符串则该设置无效。通常无需改动——只有 Yuris 等老引擎的中文官方版可能使用 GBK/BIG5/UTF8 时需要关注。找不到正确文本时更有效的做法是直接提交 issue 反馈而非盲目修改代码页。刷新延迟Refresh Delay针对三类症状对症下药——文本逐字/逐二字蹦出或文本按行刷新、旧行被顶掉只剩最后一行 →增加刷新延迟或提高游戏文本显示速度文本正确但提取很慢 →适当降低刷新延迟同时小心不要诱发前两类问题。最大缓冲长度Maximum Buffer Length当文本持续刷新不停顿、刷新延迟又降不下来时缓冲区会持续接收直到写满。可适当减小缓冲长度来加快落定但不能短于实际文本长度。最大缓存文本长度Maximum Cached Text Length历史文本会被缓存用于文本选择窗口的查看。文本项过多或持续刷新会导致缓存膨胀、查看变慢。默认值为 1000000文档明确建议可以大胆调小到 1000——真正有价值的历史文本可以在历史文本窗口中查看。最大允许输出文本长度跳过剧情或回看历史文本时可能一次性涌出大量文本但用户未必关心。将此值调到合适范围即可滤除这类突发输出。4.2 游戏专属设置补充 HookWin32 全局 Hook开启后向游戏注入 GDI、D3DX 及字符串相关函数的全局 Win32 Hook。由于注入过多 Hook 会拖慢游戏这些 Hook 默认不注入仅当无法正确提取文本时才建议尝试开启。特殊码Special Codes当某条特殊码被插入且其文本被选中时该特殊码会被自动记录下次启动游戏时自动应用。设置页会列出所有已记录的特殊码可自由增删。这解决了每次进游戏都要手动插入特殊码的重复劳动。延迟注入Delayed Injection部分游戏的 Hook 点位于运行一段时间后才加载的 DLL 上此时需要等待 DLL 加载完成再执行注入。游戏专属设置覆盖在设置 → HOOK 设置中修改的是全局默认值若需要为单个游戏定制进入游戏管理 → 游戏设置在设置选项卡中切换到 HOOK 页取消勾选使用默认设置即可独立配置。五、内嵌翻译把译文写进游戏画面docs/vi/embedtranslate.md 描述了沉浸式翻译方案的完整使用与排障流程。5.1 使用前提与操作首先要接受两个前提并非所有游戏都支持内嵌内嵌可能造成游戏卡死。文本选择窗口中若文本行没有嵌入按钮即表示不支持。操作流程在文本选择窗口选中支持内嵌的文本项并激活。注意显示与嵌入是两个独立开关两者都开游戏内嵌译文软件窗口显示更完整的译文只开嵌入仅在游戏内显示译文软件窗口不再显示内容。5.2 乱码排查字符集与字体开始内嵌翻译后最常见的故障是译文显示乱码文档给出的排查顺序是先查字体英文游戏内嵌中文译文时多为缺少中文字体所致。此时需开启编辑游戏字体并选择一款能显示中文的字体。再查字符集许多经典日式 Galgame 使用内置 Shift-JIS 字符集处理中文可尝试开启简体转繁体/日文汉字来减少显示错误而较新引擎KiriKiri、Renpy、TyranoScript、RPGMakerMV 等多使用 UTF-8/UTF-16乱码基本是字体问题而非字符集问题关闭该转换选项后简体中文即可正确显示个别无法正确显示简体的游戏则反向尝试开启该选项。5.3 内嵌设置项设置作用显示模式受游戏可显示行数限制默认不在译文与原文之间加换行确认行数够用后可在翻译优化 → 译文处理中通过正则给译文前添加换行翻译等待时间内嵌原理是在游戏显示文本前暂停游戏、发翻译请求、等待译文、改写内存后继续显示因此慢速翻译必然造成游戏卡顿通过限制等待时间可避免长时间卡顿转繁体/日文见 5.2每行字符数限制部分游戏单行有长度上限超长内容会溢出文本框右侧不可见可设置自动断行规避编辑游戏字体 / 相对字号调整解决字体缺失与字号不匹配删除游戏内显示文本开启后游戏原文本会被清空适用三种场景① 内嵌乱码无法解决时将软件窗口覆盖在原文位置伪装内嵌效果② 使用外部翻译工具时避免译文窗口与原文重叠③ 纯日语学习场景移除原文干扰配合假名注音与双语显示暂停游戏 → 改写内存 → 恢复显示这一机制说明内嵌翻译在实现上依赖内存改写而非截图叠加这也解释了为何它对引擎兼容性要求极高。六、HOOK 模拟器覆盖 NS/PSP/PSV/PS2 主机游戏docs/vi/emugames.md 通过 include 机制引入 docs/emusupportlist/all.md给出当前模拟器支持矩阵平台支持的模拟器含版本要求NSyuzu(≥1616)已停用、Eden (MSVC)、Citron (MSVC)PSPPPSSPP ≥ v1.15.0PSVVita3K ≥ v0.1.9.3339PS2PCSX2 ≥ v1.7.4473PS3RPCS3这一能力在仓库 NativeImpl/LunaHook/LunaHook/emulators 目录中落地——该目录集中存放各主机模拟器的文本读取适配代码。对不在支持列表中的游戏文档引导用户提交 issue 请求适配。七、OCR 引擎体系内置模型与多引擎生态docs/vi/useapis/ocrapi.md 将 OCR 引擎划分为在线与离线两大阵营而 ocrsetting.json 则给出了默认配置的源码级证据。7.1 在线 OCR内置平台包括百度智能云 OCR含图片翻译、百度翻译开放平台图片翻译、腾讯通用印刷体识别与图片翻译、有道、火山引擎、讯飞、Google Cloud Vision、Ocr.space以及通用大模型接口与大语言模型翻译共用同一套接口配置见下文第八章。7.2 内置 OCR离线软件随包内置PP-OCRv5_mobile轻量模型支持简中、繁中、英文、日文识别无需任何配置开箱即用。设置页还提供多档模型可选文档给出了官方评测数据检测 Hmean / 识别平均准确率 / 语言支持 / 体积模型检测 Hmean(%)识别准确率(%)支持语言体积(MB)PP-OCRv6_small84.181.3任意25.2PP-OCRv6_medium86.283.2任意99.7PP-OCRv6_tiny80.673.5任意5.45PP-OCRv5_mobile79.081.29简中/繁中/英/日17.7PP-OCRv5_server83.886.38简中/繁中/英/日148eslav_PP-OCRv5_mobile79.081.6东斯拉夫语系11.2korean_PP-OCRv5_mobile79.088.0韩语12.2latin_PP-OCRv5_mobile79.084.7拉丁字母语系11.3从源码看默认配置确实指向内置模型defaultconfig/ocrsetting.json中local引擎的默认参数为model: PP-OCRv5_mobile、thread: 4、device_type: CPU、gpu: falseocrsetting.json。高精度模型如 v6_medium、v5_server识别率更高但速度更慢文档给出两条提速路径GPU 推理Win10 之后的软件版本可直接在设置中开启 GPU 运行模型。OpenVINO 推理使用 Intel CPU/NPU/GPU 时可下载 onnxruntime-openvino 运行时将其runtimes/win-x64/native下的文件覆盖到LunaTranslator/files/DLL64目录然后在设备选择中切换。内置 OCR 的实现位于 ocrengines/local.py底层依赖原生推理模块ONNX Runtime 封装见 NativeImpl/CVUtils/localocr.cpp。7.3 其他离线 OCRSnippingTool仅支持 Windows 10/11Windows 11 最新版可直接使用否则需在设置中安装该模块。Manga-OCR针对漫画文本优化但文档警告对横排文本识别效果较差需单独下载 CPU/GPU 集成包。WeChat/QQ OCR依赖本机安装微信或最新版 QQ。WindowsOCR性能较差、不推荐仅支持 Windows 10/11且需要按文档指引查询、安装对应语言的 OCR 语言包。Tesseract5性能较差、不推荐。八、翻译引擎体系大语言模型与离线模型docs/vi/guochandamoxing.md 是翻译能力中占比最重的一篇核心是通用大模型接口的统一配置范式。仓库 translator/ 目录下数十个引擎文件含 chatgptlike.py、sakura.py、ModernMt.py 等正是几乎覆盖所有翻译引擎的源码体现。8.1 通用大模型接口参数详解参数说明API 地址多数主流平台的地址可直接在下拉框选择未收录的按平台文档自行填写API Key在平台获取填入多个 Key 时系统会自动轮换并根据错误反馈动态调整权重Model填入地址与 Key 后点击刷新按钮拉取可用模型列表平台不支持模型列表 API 时手动填写流式输出开启后译文逐字递增显示关闭则等模型完成后一次性输出附带上下文个数将若干条原文与译文历史附加给大模型以优化翻译设为 0 关闭自定义 system prompt / user message / Prefill通过占位符引用动态信息见下文Temperature / max tokens / top p / frequency penalty部分平台接口不接收top p、frequency penalty或已用max completion tokens取代max tokens可用开关切换兼容模式reasoning effort控制部分平台支持的推理强度Gemini 平台自动映射为thinkingBudgetnone/minimal→0关闭推理不适用于 Gemini-2.5-Pro、low→512、medium→-1动态推理、high/xhigh→24576thinking.type部分平台主要是 DeepSeek的思维链模式开关其他参数支持自由追加键值对适配平台专属参数Prompt 占位符是定制翻译效果的关键支持以下字段{sentence}待翻译文本{srclang}/{tgtlang}源语言与目标语言若 prompt 全为英文则替换为英文语言名否则替换为当前 UI 语言下的语言名{contextOriginal[N]}/{contextTranslation[N]}/{contextBoth[N]}最近 N 条原文 / 译文 / 两者。若写contextBoth[N]则引用附带上下文个数设置若写contextBoth[10]则固定取 10 条{DictWithPrompt[XXXXX]}引用翻译术语表中的词条XXXXX是指导 LLM 使用这些词条优化译文的说明文字找不到匹配词条时该字段会被整体删除以免污染译文。8.2 多接口并行若只有多个不同 Key 想轮流使用用|分隔即可。但若想同时使用不同 API 地址、prompt、模型或参数做对比则需要点击上方号新建一个通用大模型接口 → 为其命名会复制当前接口的设置与 API→ 激活副本并独立配置。副本与原件可以并行运行。8.3 平台支持欧美平台OpenAI、Gemini、Nvidia、Claude、Cohere、x.ai、Groq、OpenRouter、Mistral AI、Azure、Cerebras 等。其中 Azure 需按https://{endpoint}.openai.azure.com/openai/deployments/{deployName}/chat/completions?api-version2023-12-01-preview的格式替换 endpoint 与 deployName讯飞 Spark 的 API Key 需按APIKey:APISecret格式填写百度千帆的 API Key 需使用智能云 IAM 的 Access Key/Secret Key 生成 BearerToken或直接按Access Key:Secret Key格式填写注意不是千帆旧版 v1 的 API Key/Secret Key。国产平台DeepSeek、小米 MiMo、阿里云百炼、火山引擎方舟、Moonshot AI、智谱 AI、讯飞星火、腾讯混元、百度千帆、MiniMax 等。聚合管理可通过 new-api 等 API 转发工具统一管理多平台多 Key若使用此类工具可参考其提供的 LunaTranslator 接入文档进行配置。8.4 专用离线翻译模型部分大模型专为离线翻译或特定场景微调需要专用 prompt 格式才能发挥最佳效果因此软件单独提供了一套不开放用户自定义 prompt、使用模型发行方既定 prompt的专用接口。当前支持出品方模型适用语言tencentHy-MT2多语言通用SakuraLLMSakuraLLM GalTransl日文 → 中文这类模型部署完成后多数也能直接通过通用大模型接口调用仅在需要专用 prompt 格式时使用专用接口。九、语言学习日语分词、假名注音与词典生态首页将语言学习列为独立能力涉及日语分词注音qa1.md、AnkiConnect 与 Yomitan 插件yomitan.md三块内容。9.1 MeCab UniDic日语分词的基石日文分词与假名注音依赖 MeCab 搭配 UniDic 词典配置有两种路径自动下载在词典设置 → 资源下载中若尚未下载 UniDic 会出现下载按钮点击即自动下载并配置好路径。手动配置自动下载只获取常用版本unidic-mecab-2.1.2_bin想用其他版本可自行下载解压到软件目录后重启软件自动识别或解压到任意目录后手动指定路径。完成分词后激活显示假名注音默认开启与语法高亮即可在译文中看到逐词的 furigana 标注与高亮。9.2 源码级实现mecab.py 的解析链路分词与注音的核心实现在 myutils/mecab.pyMeCab 封装mecab类mecab.py初始化时依次探测用户配置路径、程序目录、C:\Program Files\MeCab\dic等常见目录寻找词典解析时调用NativeUtils.mecab原生模块根据 UniDic 不同版本的特征字段数26/29/17/9 等提取读音kana、原型origorig与词性pos1英文词汇直接以英文形式作为读音。假名显示策略parseastargetmecab.py由全局配置hira_vis_type控制注音形态——0 为片假名转平假名、1 为平假名转片假名、2 为转罗马音纯假名词会按需隐藏注音避免冗余。Ruby HTML 生成makerubyhtmlmecab.py将分词结果渲染为ruby注音 HTML 供界面展示。配置入口hirasetting.mecab.args.path即 UniDic 词典目录类型为目录选择器config.json。除 MeCab 外该模块还提供latin拉丁语系按标点切分、jiebapinyin中文结巴分词 拼音注音等实现可覆盖多语言学习场景。词典方面仓库 cishu/ 内置了 Moji辞书、有道、jisho、jpdb、JapanDict、weblio 等在线词典以及 mdict、自建词典支持。9.3 Yomitan 浏览器插件Yomitan 配置文档 给出了将 Yomitan 浏览器划词插件接入翻译界面的完整步骤确认显示引擎为 Webview2浏览器插件依赖 Webview2除系统不支持外默认即为该引擎。开启使用浏览器插件并加载 Yomitan 扩展务必使用 Chrome/Edge 版本Firefox 版不兼容。等待初始化完成后再配置 Yomitan若插件未被识别可关闭软件重开一次。窗口尺寸联动主窗口默认按文本与译文自动调整高度这会连带改变 Yomitan 窗口尺寸若想固定可在显示设置 → 界面设置 → 主界面中取消勾选自动调整高度。历史文本窗口同样支持浏览器插件但默认关闭以节省资源。至于 AnkiConnect 卡片同步仓库在 myutils/template/myanki_v3.py 中提供了 Anki 模板实现与首页支持 AnkiConnect的能力描述相互印证。十、语音合成多引擎 TTSdocs/vi/ttsengines.md 梳理了 TTS 引擎接入方式仓库 tts/ 目录下的引擎文件与之对应edgetts、gtts、windowstts、voicevox、voiceroid2、gptsovits、bcuttts、huoshantts、chatgpttts、vitsSimpleAPI、selfbuild、tolk 等。Windows TTSWindows 7 及以上可通过系统语言设置添加对应语言的 SAPI 语音包Windows 10/11 可使用更自然的 Natural Voice。注意因微软改变了新版语言包的编码方式已安装语言包与新版下载语言包可能无法直接使用需参考官方修复说明处理。Windows 11 还可在辅助功能 → 讲述人 → 添加自然语音中增加高质量语音Windows 10 则可下载 Natural Voice 资源解压到软件目录部分系统还需额外补装语音运行时。VoiceRoid / A.I.VOICEA.I.VOICE 需从官网下载安装VoiceRoid 可在软件资源下载中获取但追加音源必须先装任意一个整合包——整合包内含常用音源与必要运行时只下载追加音源会缺少 VoiceRoid 运行时。VOICEVOX下载并运行 VOICEVOX 本体即可默认端口与软件预设一致两端不改设置的话开箱即用。GPT-SoVITSAPI version中的 v2 指 API 接口版本而非模型版本一般默认使用 v2除少数常用参数外支持自由追加其他参数。十一、语音识别Windows 语音识别接入docs/vi/sr.md 说明在 Windows 10/11 上可使用 Windows 语音识别功能提供两种模式直接调用模式直接调用 Windows 语音识别模型性能更好Windows 10 可用。在核心设置 → 其他 → 语音识别中选择识别语言并启用。Windows 11 会自动检测已装语言与对应模型Windows 10 或低版本 Windows 11 需先安装作者打包的中日英识别运行时解压到软件目录后自动识别。其他语言可按MicrosoftWindows.Speech.{LANGUAGE}.1_cw5n1h2txyewy的 PackageFamilyName 在对应商店抓包站点检索 msix 包解压使用。间接读取模式通过读取 Windows 11LiveCaptions实时字幕窗口的文本间接工作仅限 Windows 11性能稍弱但无运行时与许可兼容问题开启切换即可使用。十二、从功能矩阵到源码一篇文章读懂 LunaTranslator回到 docs/vi/index.md八个功能卡片并非孤立的功能罗列而是构成了一条完整的视觉小说翻译工作流HOOK/模拟器/OCR 负责取文本翻译接口负责译文本内嵌翻译负责放回游戏语言学习与 TTS/SR 负责用文本。每一环都能在仓库中找到对应的源码模块与默认配置取文本textio/textsource/texthook.pyHOOK、ocrengines/local.py内置 OCR、NativeImpl/LunaHook/LunaHook/emulators模拟器译文本translator/翻译引擎目录、defaultconfig/translatorsetting.json翻译默认配置学文本myutils/mecab.py分词注音、cishu/词典、myutils/template/myanki_v3.pyAnki听/说文本tts/合成、Windows 语音识别接入识别。对使用者而言建议的上手顺序是先按 README 完成下载与杀软白名单配置再按 basicuse.md 从 HOOK 模式跑通第一句译文之后根据游戏类型补充 hooksettings.md 的调优参数最后按需启用内嵌翻译、OCR 模型与大模型翻译接口逐步搭建出适合自己的完整翻译与学习环境。【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LunaTranslator 功能全景指南：HOOK 文本提取、内嵌翻译、OCR 与大模型翻译一站式解读
LunaTranslator 功能全景指南HOOK 文本提取、内嵌翻译、OCR 与大模型翻译一站式解读【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslatorLunaTranslator 是一款面向视觉小说Galgame的翻译工具其官方文档首页 docs/vi/index.md 以功能卡片的形式概括了软件的八大核心能力HOOK 文本提取、内嵌翻译、HOOK 模拟器、OCR、丰富翻译接口、语言学习、语音合成与语音识别。本文以这份功能矩阵为主线逐项展开对应子文档的实操细节并引入仓库源码佐证实现原理帮助读者从知道有什么功能进阶到知道怎么配置、为什么这样配置。一、功能矩阵文档首页在讲什么与常见的 VitePress 文档一样docs/vi/index.md 是文档站首页采用layout: home布局通过 hero 区的三个动作按钮软件下载与常见问题、基本用法、Github和八个 feature 卡片快速导航全站。八个功能卡片构成了 LunaTranslator 的能力全景功能一句话定位对应子文档HOOK以 HOOK 方式提取游戏文本兼容绝大多数常见与冷门视觉小说hooksettings.md内嵌翻译部分游戏可直接将译文嵌入游戏内获得沉浸式体验embedtranslate.mdHOOK 模拟器对 NS/PSP/PSV/PS2 上的大部分游戏直接读取游戏文本emugames.mdOCR内置高精度 OCR 模型并支持大量在线/离线 OCR 引擎useapis/ocrapi.md丰富翻译接口支持几乎所有翻译引擎含大语言模型翻译与离线翻译guochandamoxing.md语言学习日语分词与假名注音支持 AnkiConnect 与 Yomitan 插件qa1.md、yomitan.md语音合成支持大量在线与离线 TTS 引擎ttsengines.md语音识别在 Windows 10 / 11 上使用 Windows 语音识别sr.md在仓库层面这些能力可以一一对应到src/LunaTranslator下的源码模块textio/textsource/texthook.pyHOOK 文本源、ocrengines/OCR 引擎目录、translator/翻译引擎目录、cishu/词典目录、tts/语音合成目录可见首页功能矩阵并非宣传文案而是对代码结构的直接映射。二、下载、启动与更新把软件跑起来功能再丰富第一步也是正确下载与启动。docs/vi/README.md 明确了系统支持范围与启动注意事项。2.1 系统支持与下载主推版本Windows 11 与 Windows 101803的 64 位版本提供一键下载按钮。旧系统兼容版Windows 732/64 位、Windows XP 与 Vista32 位也有对应构建。但文档明确警告这些旧版本性能较差、运行不稳定、缺失部分功能、容易被杀毒软件误报除非有特殊需求否则不推荐使用。2.2 启动方式与目录要求解压后有三个启动入口可执行文件说明LunaTranslator.exe普通模式启动LunaTranslator_admin.exe以管理员权限启动HOOK 部分游戏必需仅必要时使用LunaTranslator_debug.bat附带命令行窗口便于查看日志一个非常关键的目录约束不要将软件放在C:\Program Files等特殊路径否则即使有管理员权限也可能无法保存配置与缓存文件甚至无法运行程序。这背后的原因是配置文件写入权限与 UAC 虚拟化值得所有用户在第一时间规避。2.3 更新机制软件默认自动更新自动更新失败时可手动更新——直接下载新版本解压覆盖旧目录即可。特别强调卸载重装时不要删除userconfig目录否则将丢失所有既有设置。从仓库结构看用户配置与软件本体分离的设计gobject.thisuserconfig指向独立用户配置目录见 mecab.py 中对用户配置目录的引用正是为了支持这种覆盖更新保留配置的工作流。2.4 常见启动错误排查README 整理了四类高频错误其根因大多指向杀毒软件误报缺少重要组件 / Missing embedded Python3杀软拦截了内置 Python 运行时。解决方法是关闭杀软或将软件目录加入白名单后重新下载解压。等待注入 DLL 到游戏中…与上一项同因。HOOK 机制需要向游戏进程注入LunaSubprocess32.exe/LunaHost32.dll等文件这种注入行为极易被启发式引擎判为病毒。文档给出的判断依据是软件由 GitHub Actions 自动构建除非构建服务器被感染否则不可能携带病毒可放心加白。Error / FileNotFoundError运行一段时间后出现通常意味着关键组件已被杀软静默删除处理方式同上。Error / PermissionError通常是因为软件被放置在C:\Program Files等受保护目录。在源码侧DLL 注入与文本提取的实现位于 NativeImpl/LunaHost 与 NativeImpl/LunaHook 两个原生模块中其中LunaHostDll.cpp、injector.cpp承担进程注入职责这正是杀软关注点的来源。三、基本用法三种文本获取方式docs/vi/basicuse.md 给出了上手软件最核心的三条路径分别对应视觉小说的三种典型文本来源。3.1 HOOK 模式首选对已经启动的游戏切换至 HOOK 模式 → 打开进程选择窗口 → 选中游戏进程。确认后游戏会加入软件列表并被注入随后弹出文本选择窗口。此时让游戏继续运行一段时间产生文本文本选择窗口中会列出候选文本行选中与游戏画面一致的那一行即可开始翻译。若该游戏支持内嵌翻译文本行所在列会同时出现嵌入按钮否则只有显示按钮。HOOK 模式的文本流式更新与候选行过滤对应源码 textio/textsource/texthook.py 与 HOOK 原生端的文本线程实现。3.2 OCR 模式兜底部分游戏无法 HOOK 时可切换至 OCR 模式框选识别区域软件将自动循环识别画面文本并翻译。文档特别提醒不要误用按钮——工具栏中外观相似的另一按钮只做一次性截图识别不会持续跟踪画面。3.3 拖拽启动与自动 HOOK更快捷的路径将游戏程序直接拖入软件窗口软件会自动完成添加游戏 → 以转区方式启动 → 自动 HOOK三步随后弹出文本选择窗口后续操作与 HOOK 模式一致。这对需要加载区域语言Locale Emulator / NTLEA 式转区才能运行的日文游戏尤为方便。四、HOOK 设置详解从提取到输出的调优HOOK 是 LunaTranslator 的主战场hooksettings.md 将配置分为通用设置与游戏专属设置两层这一分层与配置系统中默认配置 覆盖配置的设计一一对应。4.1 通用设置5 个核心参数代码页Code Page仅当引擎提取出的是编码未知的多字节字符串时该设置才生效若引擎已确定代码页或文本为 UTF-16/UTF-32 字符串则该设置无效。通常无需改动——只有 Yuris 等老引擎的中文官方版可能使用 GBK/BIG5/UTF8 时需要关注。找不到正确文本时更有效的做法是直接提交 issue 反馈而非盲目修改代码页。刷新延迟Refresh Delay针对三类症状对症下药——文本逐字/逐二字蹦出或文本按行刷新、旧行被顶掉只剩最后一行 →增加刷新延迟或提高游戏文本显示速度文本正确但提取很慢 →适当降低刷新延迟同时小心不要诱发前两类问题。最大缓冲长度Maximum Buffer Length当文本持续刷新不停顿、刷新延迟又降不下来时缓冲区会持续接收直到写满。可适当减小缓冲长度来加快落定但不能短于实际文本长度。最大缓存文本长度Maximum Cached Text Length历史文本会被缓存用于文本选择窗口的查看。文本项过多或持续刷新会导致缓存膨胀、查看变慢。默认值为 1000000文档明确建议可以大胆调小到 1000——真正有价值的历史文本可以在历史文本窗口中查看。最大允许输出文本长度跳过剧情或回看历史文本时可能一次性涌出大量文本但用户未必关心。将此值调到合适范围即可滤除这类突发输出。4.2 游戏专属设置补充 HookWin32 全局 Hook开启后向游戏注入 GDI、D3DX 及字符串相关函数的全局 Win32 Hook。由于注入过多 Hook 会拖慢游戏这些 Hook 默认不注入仅当无法正确提取文本时才建议尝试开启。特殊码Special Codes当某条特殊码被插入且其文本被选中时该特殊码会被自动记录下次启动游戏时自动应用。设置页会列出所有已记录的特殊码可自由增删。这解决了每次进游戏都要手动插入特殊码的重复劳动。延迟注入Delayed Injection部分游戏的 Hook 点位于运行一段时间后才加载的 DLL 上此时需要等待 DLL 加载完成再执行注入。游戏专属设置覆盖在设置 → HOOK 设置中修改的是全局默认值若需要为单个游戏定制进入游戏管理 → 游戏设置在设置选项卡中切换到 HOOK 页取消勾选使用默认设置即可独立配置。五、内嵌翻译把译文写进游戏画面docs/vi/embedtranslate.md 描述了沉浸式翻译方案的完整使用与排障流程。5.1 使用前提与操作首先要接受两个前提并非所有游戏都支持内嵌内嵌可能造成游戏卡死。文本选择窗口中若文本行没有嵌入按钮即表示不支持。操作流程在文本选择窗口选中支持内嵌的文本项并激活。注意显示与嵌入是两个独立开关两者都开游戏内嵌译文软件窗口显示更完整的译文只开嵌入仅在游戏内显示译文软件窗口不再显示内容。5.2 乱码排查字符集与字体开始内嵌翻译后最常见的故障是译文显示乱码文档给出的排查顺序是先查字体英文游戏内嵌中文译文时多为缺少中文字体所致。此时需开启编辑游戏字体并选择一款能显示中文的字体。再查字符集许多经典日式 Galgame 使用内置 Shift-JIS 字符集处理中文可尝试开启简体转繁体/日文汉字来减少显示错误而较新引擎KiriKiri、Renpy、TyranoScript、RPGMakerMV 等多使用 UTF-8/UTF-16乱码基本是字体问题而非字符集问题关闭该转换选项后简体中文即可正确显示个别无法正确显示简体的游戏则反向尝试开启该选项。5.3 内嵌设置项设置作用显示模式受游戏可显示行数限制默认不在译文与原文之间加换行确认行数够用后可在翻译优化 → 译文处理中通过正则给译文前添加换行翻译等待时间内嵌原理是在游戏显示文本前暂停游戏、发翻译请求、等待译文、改写内存后继续显示因此慢速翻译必然造成游戏卡顿通过限制等待时间可避免长时间卡顿转繁体/日文见 5.2每行字符数限制部分游戏单行有长度上限超长内容会溢出文本框右侧不可见可设置自动断行规避编辑游戏字体 / 相对字号调整解决字体缺失与字号不匹配删除游戏内显示文本开启后游戏原文本会被清空适用三种场景① 内嵌乱码无法解决时将软件窗口覆盖在原文位置伪装内嵌效果② 使用外部翻译工具时避免译文窗口与原文重叠③ 纯日语学习场景移除原文干扰配合假名注音与双语显示暂停游戏 → 改写内存 → 恢复显示这一机制说明内嵌翻译在实现上依赖内存改写而非截图叠加这也解释了为何它对引擎兼容性要求极高。六、HOOK 模拟器覆盖 NS/PSP/PSV/PS2 主机游戏docs/vi/emugames.md 通过 include 机制引入 docs/emusupportlist/all.md给出当前模拟器支持矩阵平台支持的模拟器含版本要求NSyuzu(≥1616)已停用、Eden (MSVC)、Citron (MSVC)PSPPPSSPP ≥ v1.15.0PSVVita3K ≥ v0.1.9.3339PS2PCSX2 ≥ v1.7.4473PS3RPCS3这一能力在仓库 NativeImpl/LunaHook/LunaHook/emulators 目录中落地——该目录集中存放各主机模拟器的文本读取适配代码。对不在支持列表中的游戏文档引导用户提交 issue 请求适配。七、OCR 引擎体系内置模型与多引擎生态docs/vi/useapis/ocrapi.md 将 OCR 引擎划分为在线与离线两大阵营而 ocrsetting.json 则给出了默认配置的源码级证据。7.1 在线 OCR内置平台包括百度智能云 OCR含图片翻译、百度翻译开放平台图片翻译、腾讯通用印刷体识别与图片翻译、有道、火山引擎、讯飞、Google Cloud Vision、Ocr.space以及通用大模型接口与大语言模型翻译共用同一套接口配置见下文第八章。7.2 内置 OCR离线软件随包内置PP-OCRv5_mobile轻量模型支持简中、繁中、英文、日文识别无需任何配置开箱即用。设置页还提供多档模型可选文档给出了官方评测数据检测 Hmean / 识别平均准确率 / 语言支持 / 体积模型检测 Hmean(%)识别准确率(%)支持语言体积(MB)PP-OCRv6_small84.181.3任意25.2PP-OCRv6_medium86.283.2任意99.7PP-OCRv6_tiny80.673.5任意5.45PP-OCRv5_mobile79.081.29简中/繁中/英/日17.7PP-OCRv5_server83.886.38简中/繁中/英/日148eslav_PP-OCRv5_mobile79.081.6东斯拉夫语系11.2korean_PP-OCRv5_mobile79.088.0韩语12.2latin_PP-OCRv5_mobile79.084.7拉丁字母语系11.3从源码看默认配置确实指向内置模型defaultconfig/ocrsetting.json中local引擎的默认参数为model: PP-OCRv5_mobile、thread: 4、device_type: CPU、gpu: falseocrsetting.json。高精度模型如 v6_medium、v5_server识别率更高但速度更慢文档给出两条提速路径GPU 推理Win10 之后的软件版本可直接在设置中开启 GPU 运行模型。OpenVINO 推理使用 Intel CPU/NPU/GPU 时可下载 onnxruntime-openvino 运行时将其runtimes/win-x64/native下的文件覆盖到LunaTranslator/files/DLL64目录然后在设备选择中切换。内置 OCR 的实现位于 ocrengines/local.py底层依赖原生推理模块ONNX Runtime 封装见 NativeImpl/CVUtils/localocr.cpp。7.3 其他离线 OCRSnippingTool仅支持 Windows 10/11Windows 11 最新版可直接使用否则需在设置中安装该模块。Manga-OCR针对漫画文本优化但文档警告对横排文本识别效果较差需单独下载 CPU/GPU 集成包。WeChat/QQ OCR依赖本机安装微信或最新版 QQ。WindowsOCR性能较差、不推荐仅支持 Windows 10/11且需要按文档指引查询、安装对应语言的 OCR 语言包。Tesseract5性能较差、不推荐。八、翻译引擎体系大语言模型与离线模型docs/vi/guochandamoxing.md 是翻译能力中占比最重的一篇核心是通用大模型接口的统一配置范式。仓库 translator/ 目录下数十个引擎文件含 chatgptlike.py、sakura.py、ModernMt.py 等正是几乎覆盖所有翻译引擎的源码体现。8.1 通用大模型接口参数详解参数说明API 地址多数主流平台的地址可直接在下拉框选择未收录的按平台文档自行填写API Key在平台获取填入多个 Key 时系统会自动轮换并根据错误反馈动态调整权重Model填入地址与 Key 后点击刷新按钮拉取可用模型列表平台不支持模型列表 API 时手动填写流式输出开启后译文逐字递增显示关闭则等模型完成后一次性输出附带上下文个数将若干条原文与译文历史附加给大模型以优化翻译设为 0 关闭自定义 system prompt / user message / Prefill通过占位符引用动态信息见下文Temperature / max tokens / top p / frequency penalty部分平台接口不接收top p、frequency penalty或已用max completion tokens取代max tokens可用开关切换兼容模式reasoning effort控制部分平台支持的推理强度Gemini 平台自动映射为thinkingBudgetnone/minimal→0关闭推理不适用于 Gemini-2.5-Pro、low→512、medium→-1动态推理、high/xhigh→24576thinking.type部分平台主要是 DeepSeek的思维链模式开关其他参数支持自由追加键值对适配平台专属参数Prompt 占位符是定制翻译效果的关键支持以下字段{sentence}待翻译文本{srclang}/{tgtlang}源语言与目标语言若 prompt 全为英文则替换为英文语言名否则替换为当前 UI 语言下的语言名{contextOriginal[N]}/{contextTranslation[N]}/{contextBoth[N]}最近 N 条原文 / 译文 / 两者。若写contextBoth[N]则引用附带上下文个数设置若写contextBoth[10]则固定取 10 条{DictWithPrompt[XXXXX]}引用翻译术语表中的词条XXXXX是指导 LLM 使用这些词条优化译文的说明文字找不到匹配词条时该字段会被整体删除以免污染译文。8.2 多接口并行若只有多个不同 Key 想轮流使用用|分隔即可。但若想同时使用不同 API 地址、prompt、模型或参数做对比则需要点击上方号新建一个通用大模型接口 → 为其命名会复制当前接口的设置与 API→ 激活副本并独立配置。副本与原件可以并行运行。8.3 平台支持欧美平台OpenAI、Gemini、Nvidia、Claude、Cohere、x.ai、Groq、OpenRouter、Mistral AI、Azure、Cerebras 等。其中 Azure 需按https://{endpoint}.openai.azure.com/openai/deployments/{deployName}/chat/completions?api-version2023-12-01-preview的格式替换 endpoint 与 deployName讯飞 Spark 的 API Key 需按APIKey:APISecret格式填写百度千帆的 API Key 需使用智能云 IAM 的 Access Key/Secret Key 生成 BearerToken或直接按Access Key:Secret Key格式填写注意不是千帆旧版 v1 的 API Key/Secret Key。国产平台DeepSeek、小米 MiMo、阿里云百炼、火山引擎方舟、Moonshot AI、智谱 AI、讯飞星火、腾讯混元、百度千帆、MiniMax 等。聚合管理可通过 new-api 等 API 转发工具统一管理多平台多 Key若使用此类工具可参考其提供的 LunaTranslator 接入文档进行配置。8.4 专用离线翻译模型部分大模型专为离线翻译或特定场景微调需要专用 prompt 格式才能发挥最佳效果因此软件单独提供了一套不开放用户自定义 prompt、使用模型发行方既定 prompt的专用接口。当前支持出品方模型适用语言tencentHy-MT2多语言通用SakuraLLMSakuraLLM GalTransl日文 → 中文这类模型部署完成后多数也能直接通过通用大模型接口调用仅在需要专用 prompt 格式时使用专用接口。九、语言学习日语分词、假名注音与词典生态首页将语言学习列为独立能力涉及日语分词注音qa1.md、AnkiConnect 与 Yomitan 插件yomitan.md三块内容。9.1 MeCab UniDic日语分词的基石日文分词与假名注音依赖 MeCab 搭配 UniDic 词典配置有两种路径自动下载在词典设置 → 资源下载中若尚未下载 UniDic 会出现下载按钮点击即自动下载并配置好路径。手动配置自动下载只获取常用版本unidic-mecab-2.1.2_bin想用其他版本可自行下载解压到软件目录后重启软件自动识别或解压到任意目录后手动指定路径。完成分词后激活显示假名注音默认开启与语法高亮即可在译文中看到逐词的 furigana 标注与高亮。9.2 源码级实现mecab.py 的解析链路分词与注音的核心实现在 myutils/mecab.pyMeCab 封装mecab类mecab.py初始化时依次探测用户配置路径、程序目录、C:\Program Files\MeCab\dic等常见目录寻找词典解析时调用NativeUtils.mecab原生模块根据 UniDic 不同版本的特征字段数26/29/17/9 等提取读音kana、原型origorig与词性pos1英文词汇直接以英文形式作为读音。假名显示策略parseastargetmecab.py由全局配置hira_vis_type控制注音形态——0 为片假名转平假名、1 为平假名转片假名、2 为转罗马音纯假名词会按需隐藏注音避免冗余。Ruby HTML 生成makerubyhtmlmecab.py将分词结果渲染为ruby注音 HTML 供界面展示。配置入口hirasetting.mecab.args.path即 UniDic 词典目录类型为目录选择器config.json。除 MeCab 外该模块还提供latin拉丁语系按标点切分、jiebapinyin中文结巴分词 拼音注音等实现可覆盖多语言学习场景。词典方面仓库 cishu/ 内置了 Moji辞书、有道、jisho、jpdb、JapanDict、weblio 等在线词典以及 mdict、自建词典支持。9.3 Yomitan 浏览器插件Yomitan 配置文档 给出了将 Yomitan 浏览器划词插件接入翻译界面的完整步骤确认显示引擎为 Webview2浏览器插件依赖 Webview2除系统不支持外默认即为该引擎。开启使用浏览器插件并加载 Yomitan 扩展务必使用 Chrome/Edge 版本Firefox 版不兼容。等待初始化完成后再配置 Yomitan若插件未被识别可关闭软件重开一次。窗口尺寸联动主窗口默认按文本与译文自动调整高度这会连带改变 Yomitan 窗口尺寸若想固定可在显示设置 → 界面设置 → 主界面中取消勾选自动调整高度。历史文本窗口同样支持浏览器插件但默认关闭以节省资源。至于 AnkiConnect 卡片同步仓库在 myutils/template/myanki_v3.py 中提供了 Anki 模板实现与首页支持 AnkiConnect的能力描述相互印证。十、语音合成多引擎 TTSdocs/vi/ttsengines.md 梳理了 TTS 引擎接入方式仓库 tts/ 目录下的引擎文件与之对应edgetts、gtts、windowstts、voicevox、voiceroid2、gptsovits、bcuttts、huoshantts、chatgpttts、vitsSimpleAPI、selfbuild、tolk 等。Windows TTSWindows 7 及以上可通过系统语言设置添加对应语言的 SAPI 语音包Windows 10/11 可使用更自然的 Natural Voice。注意因微软改变了新版语言包的编码方式已安装语言包与新版下载语言包可能无法直接使用需参考官方修复说明处理。Windows 11 还可在辅助功能 → 讲述人 → 添加自然语音中增加高质量语音Windows 10 则可下载 Natural Voice 资源解压到软件目录部分系统还需额外补装语音运行时。VoiceRoid / A.I.VOICEA.I.VOICE 需从官网下载安装VoiceRoid 可在软件资源下载中获取但追加音源必须先装任意一个整合包——整合包内含常用音源与必要运行时只下载追加音源会缺少 VoiceRoid 运行时。VOICEVOX下载并运行 VOICEVOX 本体即可默认端口与软件预设一致两端不改设置的话开箱即用。GPT-SoVITSAPI version中的 v2 指 API 接口版本而非模型版本一般默认使用 v2除少数常用参数外支持自由追加其他参数。十一、语音识别Windows 语音识别接入docs/vi/sr.md 说明在 Windows 10/11 上可使用 Windows 语音识别功能提供两种模式直接调用模式直接调用 Windows 语音识别模型性能更好Windows 10 可用。在核心设置 → 其他 → 语音识别中选择识别语言并启用。Windows 11 会自动检测已装语言与对应模型Windows 10 或低版本 Windows 11 需先安装作者打包的中日英识别运行时解压到软件目录后自动识别。其他语言可按MicrosoftWindows.Speech.{LANGUAGE}.1_cw5n1h2txyewy的 PackageFamilyName 在对应商店抓包站点检索 msix 包解压使用。间接读取模式通过读取 Windows 11LiveCaptions实时字幕窗口的文本间接工作仅限 Windows 11性能稍弱但无运行时与许可兼容问题开启切换即可使用。十二、从功能矩阵到源码一篇文章读懂 LunaTranslator回到 docs/vi/index.md八个功能卡片并非孤立的功能罗列而是构成了一条完整的视觉小说翻译工作流HOOK/模拟器/OCR 负责取文本翻译接口负责译文本内嵌翻译负责放回游戏语言学习与 TTS/SR 负责用文本。每一环都能在仓库中找到对应的源码模块与默认配置取文本textio/textsource/texthook.pyHOOK、ocrengines/local.py内置 OCR、NativeImpl/LunaHook/LunaHook/emulators模拟器译文本translator/翻译引擎目录、defaultconfig/translatorsetting.json翻译默认配置学文本myutils/mecab.py分词注音、cishu/词典、myutils/template/myanki_v3.pyAnki听/说文本tts/合成、Windows 语音识别接入识别。对使用者而言建议的上手顺序是先按 README 完成下载与杀软白名单配置再按 basicuse.md 从 HOOK 模式跑通第一句译文之后根据游戏类型补充 hooksettings.md 的调优参数最后按需启用内嵌翻译、OCR 模型与大模型翻译接口逐步搭建出适合自己的完整翻译与学习环境。【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考