LunaTranslator 网络服务与 API 接口完全指南Web 页面、HTTP 接口与 WebSocket 输出【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslator导读LunaTranslator视觉小说翻译器内置了一套自研的轻量级 HTTP/WebSocket 网络服务允许开发者在浏览器中远程查看翻译界面、调用翻译/OCR/TTS/词典查询等核心能力。本文基于 docs/vi/apiservice.md英文版参见 docs/en/apiservice.md、中文版参见 docs/zh/apiservice.md并结合 network/server/servicecollection.py、network/server/tcpservice.py 等源码实现系统讲解服务如何开启、每个 Web 页面与 API 端点的作用、请求/响应格式以及 WebSocket 实时数据流的使用方式。读完本文你将能独立在浏览器或脚本中接入 LunaTranslator 的翻译、查词、OCR、TTS 与实时文本输出能力。1. 服务的开启与基本配置1.1 在哪里开启网络服务默认是关闭的需要在设置界面中手动开启。相关配置项位于“设置 → 文本输入”区域源码见 gui/setting/textinput.py开启networktcpenable一个开关默认值为False打开后回调gobject.base.serviceinit()启动服务端口号networktcpport数值输入框取值范围0~65535默认端口为2333修改后同样会触发服务重启。设置界面还提供一个“打开”按钮直接用默认浏览器访问http://127.0.0.1:{端口}。1.2 服务启动的源码链路服务启动逻辑位于 LunaTranslator.pythreader def serviceinit(self): gobject.base.portconflict.emit() self.service.stop() if globalconfig.get(networktcpenable, False): try: self.service.init(globalconfig.get(networktcpport, 2333)) except OSError: gobject.base.portconflict.emit(端口冲突)关键点服务实例在应用初始化时创建并一次性注册所有路由registerall(self.service)见 LunaTranslator.py监听地址为0.0.0.0见 tcpservice.py即局域网内其他设备也可访问不只是本机127.0.0.1端口被占用时会抛出OSError并在界面上提示“端口冲突”可通过globalconfig[network_service_disabled_paths]默认空列表见 defaultconfig/config.json屏蔽指定路径——命中该列表的请求会被直接返回 404见 tcpservice.py。1.3 路由注册一览所有端点在 servicecollection.py 的registerall()中统一注册完整清单如下类型路径处理类Web 页面/、/page/mainui、/page/transhist、/page/dictionary、/page/manyinone、/page/translate、/page/ocr、/page/ttsPageIndex、PageMainui、Pagetranshist、PageSearchWord、PageManyInOne、Pagetranslate、Pageocr、PagettsHTTP API/api/translate、/api/dictionary、/api/mecab、/api/tts、/api/ocr、/api/list/dictionary、/api/list/translator、/api/textinputAPITranslate、APISearchWord、APImecab、APItts、APIocr、APIdicts、APITranslators、TextInputWebSocket/api/ws/text/origin、/api/ws/text/transTextOutputOrigin、TextOutputTrans内部 WebSocket/__internalservice/mainuiws、/__internalservice/transhistwsinternalservicemainuiws、internalservicetranshistws1.4 底层协议实现特点这套服务没有依赖任何 Web 框架而是直接用标准库socket实现见 tcpservice.py特点如下响应类型自动识别处理器返回值可以是dict/list序列化为 JSON、str按 HTML 输出、bytes二进制、FileResponse静态文件按 MIME 类型输出、GeneratorType流式输出text/event-stream统一由ResponseInfo根据类型自动设置Content-Type见 tcpservice.pyCORS 支持所有响应都带Access-Control-Allow-Origin: *浏览器端跨域调用无障碍WebSocket 握手按 RFC 标准计算Sec-WebSocket-AcceptSHA-1 Base64见 tcpservice.pyWebSocket 帧编解码完整实现了掩码处理、扩展长度126/127、Ping/Pong、Close 帧等见 tcpservice.py。2. Web 页面端点服务根路径/返回一个导航页源码 htmlcode/service/index.html列出所有页面链接。各页面端点说明如下2.1/page/mainui—— 主界面同步页与主窗口显示的文本内容同步包括原文、译文等渲染结果。其 HTML 由渲染模块动态生成TextBrowser.loadex_()见 servicecollection.py页面数据通过内部 WebSocket/__internalservice/mainuiws推送刷新见 gui/textbrowser.py 中大量WSForEach(mainuiwsoutputsave, ...)调用。此外页面还会把点击查词回调转发给主程序calllunaclickedwordgobject.base.clickwordcallback。2.2/page/transhist—— 历史记录同步页与历史文本翻译历史显示的文本内容同步由wvtranshist.loadex_()生成页面见 servicecollection.py内部 WebSocket/__internalservice/transhistws负责推送新的句子与译文见 gui/transhist.py。2.3/page/dictionary—— 词典查词页查词页面在/page/mainui中点击单词查词时会唤出该页面。其处理类PageSearchWord有一个细节若 URL 查询参数中携带word且包含原型prototype会先做一次 302 重定向把词形还原为原型后再打开页面见 servicecollection.py保证查询的是词典可识别的原形词。2.4/page/manyinone—— 多合一页面整合上述三个页面主界面、历史、查词的单一页面。其特殊交互逻辑是在该窗口内的/page/mainui子区域点击单词查词时不会打开新的查词窗口而是在当前窗口的/page/dictionary子区域内显示查询结果见 servicecollection.py。2.5/page/translate、/page/ocr、/page/tts分别为翻译、OCR、TTS 三个独立功能的网页界面页面文件存放在 htmlcode/service/ 目录下translate.html、ocr.html、tts.html分别由Pagetranslate、Pageocr、Pagetts返回。3. HTTP API 服务3.1GET /api/translate—— 翻译必填查询参数text待翻译文本可选参数id翻译器 ID。指定后使用对应翻译器未指定则使用当前最快的翻译接口返回application/json包含三个字段翻译器 IDid、翻译器名称name、翻译结果result。实现细节见 servicecollection.py通过gobject.base.textgetmethod(text, False, waitforresultcallback..., waitforresultcallbackenginetsid, waitforresultcallbackengine_forceTrue, erroroutput...)同步等待翻译结果用threading.Event阻塞直至回调返回翻译失败时返回{error: 错误信息, id: 翻译器ID, name: 翻译器名称}id/name仅在错误携带 ID 时存在翻译器 ID 与显示名通过dynamicapiname()和_TR()解析。示例curl http://127.0.0.1:2333/api/translate?textこんにちは # {id: sakura, name: Sakura, result: 你好}3.2GET /api/dictionary—— 词典查词必填查询参数word要查询的单词可选参数id词典 ID。两种模式见 servicecollection.py指定id返回单个词典查询结果的application/json对象包含词典 IDid、词典名称name、HTML 内容result查询失败含词典不存在、无结果时返回空对象{}未指定id并发查询所有已启用词典以text/event-stream流式返回每个事件为一个 JSON 对象id、name、result方便前端边收边渲染。实现上对所有词典调用cishu.safesearch(...)并发查询用threading.Semaphore(0)统计并发计数并逐个收集结果见 servicecollection.py。示例单词典curl http://127.0.0.1:2333/api/dictionary?word日本語idjisho示例全词典流式curl http://127.0.0.1:2333/api/dictionary?word日本語 # data: {id: jisho, name: Jisho, result: html...}3.3GET /api/mecab—— 日语分词解析必填查询参数text返回 Mecab 对text的解析结果。实现上直接调用gobject.base.parsehira(text)并把每个解析单元通过_.as_dict()转为 JSON 数组返回见 servicecollection.py。LunaTranslator 内置 Mecab 封装见 myutils/mecab.py适合日语文本的形态素分析。3.4GET /api/tts—— 语音合成必填查询参数text返回音频二进制数据响应头包含由 TTS 引擎确定的content-type如audio/wav与content-length若 TTS 出错则返回{error: 错误信息}。实现上通过gobject.base.reader.ttscallback(...)异步获取TTSResult再用threading.Event等待结果后原样输出见 servicecollection.py。示例curl -o out.wav http://127.0.0.1:2333/api/tts?textこんにちは3.5POST /api/ocr—— 图片文字识别请求方式为POSTContent-Type: application/json请求体包含字段image其值为Base64 编码的图片数据返回当前 OCR 引擎的识别结果 JSON。实现细节见 servicecollection.py服务端对image做base64.b64decode后加载为QImage若图片损坏qi.isNull()则直接报错随后调用ocr_run(qi)封装于 myutils/ocrutil.py执行识别并返回结果。示例IMG_B64$(base64 -w0 screenshot.png) curl -X POST http://127.0.0.1:2333/api/ocr \ -H Content-Type: application/json \ -d {\image\: \$IMG_B64\}3.6GET /api/list/dictionary—— 列出可用词典返回当前可用的词典列表每个元素为{id: 词典ID, name: 词典名称}。实现上遍历globalconfig[cishuvisrank]中的词典排序并过滤掉未实例化的项见 servicecollection.py因此顺序即界面上的显示顺序。3.7GET /api/list/translator—— 列出可用翻译器返回当前可用的翻译器列表每个元素为{id: 翻译器ID, name: 翻译器名称}。实现上遍历globalconfig[fix_translate_rank_rank]中的翻译器排序并过滤未实例化的项见 servicecollection.py。3.8GET /api/textinput—— 注入文本到主程序必填查询参数text相当于远程“输入文本”调用gobject.base.textgetmethod(text, is_auto_runFalse)把文本注入 LunaTranslator 主流程走原文处理、翻译等管线可用来做自动化测试或外部工具联动见 servicecollection.py。注意该接口没有返回值。4. WebSocket 实时服务两个 WebSocket 端点用于持续推送文本流适合做实时翻译挂件、字幕同步、自动化采集等场景。端点推送内容/api/ws/text/origin持续输出所有提取到的原文文本/api/ws/text/trans持续输出所有翻译结果实现机制见 servicecollection.py 与 textio/textoutput/websocket.py客户端连接后WSHandler.parse()将自身追加到全局连接列表wsoutputsave文本输出器Outputer在收到新文本时通过WSForEach遍历列表把原文推送给TextOutputOrigin类型的连接、把译文推送给TextOutputTrans类型的连接见 websocket.py某连接发生OSError断开时自动从列表移除不影响其他连接。前端接入示例原文流const ws new WebSocket(ws://127.0.0.1:2333/api/ws/text/origin); ws.onmessage (e) console.log(原文:, e.data);5. 内部 WebSocket 与外部扩展除公开端点外主界面页与历史页还各自使用一组内部 WebSocket/__internalservice/mainuiws、/__internalservice/transhistws完成页面与主程序的实时同步。其消息协议为 JSON{function: 函数名, args: [...]}例如主界面页支持calllunaloadready页面加载完成、callwheelEvent滚轮事件、calllunaclickedword点击查词等函数回调见 servicecollection.py。外部开发者可参考该模式实现自定义的远程界面。6. 常见问题与注意事项服务默认关闭未在设置中开启networktcpenable时所有端口请求都会被拒绝需先在设置界面开启或修改端口局域网访问服务绑定0.0.0.0同一局域网内的设备可通过http://主机IP:2333访问如有防火墙请放行对应端口端口冲突端口被占用时界面会提示“端口冲突”更换networktcpport即可禁用路径可通过network_service_disabled_paths配置禁用某些路径返回 404用于暴露面收敛/api/textinput无返回该接口只负责注入文本调用后不要期待响应体内容/api/dictionary的两种响应格式差异指定id返回普通 JSON失败为空对象{}不指定id返回text/event-stream流调用端需分别处理。参考文件速查关联文档docs/vi/apiservice.md、docs/en/apiservice.md、docs/zh/apiservice.md路由注册与各端点实现network/server/servicecollection.pyTCP/HTTP/WebSocket 底层实现network/server/tcpservice.pyWebSocket 连接池管理network/server/servicecollection_1.pyWebSocket 文本输出器textio/textoutput/websocket.py服务启动与配置LunaTranslator.py、gui/setting/textinput.py页面静态资源htmlcode/service/默认配置defaultconfig/config.json【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考