企业官网建设流程全解析

LunaTranslator 内置查词工具完全指南：Mecab 分词、辞书激活与触发显示配置

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

本篇指南基于 LunaTranslator（视觉小说翻译器）的内置查词（辞书）功能展开，系统讲解从安装 Mecab 分词器、激活在线/离线辞书，到配置「鼠标悬停/点击」触发方式、按键修饰条件，以及「小窗口/完整窗口」两种查词结果展示形态的完整链路。读完本文，你将能够独立配置出一套随点随查、多辞书聚合的内置查词环境，并理解其底层实现机制。

一、内置查词工具能做什么

LunaTranslator 的「内置查词工具」是挂在原文显示（原文/注音分词区域）上的一层交互能力：当程序通过分词器把原文切成一个个单词后，你可以用鼠标悬停或点击任意单词，即可触发辞书查询，结果以悬浮小窗或独立大窗呈现。

从源码结构看，这整套能力由三块构成：

• 分词层：myutils/mecab.py 负责日语（及英语、中文拼音）的分词与假名注音，产出WordSegResult词条序列；
• 辞书层：cishu/ 目录下的各辞书实现（如mdict、mojidict、youdao等）负责针对单词返回释义 HTML；
• 交互层：LunaTranslator.py 的clickwordcallback与 gui/rendertext/texttype.py 的dataget负责把鼠标动作映射为「查词 / 复制 / 显示详情」等行为。

二、前置条件：安装 Mecab 分词工具

官方使用步骤的第一步是安装好 Mecab 分词工具，这一步是日语分词与假名注音（以及后续查词按词触发）的基础。

2.1 Mecab 在项目中的角色

从 myutils/mecab.py 可以看到mecab类通过NativeUtils.mecab（C++ 侧封装）调用 MeCab 词典，对文本逐行分词，并从 MeCab 输出的特征字段中提取：

• kana：读音（假名/罗马音）；
• prototype（原型）：词的词典形；
• wordclass（词性）：如名词、动词；
• info：完整的特征字段列表。

parse_singleline还会把标点、空白单独切分为isdeli=True的边界词，保证分词结果与原文逐字可对齐。

2.2 配置 Mecab 词典路径

在「设置 → 辞书 → 分词器」面板中可配置 Mecab 的参数（gui/setting/cishu.py 的fenciqisettings）。其默认配置项定义在 defaultconfig/config.json：

"hirasetting": { "mecab": { "args": { "path": "" }, "argstype": { "path": { "type": "file", "name": "unidic_路径", "dir": true } } } }

即path是一个目录型参数（dir: true），指向 unidic（UniDic 词典）所在目录。初始化时mecab.init()会依次尝试配置路径、当前目录以及默认安装位置（如C:\Program Files\MeCab\dic、C:\Program Files (x86)\MeCab\dic），并递归遍历目录寻找可用词典，找不到则抛出not find异常。

此外，分词器设置区域还提供了「资源下载」按钮，可直接在软件内获取 MeCab 相关资源，无需手动跳转外部站点。

三、在辞书设置中激活辞书

3.1 设置界面入口

「辞书」设置页（gui/setting/cishu.py 的setTabcishu_l）划分为两个区块：

• 离线：MDict 辞书（mdictsettings），提供启用开关、参数配置与「资源下载」按钮；
• 在线：动态网格列出全部在线辞书，每个辞书行包含名称（可点击重命名）、启用开关与参数按钮。

页头还提供「社区辞书」按钮（_opencommunitycishu），可打开社区辞书对话框安装更多辞书。

3.2 内置辞书种类

仓库 cishu/ 目录内置了多类辞书实现，例如：

• MDict（离线）：mdict.py，读取本地.mdx/.mdd词典文件；
• 在线辞书：Moji辞书（mojidict.py）、有道词典（youdao.py）、Jisho（jisho.py）、jpdb（jpdb.py）、日本国語辞典（japandict.py）、Weblio（weblio.py）等；
• 自定义：selfbuild.py支持编写自己的查词脚本（模板见 myutils/template/selfbuild_cishu.py）。

从默认配置（defaultconfig/config.json）看，Moji辞书默认启用且限定"langs": ["ja"]，有道词典默认启用——langs字段（对应 cishubase.py 的support_langs属性）用于限制该辞书参与的语言查询。

3.3 辞书的查询与缓存机制

