企业官网建设流程全解析

• 前端

导读：本文围绕 README.md 的官方说明，系统讲解 KISS Translator（简约翻译）这款开源双语对照翻译扩展与油猴脚本的完整使用体系——从浏览器安装、六大翻译场景、规则优先级与网页可视化规则编辑，到自定义翻译接口、聚合批量、流式传输与 Hook 高级玩法，再到快捷键与数据同步。读完本文，你将掌握这款工具的日常使用姿势，并理解其接口与规则体系背后的源码级设计，能够自行接入任意翻译 API、编写个性化翻译规则，甚至通过外部事件与其他脚本联动。

一、项目定位：保持简约，却能力完整

KISS Translator（简约翻译）是一款开源、简约的双语对照翻译浏览器扩展，同时提供油猴（Greasemonkey）脚本版本。它的核心产品理念是「保持简约、开放源代码」，但功能上并不简陋：不仅覆盖网页翻译、划词翻译、输入框翻译、鼠标悬停翻译与 YouTube 字幕翻译等常见场景，还内置了从 Google、Microsoft、DeepL 到 OpenAI、Gemini、Claude、Ollama 等数十种翻译服务接入能力。

在代码层面，翻译服务的能力清单可以从 src/config/api.js 中看到完整的实现：该文件集中定义了全部翻译引擎与词典服务商的标识常量，包括OPT_TRANS_GOOGLE（谷歌翻译）、OPT_TRANS_MICROSOFT（微软翻译）、OPT_TRANS_TENCENT（腾讯翻译君）、OPT_TRANS_VOLCENGINE（火山翻译）、OPT_TRANS_DEEPL/OPT_TRANS_DEEPLX/OPT_TRANS_DEEPLFREE（DeepL 系）、OPT_TRANS_OPENAI/OPT_TRANS_GEMINI/OPT_TRANS_GEMINI_2/OPT_TRANS_CLAUDE（主流大模型 API）、OPT_TRANS_OLLAMA（本地模型）、OPT_TRANS_OPENROUTER/OPT_TRANS_ORCAROUTER/OPT_TRANS_REQUESTY（多模型聚合 API）、OPT_TRANS_AZUREAI/OPT_TRANS_CLOUDFLAREAI（云厂商 AI）、OPT_TRANS_BUILTINAI（Chrome 浏览器内置 Gemini AI 翻译）以及OPT_TRANS_CUSTOMIZE（自定义翻译 API）等，并导出OPT_ALL_TRANS_TYPES作为内置支持的翻译引擎全集。

二、特性全景：从翻译场景到高级接口能力

2.1 适配的浏览器与运行环境

项目目标覆盖常见浏览器运行环境，包括：

• Chrome / Edge（桌面端主战场，功能最完整）
• Firefox
• Kiwi（Android 端 Chrome 内核浏览器）
• Orion（iOS）
• Safari（含 macOS 与 iOS）
• Thunderbird（邮件客户端）

2.2 支持的多类翻译服务

官方列出的翻译服务支持矩阵如下：

• 通用网页翻译：Google / Microsoft
• 国内商业 API：Tencent（腾讯翻译君）/ Volcengine（火山翻译）
• AI 大模型 API：OpenAI / Gemini / Claude / Ollama / DeepSeek / OpenRouter / OrcaRouter / Requesty，以及 Google 系、AzureAI、CloudflareAI、Cerebras、Zai（智谱）、SiliconFlow（硅基流动）、AliyunBailian（阿里云百炼）、XiaomiMimo（小米米莫）等
• 专业翻译 API：DeepL / DeepLX（自建中转）
• 浏览器内置 AI：Chrome 浏览器内置的 AI 翻译（BuiltinAI）

此外，通过「自定义接口」机制，理论上可以接入任何翻译服务——这一点在 custom-api_v2.md 中有完整的规范与示例支撑，后面单独成节展开。

2.3 覆盖的常见翻译场景

