从核心到界面：kiss-translator模块化架构深度解析

2026-02-05 04:33:48作者：滑思眉Philip

项目概述

kiss-translator是一个简约、开源的双语对照翻译扩展及油猴脚本，支持网页翻译、字幕翻译、划词翻译等多种场景。项目采用模块化设计，核心功能通过多个相互协作的模块实现，整体架构清晰且易于扩展。项目完整结构可参考项目根目录。

核心模块架构

项目核心功能通过以下关键模块实现，各模块职责明确且通过统一接口协作：

1. 翻译引擎层

TranslatorManager作为翻译功能的总调度中心，协调翻译器、输入翻译器和翻译框管理器等组件。该模块位于src/libs/translatorManager.js，负责：

初始化翻译相关组件
注册快捷键和事件监听
处理跨模块消息通信
管理翻译状态切换

// 核心初始化逻辑示例
this._translator = new Translator({
  rule,
  setting,
  favWords,
  isUserscript,
  isIframe,
});
this._transboxManager = new TransboxManager(setting);
this._inputTranslator = new InputTranslator(setting);

2. 字幕翻译系统

针对视频平台的字幕翻译需求，项目实现了完整的字幕处理流程：

BilingualSubtitleManager负责在视频上显示和翻译字幕，位于src/subtitle/BilingualSubtitleManager.js。其核心功能包括：

字幕窗口创建与样式控制
字幕时间轴匹配
预翻译与实时更新
字幕拖动交互

关键实现包括时间轴匹配算法：

#findSubtitleIndexForTime(currentTimeMs) {
  return this.#formattedSubtitles.findIndex(
    (sub) => currentTimeMs >= sub.start && currentTimeMs <= sub.end
  );
}

3. 翻译规则系统

项目支持自动识别与手动规则两种翻译模式，规则系统通过以下组件实现：

规则定义：src/config/rules.js
规则管理：src/hooks/Rules.js
规则优先级：个人规则 > 订阅规则 > 全局规则

规则系统允许用户针对特定网站进行翻译优化，支持自定义选择器、排除规则和翻译样式。

4. 界面交互组件

项目提供多种用户交互方式，核心界面组件包括：

FABManager：浮动操作按钮，src/libs/fabManager.js
PopupManager：设置弹窗，src/libs/popupManager.js
TransboxManager：翻译框管理，src/libs/tranbox.js

这些组件通过统一的事件系统通信，确保界面操作的一致性和响应性。

高级功能实现

自定义翻译接口

项目支持通过自定义接口接入任意翻译服务，实现方式参考custom-api_v2.md。自定义接口需实现请求/响应钩子，例如Ollama接口：

// 请求钩子示例
async (args) => {
  const body = {
    model: "gemma3",
    messages: [
      { role: "system", content: args.defaultSystemPrompt },
      { role: "user", content: JSON.stringify({
          targetLanguage: args.to,
          segments: args.texts.map((text, id) => ({ id, text }))
        })
      }
    ]
  };
  return { url: args.url, body, headers: { "Content-type": "application/json" }, method: "POST" };
};