企业官网建设流程全解析

LunaTranslator 功能全景指南：HOOK 文本提取、内嵌翻译、OCR 与大模型翻译一站式解读

【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslator

LunaTranslator 是一款面向视觉小说（Galgame）的翻译工具，其官方文档首页 docs/vi/index.md 以功能卡片的形式概括了软件的八大核心能力：HOOK 文本提取、内嵌翻译、HOOK 模拟器、OCR、丰富翻译接口、语言学习、语音合成与语音识别。本文以这份功能矩阵为主线，逐项展开对应子文档的实操细节，并引入仓库源码佐证实现原理，帮助读者从"知道有什么功能"进阶到"知道怎么配置、为什么这样配置"。

一、功能矩阵：文档首页在讲什么

与常见的 VitePress 文档一样，docs/vi/index.md 是文档站首页，采用layout: home布局，通过 hero 区的三个动作按钮（软件下载与常见问题、基本用法、Github）和八个 feature 卡片快速导航全站。八个功能卡片构成了 LunaTranslator 的能力全景：

在仓库层面，这些能力可以一一对应到src/LunaTranslator下的源码模块：textio/textsource/texthook.py（HOOK 文本源）、ocrengines/（OCR 引擎目录）、translator/（翻译引擎目录）、cishu/（词典目录）、tts/（语音合成目录），可见首页功能矩阵并非宣传文案，而是对代码结构的直接映射。

二、下载、启动与更新：把软件跑起来

功能再丰富，第一步也是正确下载与启动。docs/vi/README.md 明确了系统支持范围与启动注意事项。

2.1 系统支持与下载

• 主推版本：Windows 11 与 Windows 10（1803+）的 64 位版本，提供一键下载按钮。
• 旧系统兼容版：Windows 7（32/64 位）、Windows XP 与 Vista（32 位）也有对应构建。但文档明确警告：这些旧版本性能较差、运行不稳定、缺失部分功能、容易被杀毒软件误报，除非有特殊需求否则不推荐使用。

2.2 启动方式与目录要求

解压后有三个启动入口：

一个非常关键的目录约束：不要将软件放在C:\Program Files等特殊路径，否则即使有管理员权限，也可能无法保存配置与缓存文件，甚至无法运行程序。这背后的原因是配置文件写入权限与 UAC 虚拟化，值得所有用户在第一时间规避。

2.3 更新机制

软件默认自动更新；自动更新失败时可手动更新——直接下载新版本解压覆盖旧目录即可。特别强调：卸载重装时不要删除userconfig目录，否则将丢失所有既有设置。从仓库结构看，用户配置与软件本体分离的设计（gobject.thisuserconfig指向独立用户配置目录，见 mecab.py 中对用户配置目录的引用）正是为了支持这种"覆盖更新保留配置"的工作流。

2.4 常见启动错误排查

README 整理了四类高频错误，其根因大多指向杀毒软件误报：

1. "缺少重要组件 / Missing embedded Python3"：杀软拦截了内置 Python 运行时。解决方法是关闭杀软或将软件目录加入白名单后重新下载解压。
2. "等待注入 DLL 到游戏中…"：与上一项同因。HOOK 机制需要向游戏进程注入LunaSubprocess32.exe/LunaHost32.dll等文件，这种注入行为极易被启发式引擎判为病毒。文档给出的判断依据是：软件由 GitHub Actions 自动构建，除非构建服务器被感染否则不可能携带病毒，可放心加白。
3. Error / FileNotFoundError：运行一段时间后出现，通常意味着关键组件已被杀软静默删除，处理方式同上。
4. 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 游戏专属设置

补充 Hook（Win32 全局 Hook）：开启后向游戏注入 GDI、D3DX 及字符串相关函数的全局 Win32 Hook。由于注入过多 Hook 会拖慢游戏，这些 Hook 默认不注入；仅当无法正确提取文本时才建议尝试开启。

特殊码（Special Codes）：当某条特殊码被插入且其文本被选中时，该特殊码会被自动记录，下次启动游戏时自动应用。设置页会列出所有已记录的特殊码，可自由增删。这解决了"每次进游戏都要手动插入特殊码"的重复劳动。

