LunaTranslator 网络服务完全指南Web 页面、HTTP API 与 WebSocket 接口详解【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslatorLunaTranslator 内置了一套独立的网络服务允许外部程序浏览器、脚本、第三方应用通过 HTTP 与 WebSocket 与翻译器本体交互从而复用其翻译、查词、OCR、TTS 与日语分词能力。本文以 docs/zh/apiservice.md 为主线结合 tcpservice.py、servicecollection.py 等源码实现完整讲解每个页面与接口的用法、请求/响应格式及底层实现原理。一、网络服务的开启与基础配置网络服务并非默认常开需要通过配置项启用。相关配置集中在globalconfig对应 defaultconfig/config.json关键项如下配置项默认值含义networktcpenablefalse是否启用 TCP 网络服务HTTP/WebSocketnetworktcpport2333服务监听端口network_service_disabled_paths[]需要禁用的路径列表命中即返回 404network1网络服务总开关network_websocket1WebSocket 服务开关服务初始化与启停逻辑位于 LunaTranslator.py应用启动时创建TCPService并调用registerall注册全部路由serviceinit中会先关闭旧服务再判断networktcpenable是否开启若开启则以networktcpport指定的端口调用service.init()。监听地址固定为0.0.0.0见 tcpservice.py即同一局域网内的其他设备也能访问但需要注意该服务没有内置身份认证与访问控制建议仅在可信网络环境开启或通过network_service_disabled_paths按需屏蔽敏感路径。若端口被占用服务会发出端口冲突提示信号而不会崩溃。启用后用浏览器访问http://127.0.0.1:2333/即可打开导航页。下文所有接口默认基于http://127.0.0.1:2333。二、服务端架构与路由机制LunaTranslator 没有依赖外部 Web 框架而是在 tcpservice.py 中用 Python 标准库socket自行实现了 HTTP/1.1 与 WebSocket 协议的解析和响应RequestInfo解析请求行与请求头把 URL 拆分为path和query查询参数经parse_qsl转为字典若存在Content-Length会读取请求体为RequestBody并可通过.json属性直接获得 JSON 对象。ResponseInfo统一构造响应。传入str自动按text/html; charsetutf-8输出传入dict/list/tuple自动序列化为application/json传入生成器则按text/event-stream以 SSE 格式逐条推送同时支持FileResponse流式发送本地 HTML 文件、RedirectResponse302 跳转与自定义头。所有响应都带Access-Control-Allow-Origin: *方便浏览器端跨域调用。路由注册servicecollection.py末尾的registerall()将全部处理器注册进TCPService.handlers。请求到来时服务根据是否为 WebSocket 升级请求筛选对应的HTTPHandler/WSHandler再按path精确匹配未匹配或命中禁用列表一律返回 404见 tcpservice.py。并发模型listen与handle_client均通过threader装饰器在线程中运行即每个连接由独立线程处理避免阻塞主界面与翻译流程。HTML 页面资源统一存放在 src/LunaTranslator/htmlcode/service/ 目录index.html、dictionary.html、manyinone.html、ocr.html、translate.html、tts.htmlFileResponse会按文件名推断 MIME 类型后流式发送。三、Web 页面接口网络服务提供 7 个可直接在浏览器访问的页面全部为 GET 请求路径页面内容说明/导航页所有功能的入口索引对应index.html/page/mainui主界面同步页与主窗口显示的文本内容实时同步/page/transhist历史文本同步页与历史文本窗口内容实时同步/page/dictionary查词页面在/page/mainui中点击单词查词时会唤出该页面/page/manyinone三合一整合页整合 mainui/transhist/dictionary 三个页面在其 mainui 子区域点词查词时不会新开查词窗口而是在当前页的 dictionary 子区域内就地显示结果/page/translate翻译界面独立的翻译输入界面对应translate.html/page/ocrOCR 界面图像识别界面对应ocr.html/page/ttsTTS 界面语音合成界面对应tts.html其中/page/mainui与/page/transhist由渲染组件动态加载分别对应TextBrowser.loadex_()与wvtranshist.loadex_()页面通过内部 WebSocket/__internalservice/mainuiws、/__internalservice/transhistws与翻译器本体通信从而与桌面窗口保持内容同步。/page/dictionary还支持查询参数携带word参数访问时会直接执行该词的查询servicecollection.py的PageSearchWord会解析WordSegResult必要时对原形prototype做 302 重定向规范化参数。四、HTTP API 接口所有 API 返回 JSON 或 SSE 流便于脚本与第三方程序调用。下面是逐接口说明含源码实现细节。1./api/translate— 文本翻译方法GET必填参数text待翻译文本可选参数id翻译器 ID可在/api/list/translator中查询不指定id时走翻译器自动选择逻辑即最快的翻译接口由 LunaTranslator 按当前配置的翻译器排序自动挑选可用引擎指定id时强制使用该翻译器源码中waitforresultcallbackengine_forceTrue。成功时返回{id: 翻译器ID, name: 翻译器名称, result: 翻译结果}翻译失败时返回{error: 错误信息}若错误源于指定翻译器还会附带id与name。底层调用链为APITranslate.parse→gobject.base.textgetmethod(...)它通过waitforresultcallback回调 threading.Event让 HTTP 请求线程同步等待翻译结果返回见 LunaTranslator.py 与 servicecollection.py。注意此调用is_auto_runFalse不会触发原文去重过滤等自动运行逻辑。命令行示例# 自动选择最快翻译器 curl http://127.0.0.1:2333/api/translate?text%E4%BD%A0%E5%A5%BD # 指定翻译器id 见 /api/list/translator curl http://127.0.0.1:2333/api/translate?texthelloidbaiduapi2./api/dictionary— 词典查询方法GET必填参数word要查询的词可选参数id词典 ID指定id时只查询该词典返回单个 JSON 对象包含词典 IDid、词典名称name与 HTML 内容result查询失败词典不存在或查无结果时返回空对象{}。不指定id时查询所有可用词典响应类型为text/event-streamSSE每个 event 是一个 JSON 对象同样包含id、name、result逐条推送形如data: {id: 词典ID1, name: 词典名1, result: b释义HTML/b} data: {id: 词典ID2, name: 词典名2, result: b释义HTML/b}实现上APISearchWord会遍历gobject.base.cishus中全部词典对每个词典调用safesearch异步查询并用threading.Semaphore收集所有结果后再以生成器逐条yield见 servicecollection.py生成器类型的响应体会被ResponseInfo识别并转换为 SSE 流。result为 HTML 片段可直接嵌入页面展示。# 查询单个词典 curl http://127.0.0.1:2333/api/dictionary?word%E9%9B%A8idmojidict # 查询所有词典SSE 流 curl -N http://127.0.0.1:2333/api/dictionary?word%E9%9B%A83./api/mecab— 日语分词与注音方法GET必填参数text返回 Mecab 对text的解析结果JSON 数组每个元素为分词单元的结构化字典。底层调用gobject.base.parsehira(text)见 LunaTranslator.py该函数按当前源语言分派日语Auto或Japanese走 Mecab 分词产出含读音、词性等信息的词条中文走结巴分词 拼音jiebapinyin英文及其他走 spaCy可用时或拉丁语兜底解析器。只有当你开启假名注音、分词显示或点击词查词功能时isshowhira/show_fenci等解析结果才非空。该接口常用于外部程序获取日文句子的假名注音。curl http://127.0.0.1:2333/api/mecab?text%E4%BB%8A%E6%97%A5%E3%81%AF%E6%99%B4%E3%82%8C4./api/tts— 语音合成方法GET必填参数text返回音频二进制数据Content-Type与Content-Length由 TTS 引擎结果决定合成失败时返回{error: 错误信息}。实现上APItts.parse调用gobject.base.reader.ttscallback(text, callback)触发当前选中的 TTS 引擎合成并用threading.Event同步等待结果最终以ResponseWithHeader原样输出音频字节见 servicecollection.py。# 直接保存音频 curl -o audio.mp3 http://127.0.0.1:2333/api/tts?texthello5./api/ocr— 图像文字识别方法POST请求体JSON含image字段值为base64 编码的图像数据服务端对 base64 解码后用QImage.loadFromData还原图像校验成功后调用ocr_run()来自 myutils/ocrutil.py执行当前配置的 OCR 引擎返回其结构化 JSON 结果通常含识别文本与坐标信息。图像解码失败或image字段缺失会返回 404。curl -X POST http://127.0.0.1:2333/api/ocr \ -H Content-Type: application/json \ -d {image: base64编码的图像数据}6./api/list/translator与/api/list/dictionary— 枚举可用引擎两个接口分别列出当前可用的翻译器和词典均为 GET、无需参数返回形如[{id: ..., name: ...}]的 JSON 数组。/api/list/translator按fix_translate_rank_rank翻译器排序过滤出已实例化的翻译器id可直接用于/api/translate?id.../api/list/dictionary按cishuvisrank词典显示排序过滤出已加载的词典id可直接用于/api/dictionary?word...id...。name为本地化显示名通过_TR()动态翻译见 servicecollection.py。curl http://127.0.0.1:2333/api/list/translator curl http://127.0.0.1:2333/api/list/dictionary7./api/textinput— 外部文本输入方法GET必填参数text相当于把文本投递给翻译器主流程处理一次内部调用textgetmethod(text, is_auto_runFalse)见 servicecollection.py让文本经过预处理、翻译、输出等完整链路就像用户在输入框手动提交一样。适合从外部程序如剪贴板工具、脚本把文本送入翻译器。curl http://127.0.0.1:2333/api/textinput?text%E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF五、WebSocket 服务网络服务还提供两个 WebSocket 推送接口用于持续、实时地接收翻译器产生的文本流。连接建立后服务端会不断推送消息无需轮询。路径推送内容/api/ws/text/origin所有提取到的原文文本/api/ws/text/trans所有翻译结果实现上两个处理器在建立连接时把自身加入全局连接列表wsoutputsave见 servicecollection_1.py之后通过WSForEach遍历列表向所有客户端广播文本。WSHandler完整实现了 WebSocket 协议基于Sec-WebSocket-Key 固定 GUID 计算握手响应、解析含掩码与扩展长度的数据帧、处理文本帧/关闭帧/Ping-Pong 心跳见 tcpservice.py因此可被任意标准 WebSocket 客户端浏览器WebSocketAPI、websocat等直接连接。浏览器端最小示例const ws new WebSocket(ws://127.0.0.1:2333/api/ws/text/origin); ws.onmessage (e) console.log(原文, e.data);六、实践建议与注意事项端口确认默认 2333可在配置中修改networktcpport若修改请同步更新外部脚本的 URL。安全边界服务绑定0.0.0.0且无鉴权局域网内任何设备均可调用翻译/查词/OCR/TTS 与推送文本接口。仅在可信网络使用或通过network_service_disabled_paths禁用不希望的路径。同步阻塞语义/api/translate、/api/dictionary指定 id 时、/api/tts都会用事件对象阻塞等待内部异步流程完成翻译耗时取决于所选引擎/api/dictionary未指定 id 时则以 SSE 流式返回各词典结果可边收边展示。页面联动/page/mainui与/page/dictionary或/page/manyinone的对应子区域联动点词查词无需新开窗口适合作为自定义 UI 或网页挂件集成。文本编码查询参数中的非 ASCII 文本需 URL 编码如curl --data-urlencode或 JSencodeURIComponentOCR 的image字段必须是 base64 字符串。上述接口与页面共同构成 LunaTranslator 的开放能力层无论是写一个手机端遥控翻译的脚本还是搭建自定义查词 Web 页面都可以直接复用翻译器已配置好的引擎与数据。完整的注册清单可查阅 servicecollection.py 中的registerall函数。【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LunaTranslator 网络服务完全指南：Web 页面、HTTP API 与 WebSocket 接口详解
LunaTranslator 网络服务完全指南Web 页面、HTTP API 与 WebSocket 接口详解【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslatorLunaTranslator 内置了一套独立的网络服务允许外部程序浏览器、脚本、第三方应用通过 HTTP 与 WebSocket 与翻译器本体交互从而复用其翻译、查词、OCR、TTS 与日语分词能力。本文以 docs/zh/apiservice.md 为主线结合 tcpservice.py、servicecollection.py 等源码实现完整讲解每个页面与接口的用法、请求/响应格式及底层实现原理。一、网络服务的开启与基础配置网络服务并非默认常开需要通过配置项启用。相关配置集中在globalconfig对应 defaultconfig/config.json关键项如下配置项默认值含义networktcpenablefalse是否启用 TCP 网络服务HTTP/WebSocketnetworktcpport2333服务监听端口network_service_disabled_paths[]需要禁用的路径列表命中即返回 404network1网络服务总开关network_websocket1WebSocket 服务开关服务初始化与启停逻辑位于 LunaTranslator.py应用启动时创建TCPService并调用registerall注册全部路由serviceinit中会先关闭旧服务再判断networktcpenable是否开启若开启则以networktcpport指定的端口调用service.init()。监听地址固定为0.0.0.0见 tcpservice.py即同一局域网内的其他设备也能访问但需要注意该服务没有内置身份认证与访问控制建议仅在可信网络环境开启或通过network_service_disabled_paths按需屏蔽敏感路径。若端口被占用服务会发出端口冲突提示信号而不会崩溃。启用后用浏览器访问http://127.0.0.1:2333/即可打开导航页。下文所有接口默认基于http://127.0.0.1:2333。二、服务端架构与路由机制LunaTranslator 没有依赖外部 Web 框架而是在 tcpservice.py 中用 Python 标准库socket自行实现了 HTTP/1.1 与 WebSocket 协议的解析和响应RequestInfo解析请求行与请求头把 URL 拆分为path和query查询参数经parse_qsl转为字典若存在Content-Length会读取请求体为RequestBody并可通过.json属性直接获得 JSON 对象。ResponseInfo统一构造响应。传入str自动按text/html; charsetutf-8输出传入dict/list/tuple自动序列化为application/json传入生成器则按text/event-stream以 SSE 格式逐条推送同时支持FileResponse流式发送本地 HTML 文件、RedirectResponse302 跳转与自定义头。所有响应都带Access-Control-Allow-Origin: *方便浏览器端跨域调用。路由注册servicecollection.py末尾的registerall()将全部处理器注册进TCPService.handlers。请求到来时服务根据是否为 WebSocket 升级请求筛选对应的HTTPHandler/WSHandler再按path精确匹配未匹配或命中禁用列表一律返回 404见 tcpservice.py。并发模型listen与handle_client均通过threader装饰器在线程中运行即每个连接由独立线程处理避免阻塞主界面与翻译流程。HTML 页面资源统一存放在 src/LunaTranslator/htmlcode/service/ 目录index.html、dictionary.html、manyinone.html、ocr.html、translate.html、tts.htmlFileResponse会按文件名推断 MIME 类型后流式发送。三、Web 页面接口网络服务提供 7 个可直接在浏览器访问的页面全部为 GET 请求路径页面内容说明/导航页所有功能的入口索引对应index.html/page/mainui主界面同步页与主窗口显示的文本内容实时同步/page/transhist历史文本同步页与历史文本窗口内容实时同步/page/dictionary查词页面在/page/mainui中点击单词查词时会唤出该页面/page/manyinone三合一整合页整合 mainui/transhist/dictionary 三个页面在其 mainui 子区域点词查词时不会新开查词窗口而是在当前页的 dictionary 子区域内就地显示结果/page/translate翻译界面独立的翻译输入界面对应translate.html/page/ocrOCR 界面图像识别界面对应ocr.html/page/ttsTTS 界面语音合成界面对应tts.html其中/page/mainui与/page/transhist由渲染组件动态加载分别对应TextBrowser.loadex_()与wvtranshist.loadex_()页面通过内部 WebSocket/__internalservice/mainuiws、/__internalservice/transhistws与翻译器本体通信从而与桌面窗口保持内容同步。/page/dictionary还支持查询参数携带word参数访问时会直接执行该词的查询servicecollection.py的PageSearchWord会解析WordSegResult必要时对原形prototype做 302 重定向规范化参数。四、HTTP API 接口所有 API 返回 JSON 或 SSE 流便于脚本与第三方程序调用。下面是逐接口说明含源码实现细节。1./api/translate— 文本翻译方法GET必填参数text待翻译文本可选参数id翻译器 ID可在/api/list/translator中查询不指定id时走翻译器自动选择逻辑即最快的翻译接口由 LunaTranslator 按当前配置的翻译器排序自动挑选可用引擎指定id时强制使用该翻译器源码中waitforresultcallbackengine_forceTrue。成功时返回{id: 翻译器ID, name: 翻译器名称, result: 翻译结果}翻译失败时返回{error: 错误信息}若错误源于指定翻译器还会附带id与name。底层调用链为APITranslate.parse→gobject.base.textgetmethod(...)它通过waitforresultcallback回调 threading.Event让 HTTP 请求线程同步等待翻译结果返回见 LunaTranslator.py 与 servicecollection.py。注意此调用is_auto_runFalse不会触发原文去重过滤等自动运行逻辑。命令行示例# 自动选择最快翻译器 curl http://127.0.0.1:2333/api/translate?text%E4%BD%A0%E5%A5%BD # 指定翻译器id 见 /api/list/translator curl http://127.0.0.1:2333/api/translate?texthelloidbaiduapi2./api/dictionary— 词典查询方法GET必填参数word要查询的词可选参数id词典 ID指定id时只查询该词典返回单个 JSON 对象包含词典 IDid、词典名称name与 HTML 内容result查询失败词典不存在或查无结果时返回空对象{}。不指定id时查询所有可用词典响应类型为text/event-streamSSE每个 event 是一个 JSON 对象同样包含id、name、result逐条推送形如data: {id: 词典ID1, name: 词典名1, result: b释义HTML/b} data: {id: 词典ID2, name: 词典名2, result: b释义HTML/b}实现上APISearchWord会遍历gobject.base.cishus中全部词典对每个词典调用safesearch异步查询并用threading.Semaphore收集所有结果后再以生成器逐条yield见 servicecollection.py生成器类型的响应体会被ResponseInfo识别并转换为 SSE 流。result为 HTML 片段可直接嵌入页面展示。# 查询单个词典 curl http://127.0.0.1:2333/api/dictionary?word%E9%9B%A8idmojidict # 查询所有词典SSE 流 curl -N http://127.0.0.1:2333/api/dictionary?word%E9%9B%A83./api/mecab— 日语分词与注音方法GET必填参数text返回 Mecab 对text的解析结果JSON 数组每个元素为分词单元的结构化字典。底层调用gobject.base.parsehira(text)见 LunaTranslator.py该函数按当前源语言分派日语Auto或Japanese走 Mecab 分词产出含读音、词性等信息的词条中文走结巴分词 拼音jiebapinyin英文及其他走 spaCy可用时或拉丁语兜底解析器。只有当你开启假名注音、分词显示或点击词查词功能时isshowhira/show_fenci等解析结果才非空。该接口常用于外部程序获取日文句子的假名注音。curl http://127.0.0.1:2333/api/mecab?text%E4%BB%8A%E6%97%A5%E3%81%AF%E6%99%B4%E3%82%8C4./api/tts— 语音合成方法GET必填参数text返回音频二进制数据Content-Type与Content-Length由 TTS 引擎结果决定合成失败时返回{error: 错误信息}。实现上APItts.parse调用gobject.base.reader.ttscallback(text, callback)触发当前选中的 TTS 引擎合成并用threading.Event同步等待结果最终以ResponseWithHeader原样输出音频字节见 servicecollection.py。# 直接保存音频 curl -o audio.mp3 http://127.0.0.1:2333/api/tts?texthello5./api/ocr— 图像文字识别方法POST请求体JSON含image字段值为base64 编码的图像数据服务端对 base64 解码后用QImage.loadFromData还原图像校验成功后调用ocr_run()来自 myutils/ocrutil.py执行当前配置的 OCR 引擎返回其结构化 JSON 结果通常含识别文本与坐标信息。图像解码失败或image字段缺失会返回 404。curl -X POST http://127.0.0.1:2333/api/ocr \ -H Content-Type: application/json \ -d {image: base64编码的图像数据}6./api/list/translator与/api/list/dictionary— 枚举可用引擎两个接口分别列出当前可用的翻译器和词典均为 GET、无需参数返回形如[{id: ..., name: ...}]的 JSON 数组。/api/list/translator按fix_translate_rank_rank翻译器排序过滤出已实例化的翻译器id可直接用于/api/translate?id.../api/list/dictionary按cishuvisrank词典显示排序过滤出已加载的词典id可直接用于/api/dictionary?word...id...。name为本地化显示名通过_TR()动态翻译见 servicecollection.py。curl http://127.0.0.1:2333/api/list/translator curl http://127.0.0.1:2333/api/list/dictionary7./api/textinput— 外部文本输入方法GET必填参数text相当于把文本投递给翻译器主流程处理一次内部调用textgetmethod(text, is_auto_runFalse)见 servicecollection.py让文本经过预处理、翻译、输出等完整链路就像用户在输入框手动提交一样。适合从外部程序如剪贴板工具、脚本把文本送入翻译器。curl http://127.0.0.1:2333/api/textinput?text%E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF五、WebSocket 服务网络服务还提供两个 WebSocket 推送接口用于持续、实时地接收翻译器产生的文本流。连接建立后服务端会不断推送消息无需轮询。路径推送内容/api/ws/text/origin所有提取到的原文文本/api/ws/text/trans所有翻译结果实现上两个处理器在建立连接时把自身加入全局连接列表wsoutputsave见 servicecollection_1.py之后通过WSForEach遍历列表向所有客户端广播文本。WSHandler完整实现了 WebSocket 协议基于Sec-WebSocket-Key 固定 GUID 计算握手响应、解析含掩码与扩展长度的数据帧、处理文本帧/关闭帧/Ping-Pong 心跳见 tcpservice.py因此可被任意标准 WebSocket 客户端浏览器WebSocketAPI、websocat等直接连接。浏览器端最小示例const ws new WebSocket(ws://127.0.0.1:2333/api/ws/text/origin); ws.onmessage (e) console.log(原文, e.data);六、实践建议与注意事项端口确认默认 2333可在配置中修改networktcpport若修改请同步更新外部脚本的 URL。安全边界服务绑定0.0.0.0且无鉴权局域网内任何设备均可调用翻译/查词/OCR/TTS 与推送文本接口。仅在可信网络使用或通过network_service_disabled_paths禁用不希望的路径。同步阻塞语义/api/translate、/api/dictionary指定 id 时、/api/tts都会用事件对象阻塞等待内部异步流程完成翻译耗时取决于所选引擎/api/dictionary未指定 id 时则以 SSE 流式返回各词典结果可边收边展示。页面联动/page/mainui与/page/dictionary或/page/manyinone的对应子区域联动点词查词无需新开窗口适合作为自定义 UI 或网页挂件集成。文本编码查询参数中的非 ASCII 文本需 URL 编码如curl --data-urlencode或 JSencodeURIComponentOCR 的image字段必须是 base64 字符串。上述接口与页面共同构成 LunaTranslator 的开放能力层无论是写一个手机端遥控翻译的脚本还是搭建自定义查词 Web 页面都可以直接复用翻译器已配置好的引擎与数据。完整的注册清单可查阅 servicecollection.py 中的registerall函数。【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考