翻译规则优先级解密：kiss-translator高级使用技巧
项目地址: https://gitcode.com/gh_mirrors/ki/kiss-translator 你是否曾在使用翻译插件时遇到过这样的困境：明明设置了网站专属翻译规则，却始终不生效？或者全局翻译设置与特定网站规则冲突，导致翻译结果混乱？作为一款开源的双语对照翻译扩展和脚本，kiss-translator的规则系统采用分层设计，理解其优先级逻辑是解锁精准翻译的关键。本文将深入剖析规则优先级体系，通过12个实战案例和可视化流程图，帮助你彻底掌握规则配置技巧，让翻译体验从"能用"升级到"好用"。
读完本文你将获得：
- 掌握5层规则优先级判定逻辑
- 学会使用
GLOBAL_KEY实现规则继承 - 解决90%的规则冲突场景
- 定制专属网站翻译方案
- 利用订阅规则实现团队协作
一、规则系统核心架构：从代码到实践
1.1 优先级金字塔模型
kiss-translator的规则优先级遵循" specificity（特异性）优先"原则，形成严格的层级体系。通过分析src/libs/rules.js的核心代码，我们可以构建出如下优先级金字塔：
关键代码验证：在matchRule函数中，系统会按以下顺序处理规则：
// src/libs/rules.js 核心逻辑
const rules = await getRulesWithDefault();
if (injectRules) {
// 注入订阅规则（位于用户规则之后，全局规则之前）
rules.splice(-1, 0, ...subRules);
}
// 查找匹配的规则
const rule = rules.find((r) =>
r.pattern.split(",").some((p) => isMatch(href, p.trim()))
);
// 应用全局规则作为默认值
const globalRule = { ...GLOBLA_RULE, ...rules.find((r) => r.pattern === GLOBAL_KEY) };
1.2 规则匹配流程图
当浏览器加载页面时，规则引擎会执行以下流程：
二、优先级判定实战：5层规则详解
2.1 第1层：用户自定义规则（最高优先级）
用户在扩展选项中手动添加的规则，以精确匹配的pattern属性作为判定依据。适合为特定网站定制专属翻译方案。
创建方法：在扩展选项 → 规则管理 → 点击"添加"按钮，设置：
pattern:www.example.com/special-page（支持逗号分隔多个URL）selector:.article-content p（CSS选择器，指定翻译区域）translator:baidu（覆盖默认翻译服务）
代码验证：用户规则存储在rules数组头部，优先被find方法匹配：
// src/libs/rules.js
export const saveRule = async (newRule) => {
const rules = await getRulesWithDefault();
// 新规则添加到数组头部
rules.unshift(newRule);
await setRules(rules);
};
2.2 第2层：订阅规则覆盖（OwSubRule）
通过injectRules功能注入的订阅规则，可通过覆盖字段临时修改订阅规则的特定属性。适合团队共享规则时的个性化调整。
关键字段：在订阅规则设置中，以下字段设为非REMAIN_KEY值时将覆盖原规则：
translator: 翻译服务fromLang/toLang: 语言方向textStyle: 文本样式（支持自定义CSS）
代码实现：
// src/libs/rules.js
const mixRule = {};
Object.entries(owSubrule)
.filter(([key, val]) => val !== REMAIN_KEY)
.forEach(([key, val]) => { mixRule[key] = val; });
// 合并覆盖规则
subRules = subRules.map((item) => ({ ...item, ...mixRule }));
2.3 第3层：订阅规则（SubRules）
通过URL订阅的远程规则集合，加载后插入到用户规则与内置规则之间。适合社区共享的通用规则集。
订阅方法：
- 选项 → 订阅规则 → 添加订阅URL
- 启用"注入规则"开关
- 规则将自动合并到规则链中
同步机制：
// src/libs/subRules.js
export const loadOrFetchSubRules = async (url) => {
// 优先加载缓存
const cache = await getSubRulesCache(url);
if (cache) return cache;
// 缓存未命中时从远程获取
const response = await fetch(url);
const rules = await response.json();
// 验证规则格式
return checkRules(rules);
};
2.4 第4层：内置规则（BUILTIN_RULES）
项目预定义的常用网站规则，存储在src/config/rules.js中。覆盖90%主流网站，如GitHub、Twitter等。
示例规则：
// src/config/rules.js
"github.com": {
selector: `.markdown-body ${DEFAULT_SELECTOR}, .repo-description p`,
keepSelector: DEFAULT_KEEP_SELECTOR // 排除代码块等元素
},
"twitter.com": {
selector: `[data-testid="tweetText"]`,
keepSelector: `img, a` // 保留图片和链接
}
2.5 第5层：全局规则（GLOBAL_KEY）
特殊pattern为*的规则，作为所有规则的默认值。未被更高级规则覆盖的字段将继承全局规则的值。
核心字段继承逻辑：
// src/libs/rules.js
// 继承文本相关属性
[
"selector", "keepSelector", "terms", "selectStyle",
"parentStyle", "injectJs", "injectCss"
].forEach((key) => {
if (!rule[key]?.trim()) {
rule[key] = globalRule[key]; // 仅当子规则未定义时继承
}
});
// 继承开关类属性
[
"translator", "fromLang", "toLang", "transOpen"
].forEach((key) => {
if (rule[key] === undefined || rule[key] === GLOBAL_KEY) {
rule[key] = globalRule[key]; // 显式设为GLOBAL_KEY时强制继承
}
});
三、冲突解决实战：10个高频场景
3.1 场景1：全局规则与网站规则冲突
问题：全局设置transOpen: false（默认关闭翻译），但希望en.wikipedia.org自动开启翻译。
解决方案：创建用户规则：
pattern:en.wikipedia.orgtransOpen:true（显式覆盖全局关闭设置）
原理：transOpen属于"开关类属性"，当子规则设为具体值（true/false）而非GLOBAL_KEY时，将覆盖全局设置。
3.2 场景2：多规则匹配同一网站
问题：内置规则已包含github.com，但需要为github.com/settings设置不同选择器。
解决方案：创建更具体的用户规则：
pattern:github.com/settings（更精确的URL匹配）selector:.js-settings-content（专用选择器）
匹配优先级：URL路径越长、越具体的规则优先匹配。规则引擎通过isMatch函数判断：
// src/libs/utils.js
export const isMatch = (href, pattern) => {
if (pattern === GLOBAL_KEY) return true;
try {
return new RegExp(pattern).test(href);
} catch {
return href.includes(pattern);
}
};
3.3 场景3：订阅规则与用户规则融合
问题：订阅了团队共享的规则集，但需要微调某个网站的翻译服务。
解决方案：
- 订阅团队规则URL
- 在"覆盖订阅规则"面板设置：
translator:deepl（仅修改翻译服务，其他字段保持不变）
关键代码：REMAIN_KEY（-）表示不覆盖该字段：
// src/views/Options/OwSubRule.js
<MenuItem key={REMAIN_KEY} value={REMAIN_KEY}>
{i18n("remain_unchanged")}
</MenuItem>
四、高级技巧：规则调试与优化
4.1 规则调试工具
- 开发者工具控制台：输入
kissRules查看当前页面应用的规则 - 可视化指示器：翻译元素添加
data-kiss-rule属性，显示应用的规则pattern - 日志输出：启用调试模式后，控制台会输出规则匹配过程：
// src/libs/log.js kissLog(`规则匹配: ${matchedPattern}`, "debug");
4.2 性能优化：规则精简策略
| 优化方法 | 实现示例 | 效果 |
|---|---|---|
| 合并相似规则 | pattern: "siteA.com,siteB.com" | 减少规则数量 |
| 使用正则表达式 | pattern: "/^https?:\/\/.*\.github\.io/" | 匹配整类网站 |
| 复用选择器 | selector: DEFAULT_SELECTOR | 继承全局选择器 |
| 禁用未使用规则 | transOpen: "false" | 减少翻译计算 |
4.3 规则迁移与备份
导出/导入：
- 导出：选项 → 规则管理 → "导出"按钮，生成JSON文件
- 导入：使用"导入"按钮上传JSON文件
自动化备份：通过同步功能（src/libs/sync.js）实现规则云同步，支持GitHub Gist等存储后端。
五、规则优先级速查表
| 规则类型 | 优先级 | 存储位置 | 适用场景 |
|---|---|---|---|
| 用户自定义规则 | 1（最高） | IndexedDB | 特定网站定制 |
| 订阅规则覆盖 | 2 | IndexedDB | 临时修改订阅规则 |
| 订阅规则 | 3 | 远程URL + 缓存 | 社区共享规则 |
| 内置规则 | 4 | src/config/rules.js | 主流网站预设 |
| 全局规则 | 5（最低） | IndexedDB | 默认 fallback |
六、常见问题解决
Q1: 为什么我的规则不生效？
排查步骤：
- 检查pattern格式：确保没有多余空格，支持逗号分隔多个URL
- 验证选择器：在开发者工具Console执行
document.querySelector("你的selector") - 查看规则优先级：是否被更高优先级规则覆盖
- 检查注入开关：订阅规则需启用"注入规则"选项
Q2: 如何分享我的规则给团队？
实现方法：
- 将规则导出为JSON文件
- 上传到公共URL（如GitHub Gist）
- 团队成员添加该URL作为订阅源
- 通过覆盖规则实现个性化调整
Q3: 内置规则需要更新怎么办？
解决方案：
- 等待插件版本更新（内置规则随版本发布）
- 创建用户规则覆盖旧内置规则
- 参与社区贡献：提交PR到
src/config/rules.js
结语：构建你的翻译规则体系
掌握优先级逻辑后，你可以构建层次分明的规则系统：
- 基础层：全局规则设置默认翻译服务和语言
- 通用层：订阅社区维护的通用规则集
- 特殊层：为个性化需求创建用户规则
通过这种分层架构，既能享受社区共享的智慧，又能满足特定场景的定制需求。访问项目仓库获取最新规则模板：https://gitcode.com/gh_mirrors/ki/kiss-translator
提示：定期备份你的规则配置，通过"导出"功能保存到安全位置。遇到复杂规则问题，可在项目Issues中分享你的规则JSON和问题描述，获取社区支持。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