延迟注入（Delayed Injection）：部分游戏的 Hook 点位于运行一段时间后才加载的 DLL 上，此时需要等待 DLL 加载完成再执行注入。

游戏专属设置覆盖：在"设置 → HOOK 设置"中修改的是全局默认值；若需要为单个游戏定制，进入游戏管理 → 游戏设置，在设置选项卡中切换到 HOOK 页，取消勾选"使用默认设置"即可独立配置。

五、内嵌翻译：把译文写进游戏画面

docs/vi/embedtranslate.md 描述了沉浸式翻译方案的完整使用与排障流程。

5.1 使用前提与操作

首先要接受两个前提：并非所有游戏都支持内嵌；内嵌可能造成游戏卡死。文本选择窗口中，若文本行没有"嵌入"按钮即表示不支持。

操作流程：在文本选择窗口选中支持内嵌的文本项并激活。注意"显示"与"嵌入"是两个独立开关：

• 两者都开：游戏内嵌译文，软件窗口显示更完整的译文；
• 只开嵌入：仅在游戏内显示译文，软件窗口不再显示内容。

5.2 乱码排查：字符集与字体

开始内嵌翻译后最常见的故障是译文显示乱码，文档给出的排查顺序是：

1. 先查字体：英文游戏内嵌中文译文时，多为缺少中文字体所致。此时需开启编辑游戏字体并选择一款能显示中文的字体。
2. 再查字符集：许多经典日式 Galgame 使用内置 Shift-JIS 字符集处理中文，可尝试开启简体转繁体/日文汉字来减少显示错误；而较新引擎（KiriKiri、Renpy、TyranoScript、RPGMakerMV 等）多使用 UTF-8/UTF-16，乱码基本是字体问题而非字符集问题，关闭该转换选项后简体中文即可正确显示；个别无法正确显示简体的游戏则反向尝试开启该选项。

5.3 内嵌设置项

"暂停游戏 → 改写内存 → 恢复显示"这一机制说明内嵌翻译在实现上依赖内存改写，而非截图叠加，这也解释了为何它对引擎兼容性要求极高。

六、HOOK 模拟器：覆盖 NS/PSP/PSV/PS2 主机游戏

docs/vi/emugames.md 通过 include 机制引入 docs/emusupportlist/all.md，给出当前模拟器支持矩阵：

这一能力在仓库 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 / 识别平均准确率 / 语言支持 / 体积）：

从源码看，默认配置确实指向内置模型：defaultconfig/ocrsetting.json中local引擎的默认参数为"model": "PP-OCRv5_mobile"、"thread": 4、"device_type": "CPU"、"gpu": false（ocrsetting.json）。高精度模型（如 v6_medium、v5_server）识别率更高但速度更慢，文档给出两条提速路径：

1. GPU 推理：Win10 之后的软件版本可直接在设置中开启 GPU 运行模型。
2. 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 其他离线 OCR

• SnippingTool：仅支持 Windows 10/11，Windows 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 通用大模型接口参数详解

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-version=2023-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的专用接口。当前支持：

这类模型部署完成后，多数也能直接通过"通用大模型接口"调用；仅在需要专用 prompt 格式时使用专用接口。

九、语言学习：日语分词、假名注音与词典生态

首页将"语言学习"列为独立能力，涉及日语分词注音（qa1.md）、AnkiConnect 与 Yomitan 插件（yomitan.md）三块内容。

9.1 MeCab + UniDic：日语分词的基石

日文分词与假名注音依赖 MeCab 搭配 UniDic 词典，配置有两种路径：

1. 自动下载：在"词典设置 → 资源下载"中，若尚未下载 UniDic 会出现下载按钮，点击即自动下载并配置好路径。
2. 手动配置：自动下载只获取常用版本（unidic-mecab-2.1.2_bin）；想用其他版本可自行下载，解压到软件目录后重启软件自动识别，或解压到任意目录后手动指定路径。