所有辞书继承自 cishu/cishubase.py 的cishubase：

• search(word[, sentence])：核心查询方法，返回释义 HTML 字符串；
• safesearch：线程化包装（@threader），内部先检查 32 条 LRU 缓存，命中则直接回调结果，否则调用multiapikeywrapper执行查询并写入缓存；
• result_cache_key：以(word, sentence, rawconfig)作为缓存键，保证配置变化后缓存自动失效。

3.4 MDict 离线辞书深入

MDict 是唯一的离线辞书选项，源码实现相当完整（cishu/mdict.py）：

• 索引构建：IndexBuilder用 sqlite3 为.mdx词条建立MDX_INDEX索引表（含文件偏移、压缩/解压大小等），并在词典文件大小/修改时间变化时自动重建；
• 模糊查询：querycomplex支持精确前缀查询与基于编辑距离的模糊匹配（NativeUtils.distance），可配置每本词典的distance（-1 表示跟随全局值）与最大返回数max_num；
• 辅助资源：.mdd内的图片、CSS、字体、音频会被解析为 base64 内联或缓存文件，音频通过sound://协议转成可播放数据；
• 跳转链接：@@@LINK=条目会被递归解析，日语叠字符号（々、ゝ、ヽ、〱）在正常查询无结果时会自动展开后重查；
• 样式呈现：stylehv控制多本词典结果的排版——0为标签页切换式（generatehtml_tabswitch），1为手风琴折叠式（generatehtml_flow）；每本词典还有priority（越大越靠前）、title（自定义显示名）、FoldFlow（折叠式下默认折叠）等私有配置，并持久化到mdict_config.json；
• CSS 隔离：通过parse_stylesheet（cishubase.py）把词典自带 CSS 的作用域限定到每次查询生成的唯一divclass内，避免辞书样式污染主界面。

四、选择触发查词的方法

在「设置 → 辞书 → 分词 → 触发功能」下可分别配置各行为的触发方式。官方文档强调了两点：鼠标悬停时是鼠标停在单词上即触发，点击单词时是鼠标点击才触发；两种触发方式均可叠加「需要键盘按下」的修饰条件。

4.1 触发方式选项

从 gui/setting/cishu.py 的manysettings看，触发方式下拉框可选：

其中「查词」（完整窗口）与「查词_在小窗口中」两组配置的函数签名分别为：

• 查词：usesearchword+searchword_mousetrigger（默认开启，默认left）；
• 查词_在小窗口中：usesearchword_S+searchword_S_mousetrigger（默认关闭，默认left）。

4.2 需要键盘按下：按键修饰条件

「需要键盘按下」开关对应配置wordclickkbtriggerneed，具体按键序列记录在wordclickkbtrigger中。设置界面用KeySequenceEdit录入组合键（仅允许修饰键）。

运行时，LunaTranslator.py 的checkkeypresssatisfy完成判定：

1. 若该行为未开启「需要键盘按下」，返回-1（表示不要求按键，直接触发）；
2. 否则解析按键序列为修饰键 + 虚拟键码（parsekeystringtomodvkcode）；
3. 通过windows.GetAsyncKeyState实时检测这些键是否处于按下状态，全部按下返回True。

4.3 点击分发逻辑

clickwordcallback（LunaTranslator.py）统一分发searchword、searchword_S、copyword三类行为：

• 先检查对应行为的总开关（如usesearchword）；
• 再比对实际鼠标动作which与该行为的触发设置：不匹配时，若当前设置为left而实际是right，则视为「追加模式」（把新词追加到上一次结果后）；
• 然后调用checkkeypresssatisfy过滤出「已满足按键」或「无需按键」的行为子集并依次执行。

此外，「使用单词原型」开关（配置usewordoriginfor）可让查询词使用分词器给出的原型形（如动词原形）而非屏幕上显示的活用形，配合查词命中率更高。

五、查词结果的展示：小窗口与完整窗口

官方文档特别说明：在小窗口中的查词结果将在较小的悬浮窗口中展现，否则使用较大的完整窗口。两者可以同时启用、各自独立配置触发方式，互不干扰。

5.1 完整窗口查词

usesearchword开启后，触发查词会调用searchwordW（主查词窗口）。结果以标签页/折叠列表形式聚合展示多本辞书的内容，顶部可切换「辞书显示顺序」（配置cishuvisrank）与「不使用的辞书」过滤（ignoredict_S_click）。