• 网页双语对照翻译：整页翻译并以双语对照形式呈现，支持自动识别文本与手动规则两种模式。
• 输入框翻译：通过快捷键（默认Alt+I）立即将输入框内文本翻译成其他语言。
• 划词翻译：任意页面打开翻译框，可用多种翻译服务对比翻译；同时支持英文词典翻译与收藏词汇。
• 鼠标悬停翻译：鼠标悬停段落即可翻译。
• YouTube 字幕翻译：支持任意翻译服务对视频字幕进行翻译并双语显示；内置字幕合并与断句算法，支持 AI 断句提升质量，并可自定义字幕样式。

2.4 多样化的翻译效果

• 自动识别文本模式：绝大部分网站无需编写规则即可翻译完整。
• 手动规则模式：可针对特定网站极致优化（详见「规则体系」一节）。
• 自定义译文样式：按需调整译文的字体、颜色等呈现方式。
• 富文本翻译与显示：尽量保留原文中的链接及其他文本样式（如斜体、加粗）。
• 仅显示译文：隐藏原文，只看译文。

2.5 翻译接口高级功能

• 自定义接口：理论上支持任何翻译接口。
• 聚合批量发送：将多个段落合并为一次请求发送，减少接口调用次数。
• 流式传输：实时显示翻译结果。
• AI 上下文会话记忆：保留多轮对话上下文，提升翻译效果。
• 自定义 AI 术语词典：对专业术语进行统一约束。
• Hook 与自定义参数：所有接口均支持Request Hook/Response Hook与自定义请求头等高级功能。

这些高级能力的底层参数可以在 src/config/api.js 的「基础请求控制参数」段找到实现依据：例如DEFAULT_FETCH_LIMIT = 10（默认最大并行请求数）、DEFAULT_BATCH_INTERVAL = 400（批处理合并请求的等待延迟，单位毫秒）、DEFAULT_BATCH_SIZE = 20（每次翻译请求最多合并发送的 DOM 段落数量）、DEFAULT_BATCH_LENGTH = 10000（每次请求最大字符数）、DEFAULT_BATCH_CONCURRENCY = 10（同时执行的聚合批次数量）、DEFAULT_CONTEXT_SIZE = 3（AI 翻译上下文历史条数上限）。理解这些默认值，有助于在聚合翻译出现超时或丢字时定位问题。

2.6 跨客户端数据同步

• KISS-Worker：基于 Cloudflare / Docker 自部署的数据同步服务。
• WebDAV：通用 WebDAV 协议同步。

同步能力与规则订阅、规则分享一起，构成了多设备、多浏览器之间配置一致性的基础。

三、安装：浏览器扩展 vs 油猴脚本

官方在安装一节明确建议：优先使用浏览器扩展，原因有二：

1. 浏览器扩展的功能更完整（本地语言识别、右键菜单等）；
2. 油猴脚本会遇到更多使用上的问题（跨域问题、脚本冲突等）。

3.1 浏览器扩展

• Chrome：通过 Chrome 网上应用店搜索 KISS Translator 安装；安装后同样适用于Kiwi（Android）与Orion（iOS）。
• Edge：通过 Edge 加载项商店搜索「简约翻译」安装。
• Firefox：通过 Firefox Add-ons 搜索 kiss-translator 安装。
• Thunderbird：通过项目 Releases 页面下载安装。
• Safari：官方标注为未完成（含 macOS 与 iOS），属于规划中的能力。

3.2 油猴脚本

• Chrome / Edge / Firefox：配合 Tampermonkey 或 Violentmonkey，安装kiss-translator.user.js脚本（可通过 Greasy Fork 搜索 KISS Translator 获取）。
• iOS Safari：配合 Userscripts Safari，安装kiss-translator-ios-safari.user.js专用脚本。

提示：油猴脚本版本如需访问自定义接口，必须在脚本设置中增加域名白名单，否则请求会被浏览器拦截，无法发出（详见「常见问题」）。

安装后，设置页面的直接访问地址是https://fishjar.github.io/kiss-translator/options.html（油猴版本）或通过扩展工具栏图标进入。