完成分词后，激活显示假名注音（默认开启）与语法高亮，即可在译文中看到逐词的 furigana 标注与高亮。

9.2 源码级实现：mecab.py 的解析链路

分词与注音的核心实现在 myutils/mecab.py：

• MeCab 封装（mecab类，mecab.py）：初始化时依次探测用户配置路径、程序目录、C:\Program Files\MeCab\dic等常见目录寻找词典；解析时调用NativeUtils.mecab原生模块，根据 UniDic 不同版本的特征字段数（26/29/17/9 等）提取读音kana、原型origorig与词性pos1，英文词汇直接以英文形式作为读音。
• 假名显示策略（parseastarget，mecab.py）：由全局配置hira_vis_type控制注音形态——0 为片假名转平假名、1 为平假名转片假名、2 为转罗马音，纯假名词会按需隐藏注音避免冗余。
• Ruby HTML 生成（makerubyhtml，mecab.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 浏览器划词插件接入翻译界面的完整步骤：

1. 确认显示引擎为 Webview2：浏览器插件依赖 Webview2，除系统不支持外默认即为该引擎。
2. 开启"使用浏览器插件"并加载 Yomitan 扩展：务必使用 Chrome/Edge 版本，Firefox 版不兼容。
3. 等待初始化完成后再配置 Yomitan；若插件未被识别，可关闭软件重开一次。
4. 窗口尺寸联动：主窗口默认按文本与译文自动调整高度，这会连带改变 Yomitan 窗口尺寸；若想固定，可在"显示设置 → 界面设置 → 主界面"中取消勾选"自动调整高度"。
5. 历史文本窗口同样支持浏览器插件，但默认关闭以节省资源。

至于 AnkiConnect 卡片同步，仓库在 myutils/template/myanki_v3.py 中提供了 Anki 模板实现，与首页"支持 AnkiConnect"的能力描述相互印证。

十、语音合成：多引擎 TTS

docs/vi/ttsengines.md 梳理了 TTS 引擎接入方式，仓库 tts/ 目录下的引擎文件与之对应（edgetts、gtts、windowstts、voicevox、voiceroid2、gptsovits、bcuttts、huoshantts、chatgpttts、vitsSimpleAPI、selfbuild、tolk 等）。

• Windows TTS：Windows 7 及以上可通过系统语言设置添加对应语言的 SAPI 语音包；Windows 10/11 可使用更自然的 Natural Voice。注意：因微软改变了新版语言包的编码方式，已安装语言包与新版下载语言包可能无法直接使用，需参考官方修复说明处理。Windows 11 还可在"辅助功能 → 讲述人 → 添加自然语音"中增加高质量语音；Windows 10 则可下载 Natural Voice 资源解压到软件目录；部分系统还需额外补装语音运行时。
• VoiceRoid / A.I.VOICE：A.I.VOICE 需从官网下载安装；VoiceRoid 可在软件资源下载中获取，但追加音源必须先装任意一个整合包——整合包内含常用音源与必要运行时，只下载追加音源会缺少 VoiceRoid 运行时。
• VOICEVOX：下载并运行 VOICEVOX 本体即可，默认端口与软件预设一致，两端不改设置的话开箱即用。
• GPT-SoVITS：API 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.py（HOOK）、ocrengines/local.py（内置 OCR）、NativeImpl/LunaHook/LunaHook/emulators（模拟器）；
• 译文本：translator/（翻译引擎目录）、defaultconfig/translatorsetting.json（翻译默认配置）；
• 学文本：myutils/mecab.py（分词注音）、cishu/（词典）、myutils/template/myanki_v3.py（Anki）；
• 听/说文本：tts/（合成）、Windows 语音识别接入（识别）。

对使用者而言，建议的上手顺序是：先按 README 完成下载与杀软白名单配置，再按 basicuse.md 从 HOOK 模式跑通第一句译文，之后根据游戏类型补充 hooksettings.md 的调优参数，最后按需启用内嵌翻译、OCR 模型与大模型翻译接口，逐步搭建出适合自己的完整翻译与学习环境。

【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslator