LunaTranslator 基本用法指南：HOOK 模式、OCR 模式与快捷启动游戏全流程详解-平芜编程栈

LunaTranslator 基本用法指南：HOOK 模式、OCR 模式与快捷启动游戏全流程详解

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

本文是 LunaTranslator（视觉小说翻译器）的基本使用教程，系统讲解三种最常用的文本获取方式：HOOK 模式（注入游戏进程读取文本）、OCR 模式（识别图像文字）以及快捷启动游戏并自动 HOOK的拖拽玩法。阅读完本文，你将掌握从选择进程、注入游戏、筛选文本行到开始翻译的完整操作链路，并能区分 HOOK 与 OCR 各自的适用场景，理解为什么某些游戏会出现"内嵌"翻译按钮而另一些没有。

LunaTranslator 是一款面向视觉小说（Visual Novel）的翻译软件，其核心工作链路是：先获取游戏文本，再调用翻译引擎输出译文。文本获取环节决定了翻译体验的上限，而docs/cht/basicuse.md正是围绕这一环节撰写的入门指南。本文以该文档为骨架，结合仓库源码深入解释每一步操作背后的实现原理。

一、HOOK 模式：注入游戏进程读取文本

HOOK 模式是 LunaTranslator 最常用的文本获取方式，适用于已经启动的游戏进程。其原理是通过注入动态链接库（DLL）到游戏进程中，挂钩（Hook）游戏内部文本输出相关的 API 调用，从而"窃听"游戏渲染文本时的数据流。

1.1 选择游戏进程

打开 LunaTranslator 主界面后，点击工具列中的选择游戏进程按钮，弹出进程选择窗口（AttachProcessDialog），从列表中选取目标游戏的进程即可。

进程选择窗口的实现位于 attachprocessdialog.py：

窗口标题会实时显示当前权限状态：选择进程_当前权限_管理员/非管理员，提示你是否拥有注入所需权限；
如果进程列表中没有看到想附加的进程，窗口内提供了"点击此按钮后点击游戏窗口"的交互按钮，可以直接用鼠标点击游戏窗口来定位其进程（对应selectwindowcallback回调，内部通过mouseselectwindow实现）；
若仍然失败，源码中的提示文案明确建议：尝试使用管理员权限运行本软件。

1.2 确认注入与弹出选择文本窗口

点击确认后，游戏会被添加到软件的游戏列表中，同时注入动作开始执行。此时会自动弹出选择文本窗口（hookselectdialog）；如果之后想再次打开，也可以通过工具列对应按钮随时调出。

从源码看，注入与文本回调的底层接口定义在 texthook.py 中：texthook类在initdll()中加载LunaHost32.dll/LunaHost64.dll（根据目标进程位数自动选择），并通过Luna_ConnectProcess、Luna_InsertHookCode、Luna_FindHooks等原生函数完成进程连接、Hook 代码插入和候选地址搜索。文本数据通过OutputCallback（handle_output）回调回传，这正是"选择文本窗口中出现候选文本行"的数据来源。

关联阅读：HOOK 设置详解（如文本编码、偏移量等高级参数）

1.3 让游戏显示文本并挑选文本行

注入完成后，让游戏运行一下以显示一些文字。此时选择文本界面中会涌现出若干候选文本行——这些来自游戏内部不同线程或不同 API 的输出。你需要从中选中符合游戏文本的那一行，翻译随即开始。

这里有一个常见困惑：为什么会有多个候选？因为一个游戏进程内部往往有多个可能输出文本的调用点（例如日志输出、对话框渲染、系统消息等），HOOK 会尽可能多地捕获它们，再由用户人工筛选出真正对应游戏剧情文本的那一行。选中后，该文本行会随游戏对话推进持续更新并送入翻译管线。

1.4 "内嵌"与"显示"两列按钮的区别

选择文本窗口的每一行候选文本后面，会出现操作按钮列：

若游戏支持内嵌翻译：会出现「内嵌」按钮——即直接把译文渲染进游戏窗口内部（相当于游戏自带汉化/翻译显示效果）；
否则只有「显示」按钮：即译文在 LunaTranslator 自身的翻译界面中显示。