四、规则体系：个人规则 > 订阅规则 > 全局规则

4.1 优先级规则

翻译规则采用三层优先级：

个人规则 > 订阅规则 > 全局规则

其中全局规则优先级最低，但非常重要，相当于兜底规则：当个人规则与订阅规则都没有命中时，由全局规则保证大部分页面仍然能翻译完整。

4.2 规则的三种来源

• 全局规则：内置兜底规则，覆盖绝大多数网站的基础翻译。
• 订阅规则：通过 kiss-rules 社区订阅获取最新最全的规则列表，也支持分享个人私有规则列表；订阅服务可以自部署（结合 KISS-Worker），数据私有。
• 个人规则：针对特定网站手动编写的最优规则，优先级最高。

4.3 规则与语言、术语

规则系统还支持自定义专业术语与规则分享。术语词典在自定义接口场景下以{{glossary}}占位符注入 Prompt，供 AI 模型遵循。

五、在网页上直接可视化编辑规则

这是 README 常见问题中讲解最细致的功能：无需打开设置页，直接在目标网页上选取元素生成规则。完整操作流程如下：

1. 打开网页翻译面板，点击「编辑网站规则」。
2. 选择规则用途后点击「选取元素」，然后在网页上点击锁定目标元素。
3. 通过祖先路径调整层级，比较不同定位候选及匹配数量，点击「确认添加定位」加入草稿。
4. 最后点击主面板的「保存规则」完成保存。
5. 也可以通过「手动添加」直接输入 CSS 选择器。

细节要点（均来自官方说明）：

• 选取交互：选取链接时不会跳转，右键可取消选取；副面板中的← / →可按页面顺序浏览匹配元素。
• 规则类型：支持翻译目标、排除区域、根容器、保留原文和段落边界。修改、删除、撤销和重做都只更新当前草稿及预览，点击「保存规则」后才写入本地并触发同步。
• 草稿机制：打开编辑器不会自动保存规则，也不会改变自动扫描设置。「自动扫描页面」启用时，目标选择器不是翻译白名单；需要严格指定目标时可选择「禁用」。删除一条定位不等于排除区域，其他规则或自动扫描仍可能覆盖它。
• 组继承：「恢复此组继承」重新使用订阅／全局值；「清空此组」将草稿中的该组设为显式空选择器。清空根容器后不扫描页面。
• 匹配范围：没有匹配的个人规则时，新规则的默认网站匹配与 popup 的「网域」一致（例如www.bbc.com），可从下拉列表选择*.bbc.com等范围，也可输入自定义匹配规则。已有匹配的个人规则会直接载入编辑，保存时保留未修改的其他配置；已有hostname:规则仍兼容，订阅内容通过个人规则覆盖。
• 未保存草稿：有未保存草稿时，退出或重新读取规则会提示选择「保存规则」「不保存」或「继续编辑」。保存失败或检测到外部冲突会保留草稿；重新读取会替换草稿并清空撤销历史；页面路由变化时也会先提醒处理草稿。撤销历史仅保留在当前编辑会话。
• 预计翻译范围：点击一次显示高亮，再次点击关闭，按钮会显示当前开关状态。范围预览使用草稿规则，只查看当前已加载 DOM，不发送翻译请求；内部排除项、保留项和后续语言／长度过滤仍然生效。「查看译文」会执行实际翻译。退出时应用已保存的规则，并恢复进入前的翻译和交互开关。

当前可视化选取的边界：支持桌面普通 DOM 网页及其动态内容；iframe、Shadow DOM 内部、Canvas 文字和触屏专用操作暂未纳入可视化选取。油猴同源页面通过浏览器 Web Locks 协调写入；不同源页面共享的 GM 存储没有跨源原子事务保证，编辑器会在检测到外部变更时提示重新读取。

六、自定义接口：理论可接入任何翻译服务

自定义接口是该项目的高级核心能力。完整规范见 custom-api_v2.md，下面提炼关键内容。

6.1 默认接口规范（无需 Hook）

