WebTrans Lab

English

WebTrans Lab 是一个学习和研究性质的本地网页翻译实验项目。项目通过桌面控制台、本地 HTTP 服务和 Chrome 扩展协作，在用户设备上验证网页正文、选中文本和格式保留文本的本地翻译流程。

项目当前处于 MVP 阶段，主要用于学习桌面应用、本地推理服务、浏览器扩展和模型合规接入的端到端工程实现。真实模型推理通过 llama-server 与 GGUF 模型文件接入，源码仓库默认不包含模型权重，也不作为官方产品、商业服务或生产可用方案发布。

本项目不提供模型下载、模型托管或模型再分发服务。用户需要自行从模型供应商官方渠道获取模型，并自行确认下载、使用、修改和分发行为符合对应许可证。

特性

• 本地优先：翻译服务运行在 127.0.0.1，浏览器扩展通过本地 HTTP API 调用。
• 桌面控制台：基于 Tauri 管理本地服务、模型状态、许可证确认和 Chrome 扩展 ZIP。
• Chrome 扩展：支持右键菜单、当前页面可见文本翻译、选中文本翻译和原文还原。
• 模型接入：预留 llama-server 推理引擎，支持 Hy-MT1.5-1.8B GGUF 模型接入。
• 加速策略：桌面端支持自动检测 Metal、CUDA、Vulkan，无法启用 GPU offload 时回退到 CPU。
• 合规提示：启用翻译前要求确认 Tencent HY Community License Agreement。

项目结构

.
├── chrome-extension/      # Chrome Manifest V3 扩展
├── desktop-app/           # Tauri 桌面控制台
├── docs/                  # 安装、API、配置和许可证说明
├── local-service/         # Python 本地翻译服务
├── scripts/               # 构建脚本
└── sidecars/              # 本地服务 sidecar 输出目录

快速开始

1. 启动本地服务

cd local-service
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m app.main

服务默认监听：

http://127.0.0.1:8765

2. 确认模型许可证

curl -s -X POST http://127.0.0.1:8765/api/license/accept \
  -H 'Content-Type: application/json' \
  -d '{"model":"HY-MT1.5-1.8B","license":"Tencent HY Community License Agreement","accepted":true}'

3. 验证翻译接口

curl -s -X POST http://127.0.0.1:8765/api/translate \
  -H 'Content-Type: application/json' \
  -d '{"source_lang":"auto","target_lang":"zh","texts":["Hello world"],"mode":"plain"}'

4. 加载 Chrome 扩展

1. 打开 Chrome 扩展管理页。
2. 开启开发者模式。
3. 选择“加载已解压的扩展程序”。
4. 选择仓库中的 chrome-extension 目录。

5. 运行桌面控制台

cd desktop-app
pnpm install
pnpm dev

真实模型接入

真实推理需要准备模型文件和支持 STQ kernel 的 llama-server 运行时。源码开发阶段建议使用项目内 .local-data 目录：

.local-data/
  models/Hy-MT1.5-1.8B-STQ1_0.gguf
  runtime/darwin-arm64/llama-server

启动服务时指定本地数据目录：

cd local-service
HYMT_HOME=/path/to/local-translator/.local-data python -m app.main

正式分发前需要分别验证目标平台运行时：

runtime/
  darwin-arm64/llama-server
  darwin-x64/llama-server
  windows-x64/llama-server.exe
  linux-x64/llama-server

请记录每个平台的运行时版本、构建 commit、构建参数、运行时 SHA256、模型文件大小和模型 SHA256，避免不兼容的普通 llama.cpp 运行时静默加载失败。

本地服务 API

常用接口：

• GET /api/health：健康检查。
• GET /api/model/status：查询模型、运行时和许可证状态。
• POST /api/license/accept：确认模型许可证。
• POST /api/translate：批量纯文本翻译。
• POST /api/translate/formatted：格式保留翻译。

更多字段说明见 docs/api.md。

构建

构建当前平台本地服务 sidecar：

python -m pip install -r local-service/requirements-build.txt
python scripts/build-local-service-sidecar.py

构建桌面应用：

cd desktop-app
pnpm install
pnpm build

模型供应商与致谢

本项目的真实翻译能力基于 Tencent HY / HY-MT 系列模型设计，感谢腾讯混元团队和相关模型发布者开放 HY-MT1.5 系列模型与文档，为本地网页翻译场景提供了高质量的基础模型能力。

模型仓库与许可证信息请以供应商官方发布为准：

• Tencent-Hunyuan / HY-MT: https://github.com/Tencent-Hunyuan/HY-MT
• Tencent HY-MT1.5-1.8B: https://huggingface.co/tencent/HY-MT1.5-1.8B
• Tencent HY Community License Agreement: 项目内 desktop-app/src/assets/tencent-hy-license.txt

Tencent HY 模型及其 GGUF 量化版本受 Tencent HY Community License Agreement 约束。使用、分发或向第三方提供服务前，请确认你已经完整阅读并遵守该许可证、Acceptable Use Policy、地域限制和 Notice 要求。

本项目不是 Tencent 或腾讯混元官方项目。Tencent 与本项目不存在关联、赞助或背书关系。

合规说明

• 本项目仅用于个人学习、技术研究和工程实践，不代表任何模型供应商、开源社区或商业主体的官方实现。
• 当前仓库不包含模型权重，模型文件需要用户自行按供应商许可证获取和放置。
• 本项目不提供模型下载、模型托管或模型再分发服务。
• 启用翻译前需要确认 Tencent HY Community License Agreement。
• 不得将 Tencent HY Works、输出或结果用于改进其他 AI 模型，除非符合许可证允许的范围。
• 公开分发前需要随产品附带模型许可证副本、Notice 文本和必要的最终用户提示。
• 如用于商业、跨地区或面向第三方的服务场景，请先完成独立法务审查。

文档

• 安装与本地运行 / Installation and Local Run
• 本地服务 API / Local Service API
• 配置说明 / Configuration
• 许可证与 Notice / License and Notice
• 隐私说明 / Privacy Notice
• 产品需求摘要 / Product Requirements Summary
• Roadmap / Roadmap EN
• 开源发布检查清单 / Open Source Release Checklist
• 贡献指南 / Contributing
• 安全说明 / Security

开发状态

当前版本仍是 MVP：

• 本项目定位为学习性质项目，代码结构和功能边界会优先服务于技术验证和二次学习。
• macOS Apple Silicon 的 llama-server 已通过 STQ1_0 模型验证。
• Windows、Linux 和 macOS Intel 需要分别构建和验证运行时。
• mock 翻译引擎仍用于端到端流程验证。
• 正式开源前建议补充项目代码许可证、发布包策略和平台兼容性矩阵。

许可证

项目代码采用 MIT License。模型权重、模型衍生物和模型输出相关权利义务不由本项目代码许可证覆盖，需遵守 Tencent HY Community License Agreement 及供应商发布的最新条款。

供应商致谢、非官方声明和模型许可证边界见 NOTICE。