解决99%的使用问题：kiss-translator常见问题解答

一、基础功能配置

1.1 如何关闭自动翻译

通过规则设置实现自动翻译关闭，以下四种方法任选其一：

配置方法	操作路径	适用场景
个人规则	个人规则 → 全局规则 → 开启翻译 → 默认关闭	长期全局关闭
订阅规则	规则订阅 → 选择 kiss-rules-off.json	临时切换关闭状态
覆写订阅	订阅规则设置 → 开启翻译 → 默认关闭	保持订阅但覆盖默认行为
网站规则	添加网站规则 → 匹配域名 → 开启翻译 → 默认关闭	特定网站单独设置

1.2 快捷键设置指南

浏览器扩展与油猴脚本的快捷键配置方式不同：

flowchart TD
    A[扩展用户] -->|Chrome/Edge| B[chrome://extensions/shortcuts]
    A -->|Firefox| C[about:addons → 扩展设置 → 管理快捷键]
    D[油猴用户] --> E[脚本管理页面 → 配置用户脚本命令]

默认快捷键一览：

• Alt+Q: 切换翻译状态
• Alt+C: 切换译文样式
• Alt+K: 打开设置弹窗
• Alt+S: 翻译选中文字
• Alt+O: 打开设置页面

二、翻译功能优化

2.1 翻译模式切换

根据不同阅读习惯选择合适的翻译展示模式：

pie
    title 翻译模式分布
    "双语对照" : 65
    "仅显示译文" : 20
    "鼠标悬停" : 10
    "划词翻译" : 5

仅显示译文设置路径：
个人规则 → 全局规则 → 仅显示译文 → 启用

提示：配合 Alt+C 快捷键可快速切换样式

2.2 划词翻译配置

划词功能的精细控制选项：

功能	配置路径	默认状态
划词触发	个人规则 → 全局规则 → 启用划词翻译	启用
悬停翻译	个人规则 → 全局规则 → 触发方式 → 悬停	禁用
词汇收藏	划词面板 → 点击⭐图标	-
音频朗读	划词面板 → 点击喇叭图标	-

三、高级规则系统

3.1 规则优先级体系

kiss-translator采用层级规则系统，优先级从高到低为：

stateDiagram-v2
    [*] --> 个人规则
    个人规则 --> 覆写订阅规则
    覆写订阅规则 --> 订阅规则
    订阅规则 --> 全局规则
    全局规则 --> [*]

关键提示：全局规则虽优先级最低，但作为默认规则控制基础行为

3.2 规则订阅与分享

社区维护的规则库：

• 通用规则：kiss-rules.json (默认订阅)
• 极简规则：kiss-rules-mini.json (轻量适配)
• 关闭规则：kiss-rules-off.json (禁用翻译)

自定义规则分享格式：

{
  "name": "技术文档优化",
  "rules": [
    {
      "match": ["developer.mozilla.org", "docs.python.org"],
      "selectors": {
        "enable": ["main > article"],
        "disable": ["pre", "code"]
      }
    }
  ]
}

四、翻译服务配置

4.1 常见API配置问题

问题现象	可能原因	解决方案
本地Ollama接口403	CORS限制	启动命令添加 --cors允许来源
油猴脚本请求失败	跨域限制	在脚本元数据添加 @connect 目标域名
DeepL接口无响应	地区限制	使用DeepLX代理或更换服务器节点
OpenAI接口超时	API密钥错误	在设置页验证密钥格式，确保无多余空格

4.2 自定义接口示例

通用请求Hook模板：

/**
 * @param {string} text 原文
 * @param {string} from 源语言
 * @param {string} to 目标语言
 * @param {string} url 接口地址
 * @param {string} key API密钥
 * @returns {[string, object]} [请求URL, 请求配置]
 */
(text, from, to, url, key) => [url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${key}`
  },
  body: JSON.stringify({
    text,
    source_lang: from || "auto",
    target_lang: to
  })
}]

响应Hook模板：

/**
 * @param {object} res 接口返回数据
 * @returns {[string, boolean]} [译文, 是否与原文相同]
 */
(res, text) => [
  res.translation || "翻译失败", 
  text.trim() === res.translation?.trim()
]

五、特定场景解决方案

5.1 YouTube字幕优化

YouTube字幕因流式加载导致翻译断句问题，可通过以下规则优化：

{
  "match": ["youtube.com"],
  "selectors": {
    "disable": ["ytd-transcript-renderer"]
  },
  "settings": {
    "delay": 1000
  }
}

原理：禁用原生字幕渲染器，增加翻译延迟聚合文本片段

5.2 数据同步配置

支持多种同步方案，推荐优先级：

flowchart LR
    A[WebDAV] -->|自建服务| 安全系数高
    B[KISS-Worker] -->|Cloudflare| 便捷度高
    C[本地文件] -->|手动导入| 隐私性高

WebDAV配置示例：

• 地址：https://dav.example.com/kiss
• 用户名：同步服务用户名
• 密码：同步服务密码

六、进阶功能探索

6.1 专业术语自定义

通过"自定义专业术语"功能维护个人词典：

1. 进入设置页 → 翻译设置 → 专业术语
2. 添加术语对：
   • 原文：API
   • 译文：应用程序编程接口（API）
3. 选择作用范围：全局/特定网站

6.2 性能优化建议

当遇到翻译延迟或页面卡顿：

1. 减少选择器范围：

   /* 优化前 */
   body * { ... }
   
   /* 优化后 */
   article, .content, .post { ... }
   

2. 调整批量翻译阈值： 设置 → 高级选项 → 文本分段 → 每段字数：500（默认200）

3. 启用缓存机制： 设置 → 高级选项 → 启用翻译缓存 → 缓存时长：3600秒

七、常见问题速查表

问题	解决方案
翻译不全	添加网站专属选择器规则
快捷键冲突	在浏览器扩展管理页重新分配
样式错乱	自定义CSS：.kiss-translated { color: #333 !important; }
无法安装扩展	检查浏览器版本是否支持Manifest V3
油猴脚本失效	更新Tampermonkey至4.18+版本

八、获取帮助与资源

8.1 官方资源

• 规则库：https://gitcode.com/gh_mirrors/ki/kiss-rules
• 代理服务：https://gitcode.com/gh_mirrors/ki/kiss-proxy
• 同步服务：https://gitcode.com/gh_mirrors/ki/kiss-worker

8.2 社区支持

• 提交Bug：项目Issues页面
• 规则求助：在规则库讨论区提问
• 功能建议：使用"Feature Request"模板

提示：提问时请附带以下信息：浏览器版本、扩展/脚本版本、问题复现步骤、控制台错误截图（F12打开）

九、自助诊断流程

当遇到未知问题时，可按以下流程排查：

flowchart TD
    A[问题发生] --> B{基础检查}
    B -->|是| C[清除浏览器缓存]
    B -->|否| D[检查扩展更新]
    C --> E[测试是否恢复]
    D --> E
    E -->|是| F[问题解决]
    E -->|否| G[开启调试模式]
    G --> H[查看控制台日志]
    H --> I[提交Issue附带日志]

调试模式开启：设置 → 高级选项 → 启用调试日志 → 按F12打开控制台查看

---