是否支持内嵌，取决于游戏文本渲染引擎是否可被内嵌式挂钩。texthook源码中通过Luna_CheckIsUsingEmbed检测当前文本线程是否已启用内嵌，并使用Luna_UseEmbed、Luna_EmbedCallback实现内嵌文本的注入与回读；在嵌入式渲染接口层面，还有专门的渲染实现（参见 rendertext 目录下的textbrowser.py、webview.py等模块）。若游戏无法安全内嵌，则只提供「显示」模式。

二、OCR 模式：识别图像中的文字

部分游戏无法通过 HOOK 获取文本（例如使用了加密/自绘文本引擎，或 HOOK 点难以定位），此时可以改用OCR 模式，让 LunaTranslator 直接"看图识字"。

2.1 切换到 OCR 模式

在主界面上将文本来源切换为 OCR 模式（sourcestatus2中的ocr文本源），然后框选一个识别区域。之后软件会对该区域进行持续自动识别：只要区域内出现文字变化，就自动截取图像、运行 OCR、识别出文本并翻译。

OCR 文本源的实现位于 ocrtext.py：

区域框选通过rangeadjust（区域调整控件）完成，每个区域对应一个rangemanger实例；
截图与预处理在imageCutEx中完成，若开启了use_ocr_preprocess配置，还会先加载用户自定义的ocr_preprocess.py预处理脚本再送入识别；
识别调用ocr_run执行，具体识别引擎由 ocrengines 目录下的实现提供（本地引擎与云端 API 均可）。

关联阅读：OCR 参数配置、OCR 引擎接入 API

2.2 易错点：临时识别按钮 vs 持续识别按钮

文档特别强调了一个新手极易踩坑的细节：OCR 模式下，后一个默认图标相同的按钮只用于"临时选取并识别一次图像"，而不是自动持续识别。

也就是说，界面上存在两个外观相近的按钮：

按钮	行为	适用场景
OCR 模式按钮	框选区域后持续自动识别并翻译	正常游玩、文字不断更新的场景
临时识别按钮	只框选并识别一次该图像	临时看一句静态文字、菜单说明等

不要用错按钮，否则你会发现游戏剧情推进时翻译文本并不会自动更新。

三、快捷启动游戏并自动 HOOK：拖拽一步到位

前两种方式都要求游戏先启动，而"快捷启动"则把启动与注入合并成一步：启动软件后，将游戏程序（.exe）用鼠标直接拖拽到 LunaTranslator 的窗口中，松开鼠标，游戏就会被自动添加到软件的游戏列表中。

拖拽支持在源码中有多处实现，例如 dialog.py 中的dragEnterEvent/dropEvent（接受含 URL 的拖拽事件并批量添加游戏），以及 v3.py 中对图片素材的拖拽添加。

拖入后发生三件事：

自动添加到游戏列表：通过addgamebatch_x将拖入的路径规范化并加入游戏列表；
自动转区启动：软件会根据游戏所属区域，调用转区工具（Locale Emulator 等）以正确区域设置启动游戏，避免日文游戏在中文系统下出现乱码。该逻辑在 localetools.py 的localeswitchedrun中实现：先通过windows.GetBinaryType判断游戏位数，再依据游戏的launch_method配置选择启动器（Launcher），最终以le_internal（内置 Locale Emulator）等方式拉起进程；
自动 HOOK 游戏：游戏启动后立刻执行注入流程。

随后同样会弹出选择文本窗口，后续操作与 HOOK 模式完全一致：运行游戏显示文本 → 挑选候选文本行 → 开始翻译。

关联阅读：模拟器游戏支持（拖拽方式同样适用于模拟器场景的扩展用法）

四、两种模式的选择建议与实战小结

维度	HOOK 模式	OCR 模式
前置条件	游戏已启动（或拖拽快捷启动）	游戏已启动并可见
文本获取	注入 DLL 挂钩文本 API	截屏 + OCR 识别
文本质量	原始文本，准确无噪声	受字体、背景干扰，可能有识别误差
速度	快（实时回调）	较慢（需截图与识别）
适用场景	绝大多数可注入游戏	无法 HOOK 的加密/自绘引擎游戏