如果接口的请求数据和返回数据符合以下规范，则无需填写Request Hook或Response Hook。

非聚合翻译的 Request body：

{ "text": "hello", // 需要翻译的文本列表 "from": "auto", // 原文语言 "to": "zh-CN" // 目标语言 }

Response（两种格式均可）：

{ "text": "你好", // 译文 "src": "en" // 原文语言 } // 或者 { "text": "你好", // 译文 "from": "en" // 原文语言 }

聚合翻译的 Request body：

{ "texts": ["hello"], // 需要翻译的文本列表 "from": "auto", // 原文语言 "to": "zh-CN" // 目标语言 }

Response：

[ { "text": "你好", // 译文 "src": "en" // 原文语言 } ]

v2.0.4 版本之后还支持以下对象包裹格式：

{ "translations": [ // 译文列表 { "text": "你好", // 译文 "src": "en" // 原文语言 } ] }

6.2 Prompt 占位符

Prompt可替换占位符：

{{from}} // 原文语言名称 {{to}} // 目标语言名称 {{fromLang}} // 原文语言代码 {{toLang}} // 目标语言代码 {{text}} // 原文 {{tone}} // 风格 {{title}} // 页面标题 {{description}} // 页面描述

与 src/config/api.js 中定义的输入占位符完全对应（该文件还额外定义了{{url}}、{{summary}}、{{context}}、{{key}}、{{model}}、{{glossary}}、{{segments}}等占位符常量，供扩展场景使用）。

Hook 中的 Prompt 类型说明：

systemPrompt // 聚合翻译 System Prompt nobatchPrompt // 非聚合翻译 System Prompt nobatchUserPrompt // 非聚合翻译 User Prompt subtitlePrompt // 字幕翻译 System Prompt

6.3 谷歌翻译接口示例（不支持聚合）

https://translate.googleapis.com/translate_a/single?client=gtx&dj=1&dt=t&ie=UTF-8&q={{text}}&sl=en&tl=zh-CN

Request Hook：

async (args) => { const url = args.url.replace("{{text}}", args.texts[0]); const method = "GET"; return { url, method }; };

Response Hook：

async ({ res }) => { return { translations: [[res?.sentences?.[0]?.trans || "", res?.src]] }; };

6.4 Ollama 本地模型示例（开启聚合）

URL：

http://localhost:11434/v1/chat/completions

注意：Ollama 启动时须添加环境变量OLLAMA_ORIGINS=*，否则浏览器跨域请求会被拒绝（返回 403）；检查环境变量是否生效的命令为systemctl show ollama | grep OLLAMA_ORIGINS。

Request Hook：

async (args) => { const url = args.url; const method = "POST"; const headers = { "Content-type": "application/json" }; const body = { model: "gemma3", // 或 args.model messages: [ { role: "system", content: args.systemPrompt, }, { role: "user", content: JSON.stringify({ targetLanguage: args.toLang, segments: args.texts.map((text, id) => ({ id, text })), title: "", // 可省略 description: "", // 可省略 glossary: {}, // 可省略 tone: "", // 可省略 }), }, ], temperature: 0, max_tokens: 20480, think: false, stream: false, }; return { url, body, headers, method }; };

Response Hook（parseAIRes为内置的 AI 输出解析器）：

async ({ res, parseAIRes }) => { const translations = parseAIRes(res?.choices?.[0]?.message?.content); return { translations }; };

6.5 硅基流动示例（禁用聚合）

URL：

https://api.siliconflow.cn/v1/chat/completions

Request Hook：

async (args) => { const url = args.url; const method = "POST"; const headers = { "Content-type": "application/json", Authorization: `Bearer ${args.key}`, }; const body = { model: "tencent/Hunyuan-MT-7B", // 或 args.model messages: [ { role: "system", content: args.systemPrompt, }, { role: "user", content: args.userPrompt, }, ], temperature: 0, max_tokens: 20480, }; return { url, body, headers, method }; };

Response Hook：

async ({ res }) => { return { translations: [[res?.choices?.[0]?.message?.content || ""]] }; };

6.6 Hook 参数中的语言代码含义

• toLang、fromLang：本插件支持的标准语言代码。
• to、from：转换后的、适用于特定接口的语言代码。

如果自定义接口与标准语言代码不匹配，需要自行映射转换。标准语言代码表（节选自 custom-api_v2.md）：

["en", "English - English"], ["zh-CN", "Simplified Chinese - 简体中文"], ["zh-TW", "Traditional Chinese - 繁體中文"], ["ar", "Arabic - العربية"], ["bg", "Bulgarian - Български"], ["ca", "Catalan - Català"], ["hr", "Croatian - Hrvatski"], ["cs", "Czech - Čeština"], ["da", "Danish - Dansk"], ["nl", "Dutch - Nederlands"], ["fa", "Persian - فارسی"], ["fi", "Finnish - Suomi"], ["fr", "French - Français"], ["de", "German - Deutsch"], ["el", "Greek - Ελληνικά"], ["hi", "Hindi - हिन्दी"], ["hu", "Hungarian - Magyar"], ["id", "Indonesian - Indonesia"], ["it", "Italian - Italiano"], ["ja", "Japanese - 日本語"], ["ko", "Korean - 한국어"], ["ms", "Malay - Melayu"], ["mt", "Maltese - Malti"], ["nb", "Norwegian - Norsk Bokmål"], ["pl", "Polish - Polski"], ["pt", "Portuguese - Português"], ["ro", "Romanian - Română"], ["ru", "Russian - Русский"], ["sk", "Slovak - Slovenčina"], ["sl", "Slovenian - Slovenščina"], ["es", "Spanish - Español"], ["sv", "Swedish - Svenska"], ["ta", "Tamil - தமிழ்"], ["te", "Telugu - తెలుగు"], ["th", "Thai - ไทย"], ["tr", "Turkish - Türkçe"], ["uk", "Ukrainian - Українська"], ["vi", "Vietnamese - Tiếng Việt"],

七、快捷键体系

默认快捷键与用途如下：

快捷键的修改入口在浏览器插件管理页面，例如：

• Chrome：chrome://extensions/shortcuts
• Firefox：about:addons（点击齿轮菜单中的「管理扩展快捷键」）
• Edge：edge://extensions/shortcuts

在源码层面，快捷键设置界面位于 src/views/Options/Setting.js：该组件通过browser.commands.getAll()读取扩展注册的全部命令，并在设置页中以只读列表展示；点击编辑按钮时，会根据当前浏览器 UA 自动跳转到对应的快捷键管理页面（Firefox 不支持直接打开，会弹出提示）。i18n 文案（如toggle_translate_shortcut、toggle_popup_shortcut、open_setting_shortcut等）定义于 src/config/i18n.js。

八、外部触发：与其他脚本联动

KISS Translator 向网页环境暴露了一个自定义事件kiss_translator，任何页面脚本都可以通过window.dispatchEvent主动触发翻译相关操作。这在油猴脚本与网页自动化场景中非常实用。

// `toggle_translate` 切换翻译 // `toggle_styles` 切换样式 // `toggle_popup` 打开/关闭控制面板 // `toggle_transbox` 打开/关闭翻译弹窗 // `toggle_hover_node` 翻译鼠标悬停段落 // `input_translate` 翻译输入框 window.dispatchEvent(new CustomEvent("kiss_translator", {detail: { action: "toggle_translate" }}));

该机制的源码实现位于 src/config/msg.js：其中定义了EVENT_KISS_TRANSLATOR = "kiss_translator"（暴露给网页环境的外部交互事件）与EVENT_KISS_INNER = "kiss_translator_inner"（插件沙箱／内容脚本内部事件），以及各 action 对应的消息常量：MSG_TRANS_TOGGLE、MSG_TRANS_TOGGLE_STYLE、MSG_TRANSBOX_TOGGLE、MSG_POPUP_TOGGLE、MSG_HOVERNODE_TOGGLE、MSG_INPUT_TRANSLATE。

事件的实际监听与分发在 src/libs/translatorManager.js 的TranslatorManager中完成：它通过window.addEventListener(EVENT_KISS_TRANSLATOR, this.#windowMessageHandler)注册外部事件监听（并在stop()时移除），同时统一管理快捷键、触屏手势、油猴菜单命令以及运行期子模块的启停。

九、常见问题排查

9.1 接口（Ollama 等）测试失败

一般接口测试失败常见以下几种原因：

• 地址填错了：例如 Ollama 有原生接口地址和 OpenAI 兼容地址，本插件目前统一支持 OpenAI 兼容地址（http://localhost:11434/v1/chat/completions），不支持 Ollama 原生接口地址。
• 某些 AI 模型不支持聚合翻译：可以禁用聚合翻译，或通过自定义接口的方式使用（参考 custom-api_v2.md）。
• 某些 AI 模型的参数不一致：例如 Gemini 原生接口参数非常不一致，部分版本的模型不支持某些参数会返回错误；可以通过Hook修改请求body，或更换为Gemini2（OpenAI 兼容地址）。
• 服务器跨域限制访问，返回 403 错误：例如 Ollama 启动时必须添加环境变量OLLAMA_ORIGINS=*。

9.2 填写的接口在油猴脚本中不能使用

油猴脚本需要增加域名白名单，否则不能发出请求。

9.3 如何设置自定义接口的 Hook 函数

自定义接口功能非常强大、灵活，理论可以接入任何翻译接口，示例参考 custom-api_v2.md。

9.4 如何设置快捷键

在插件管理页面设置：Chrome 使用chrome://extensions/shortcuts，Firefox 使用about:addons。

十、开发指引与本地构建

如果你想基于源码自行构建或参与开发：

git clone https://gitcode.com/gh_mirrors/ki/kiss-translator.git cd kiss-translator git checkout dev # 提交 PR 建议推送到 dev 分支 pnpm install pnpm build

项目采用 pnpm 作为包管理器（参见 pnpm-workspace.yaml 与 package.json），构建产物分别面向 Chrome / Firefox / Thunderbird 等目标（public/manifest.json、public/manifest.firefox.json、public/manifest.thunderbird.json）。仓库中还包含大量针对翻译、规则、存储、同步与字幕模块的测试用例（如src/libs/translator.test.js、src/apis/trans.translate.test.js等），可用于验证构建后的行为。

十一、数据同步与关联项目

• KISS-Worker（cloudflare / docker）：可用于本项目的数据同步服务，亦可分享个人的私有规则列表；自己部署、自己管理、数据私有。
• kiss-rules：社区维护的订阅规则列表，最新最全；也可在社区求助规则相关的问题。

十二、未来规划

本项目为业余开发，无严格时间表，欢迎社区共建。已完成的规划方向包括：聚合发送文本（减少接口调用、提升性能）、增强富文本翻译、强化自定义/AI 接口（流式、上下文记忆、多轮对话）、英文词典备灾机制、优化 YouTube 字幕支持等。

规划中的方向包括：支持边缘 AI 计算（本地轻量 LLM、ASR、OCR、TTS 辅助翻译）、分布式共享平台（分享字幕、规则）、文档翻译（TXT、PDF、图片、漫画）、翻译 Agent（自研智能化翻译）、项目重构（使用现代框架与技术重构整个项目）。

结语

KISS Translator 的价值在于「简约却不简单」：它把网页双语对照翻译、划词翻译、字幕翻译、规则可视化编辑与自定义 AI 接口整合在一个开源扩展中，既适合普通用户开箱即用，也适合开发者通过自定义接口、Hook 与外部事件做深度定制。本文所有功能描述均以仓库内 README.md 及 src/config/api.js、src/config/msg.js、src/libs/translatorManager.js、src/views/Options/Setting.js、custom-api_v2.md 等源码与文档为依据，读者可按需深入查阅对应文件继续研究。

• 前端