LunaTranslator 网络服务与 API 接口完全指南：页面路由、HTTP/WebSocket 服务与源码级实现解析

LunaTranslator 网络服务与 API 接口完全指南页面路由、HTTP/WebSocket 服务与源码级实现解析【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslatorLunaTranslator视觉小说翻译器内置一套基于 Python 标准库socket自实现的 TCP 网络服务既提供面向用户的 Web 页面翻译、OCR、TTS、词典查询等也提供面向第三方程序集成的 HTTP/WebSocket API。本文以 docs/ko/apiservice.md 为骨架逐一讲解每个页面与接口的用途、参数、返回格式并结合 servicecollection.py、tcpservice.py 等源码说明底层实现原理。读完本文你可以直接用浏览器或 curl/WebSocket 客户端调用这些接口把翻译、OCR、TTS、词典查询能力集成到自己的工具链中。服务如何开启网络服务设置与端口网络服务并非默认开启需要在 LunaTranslator 的设置界面中手动启用。在文件页签下的网络服务分组textinput.py 中注册右侧挂有本文档链接apiservice.html中开启切换开关networktcpenable默认false开启后立即调用gobject.base.serviceinit()启动服务同时出现一个打开按钮点击后通过os.startfile打开浏览器访问http://127.0.0.1:{端口}端口号networktcpport可配置范围为 0~65535默认2333。修改端口后同样会触发serviceinit()重启服务若端口被占用界面会通过portconflict信号显示端口冲突提示。服务启停与端口绑定的核心逻辑位于 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(端口冲突)底层TCPServicetcpservice.py创建一个绑定0.0.0.0:port的监听 socket每个连接在独立线程中处理先解析请求头再根据请求路径和是否 WebSocket 握手分发给对应 Handler。需要说明的是服务监听在所有网卡上0.0.0.0因此局域网内其他设备也能访问使用前请确认端口暴露范围符合预期。服务启动时通过registerall(service)servicecollection.py注册了全部路由。另外配置项network_service_disabled_paths默认空列表见 config.json可屏蔽指定路径命中路径的请求直接返回 404。Web 页面路由所有页面均由HTTPHandler子类实现返回对应 HTML 文件经FileResponse读取并以 MIME 类型输出。导航总览页 index.html 给出了全部页面入口。/— 导航页对应PageIndex返回LunaTranslator\htmlcode\service\index.html页面列出下面全部子页面的超链接方便从浏览器进入。/page/mainui— 主界面文本对应PageMainui返回TextBrowser.loadex_()生成的页面webview.py内容与 LunaTranslator 主窗口中显示的翻译文本实时同步。在页面上点击单词会触发词典查询并跳转到/page/dictionary。/page/transhist— 翻译历史对应Pagetranshist返回wvtranshist.loadex_()生成的页面transhist.py内容与主程序历史文本窗口同步。/page/dictionary— 单词查询页对应PageSearchWord。不带参数访问时返回dictionary.html查询表单带word参数时页面内直接发起查询。源码中它还会处理原型词重定向若查询参数含prototype等分词信息WordSegResult.from_dict会解析出词的原型并通过RedirectResponse302 跳转到规范化的/page/dictionary?word原型词。/page/manyinone— 多合一页面对应PageManyInOne返回 manyinone.html。它用object内嵌了三个子页面上半屏左右分别是/page/transhist与/page/dictionary下半屏是/page/mainui?__internal1。关键交互该页通过 JS 重写了 mainui iframe 的open方法把点击单词打开的新查询窗口直接重定向到当前页面内的 dictionary iframe实现在一个窗口内完成看文本 → 点词 → 查词的闭环。/page/translate— 翻译界面对应Pagetranslate返回 translate.html。页面加载时先调用/api/list/translator拉取可用翻译器列表再逐个调用/api/translate并行翻译?text参数指定的文本翻译失败时对应区块标红并展示错误信息。/page/ocr— OCR 界面对应Pageocr返回 ocr.html。页面提供截图或上传图片功能调用/api/ocr完成识别。/page/tts— TTS 界面对应Pagetts返回 tts.html。输入文本后调用/api/tts合成语音并通过浏览器播放。HTTP API 服务所有/api/接口由HTTPHandler子类实现。请求解析RequestInfo基于urlsplit与parse_qsl自动把查询串转为参数字典返回体支持 strtext/html、dict/list/tupleapplication/json、bytes、FileResponse静态文件、ResponseWithHeader自定义头、生成器text/event-stream等类型统一由ResponseInfo序列化。另外所有响应都带Access-Control-Allow-Origin: *支持跨域调用。/api/translate— 文本翻译对应APITranslate。必须携带查询参数text否则抛异常返回 404。指定id翻译器 ID时强制使用该翻译器源码中对应waitforresultcallbackenginetsid与waitforresultcallbackengine_forceTrue不指定id时走textgetmethod默认流程返回最快返回结果的翻译器返回application/json正常时包含id翻译器 ID、name翻译器显示名、result译文文本翻译失败时返回error字段含id/name。底层通过threading.Event同步等待异步翻译回调结果见 servicecollection.py。典型调用curl http://127.0.0.1:2333/api/translate?texthelloidgoogle/api/dictionary— 词典查询对应APISearchWord。必须携带word参数。指定id词典 ID时仅查询该词典返回单个 JSON 对象{id:..., name:..., result:HTML 内容}词典不存在或查询无结果时返回空对象{}不指定id时并发查询所有可用词典源码用Semaphore计数等待全部结果以text/event-stream流式返回多条事件每条事件体是data: {id:..., name:..., result:...}格式的 JSON 字符串。/api/mecab— 日语分词对应APImecab。必须携带text参数返回gobject.base.parsehira(text)的分词结果数组每个元素是词条信息的 dict包含读音等字段供前端做分词与注音展示。注意该接口依赖项目内 Mecab 集成mecab.py。/api/tts— 语音合成对应APItts。必须携带text参数通过reader.ttscallback异步合成语音成功后以ResponseWithHeader返回音频二进制content-type取自 TTS 引擎返回的 MIME如audio/mpeg并带content-length失败时返回{error: ...}。合成过程同样用threading.Event阻塞等待结果。/api/ocr— 图片识别对应APIocr仅接受 POSTmethod POST。请求体必须是 JSON包含image字段值为base64 编码的图片。服务端解码后用QImage.loadFromData还原图像交由ocr_runocrutil.py调用当前配置的 OCR 引擎识别返回识别结果的 JSON。base64 解码失败或图像无效时抛异常返回 404。curl -X POST http://127.0.0.1:2333/api/ocr \ -H Content-Type: application/json \ -d {image:base64 图片数据}/api/list/translator— 翻译器列表对应APITranslators。遍历globalconfig[fix_translate_rank_rank]翻译器排序只保留当前已加载的引擎返回形如[{id:google,name:Google 翻译}, ...]的 JSON 数组。/page/translate页面正是依赖它渲染翻译器按钮列表。/api/list/dictionary— 词典列表对应APIdicts。遍历globalconfig[cishuvisrank]词典显示顺序只保留已加载的词典返回[{id:jisho,name:Jisho}, ...]数组。/api/textinput— 文本输入对应TextInput。必须携带text参数将其注入gobject.base.textgetmethod(text, is_auto_runFalse)相当于从外部向 LunaTranslator 送入一段待翻译文本可配合热键或第三方脚本实现外部输入 → 主程序翻译的联动。WebSocket 服务WebSocket 握手与帧编解码由WSHandlertcpservice.py实现握手时校验Sec-WebSocket-Key并按 RFC 6455 规则计算Sec-WebSocket-Accept返回 101帧解析支持文本帧opcode 0x1、关闭帧0x8与 Ping/Pong0x9/0xA并正确处理 126/127 扩展长度与客户端掩码。服务端另有__internalservice/mainuiws、__internalservice/transhistws两个内部 WebSocket 路由供程序内置 WebView 与渲染页双向通信使用。对外公开的 WebSocket 接口有两个/api/ws/text/origin连接建立后LunaTranslator 抽取到的所有原始文本会被持续推送到该连接/api/ws/text/trans连接建立后所有翻译结果会被持续推送文档标注为计划中实际当前版本两者共用wsoutputsave连接池见下文。两者的推送机制见 servicecollection_1.py连接建立时parse会把自身追加到全局连接池wsoutputsave随后textio层的 WebSocket 输出器 websocket.py 通过dispatch(text, isorigin)判断连接类型TextOutputOrigin或TextOutputTrans把文本以文本帧send_text推送给匹配的连接连接断开OSError时自动从池中移除。也就是说第三方程序可以建立 WebSocket 长连接实时获取游戏内抽取的原文与译文用于制作字幕、弹幕或日志等扩展应用。实战用一行命令打通翻译与查询由于接口返回标准 JSON 且支持跨域你可以轻松将其接入自己的脚本。例如将/api/translate封装为命令行工具curl -s http://127.0.0.1:2333/api/translate?text$(python -c import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1])) こんにちは)更推荐使用--get并显式 URL 编码。指定翻译器时先查列表再填idcurl -s http://127.0.0.1:2333/api/list/translator curl -s http://127.0.0.1:2333/api/translate?texthelloid翻译器ID查询单词全词典流式curl -s http://127.0.0.1:2333/api/dictionary?word%E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF实时接收原文/译文WebSocket# 使用任意 WebSocket 客户端如 wscat wscat -c ws://127.0.0.1:2333/api/ws/text/origin wscat -c ws://127.0.0.1:2333/api/ws/text/trans扩展阅读服务端全部路由注册servicecollection.pyHTTP/WebSocket 底层实现握手、帧解析、响应序列化tcpservice.py设置入口与端口配置textinput.py服务启停逻辑LunaTranslator.py页面实现index.html、translate.html、manyinone.html多语言版本文档docs/en/apiservice.md、docs/zh/apiservice.md使用前提提醒以上接口依赖 LunaTranslator 处于运行状态且已在设置中开启网络服务并确认端口默认 2333未被占用。翻译、词典、OCR、TTS 的具体效果取决于你在 LunaTranslator 中实际配置的引擎未启用相应引擎的接口会返回空结果或错误。【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考