5.2 小窗口查词

usesearchword_S开启后，触发查词会调用悬浮小窗WordViewTooltip（gui/flowsearchword.py）：

• 悬停模式：当searchword_S_mousetrigger设为hover时，鼠标悬停会先启动一个 50ms 的定时器（__detectkey），配合checkkeypresssatisfy检查按键条件，满足后才真正弹出结果——避免悬停误触；
• 点击模式：按left/right/mid点击触发；
• 跟随手势：按住设定按键时，小窗会跟随鼠标位置移动（moveresult_1）；
• 样式定制：小窗支持边距、圆角（可跟随系统圆角）、Acrylic/Aero 窗口特效、背景色与内容背景色（均为半透明 ARGB），并支持「鼠标离开时关闭」「失去焦点时关闭」；
• 附加能力：小窗内可直接播放 TTS 语音（is_search_word_auto_tts_2可设为自动朗读）、跳转到完整查词窗口、一键发送 Anki；
• 辞书过滤：悬停模式可用独立的「不使用的辞书」列表（ignoredict_S_hover），防止小窗信息过载。

5.3 悬停详情提示

除查词外，还有独立的「显示详细信息」行为（word_hover_show_word_info），它使用更轻量的 tooltip 样式（gui/rendertext/tooltipswidget.py）展示该词的原型、读音、词性信息（createtipstext），支持边距、圆角、窗口特效、背景与文字颜色配置——适合只想知道读音与词性的轻量场景，与完整查词互为补充。

5.4 分词、注音与查词的可点击性

原文区域是否「可点击/可悬停」由 texttype.py 的_clickable/_clickhovershow属性统一决定：只要「查词」「小窗口查词」「复制」「显示详情」任一行为启用，原文文本即进入可交互状态，并叠加「语法加亮」（show_fenci，默认开启）以视觉区分词边界。

六、与查词配套的注音与分词设置

查词以分词为基础，以下设置直接影响查词体验：

• 日语注音方案（hira_vis_type）：平假名 / 片假名 / 罗马音三选一，实现在 myutils/mecab.py 的parseastarget（含全角片假名→平假名映射与罗马音查表）；
• 注音显示开关（isshowhira）与注音颜色（jiamingcolor）；
• 注音字号：kanarate（相对字号，默认 0.5）及独立字体/加粗/倾斜设置（gui/setting/cishu.py的fontsettings）；
• 词性颜色：multicolorset可逐词性设置是否显示与颜色（默认不透明度 30%）；
• 分词器选择：除 Mecab 外还内置英文latin分词、中文jiebapinyin（结巴 + 拼音）、spacy_wrapper等实现，均位于 myutils/mecab.py。

七、常见问题排查（结合源码）

• Mecab 报not find：path未指向含 unidic 词典的目录，或目录结构不完整；确认在「分词器 → Mecab → 参数」中正确选择词典目录，并可用「资源下载」补充。
• 点击/悬停无反应：检查「触发功能」中对应行为的总开关（如usesearchword）是否打开、触发方式是否与鼠标动作一致；若设置了「需要键盘按下」，请确认按键是否被正确按住（该条件使用全局按键状态检测，不要求窗口焦点）。
• MDict 查不到词：确认.mdx词典已放入配置的paths目录且索引成功构建；可尝试调整该词典的distance（模糊匹配距离）与max_num；@@@LINK与叠字符号会自动处理，无需手动干预。
• 辞书样式错乱：项目已通过动态divclass对辞书 CSS 做作用域隔离；若第三方词典样式仍异常，可尝试切换该词典的展示样式（标签页/折叠）。

八、总结

内置查词工具是 LunaTranslator「原文分词 → 辞书聚合 → 交互展示」链条的完整闭环：以 Mecab（含 unidic）为分词底座，以离线 MDict 与多款在线辞书为数据来源，以「点击/悬停 + 可选按键修饰」为触发手段，以「完整窗口 / 悬浮小窗 / 轻量 tooltip」三种形态承载结果。用户只需依次完成：安装 Mecab → 激活辞书 → 选择触发方式 → 按需打开小窗口模式，即可获得随点随查的日文（及多语言）查词体验。

更多关联阅读：基本使用、注音与分词 FAQ、查词 API 接入、自建辞书脚本模板。

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