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

项目概述

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" };
};

多翻译服务整合

翻译服务管理通过TranslatorManager实现，支持Google、DeepL、OpenAI等多种服务，核心代码位于src/libs/translator.js。系统通过适配器模式统一不同翻译服务的接口，确保上层模块使用一致的调用方式。

技术亮点

1. 模块化设计

项目采用分层架构，各模块通过明确接口通信：

• 核心层：翻译引擎、规则系统
• 服务层：API调用、存储管理
• 界面层：交互组件、样式系统

2. 性能优化

• 任务池：src/libs/pool.js实现并发控制
• 缓存机制：src/libs/cache.js减少重复翻译
• 节流处理：字幕更新等高频操作采用节流优化

3. 跨平台兼容

项目同时支持浏览器扩展和油猴脚本模式，通过src/userscript.js和条件编译实现不同环境适配。

总结

kiss-translator通过模块化架构实现了功能丰富且高效的翻译体验，核心优势包括：

1. 灵活的规则系统，适应不同网站结构
2. 高效的字幕翻译引擎，支持视频学习场景
3. 可扩展的翻译接口，对接各类翻译服务
4. 轻量级设计，兼顾性能与兼容性

项目架构设计平衡了功能复杂度和代码可维护性，为开源社区贡献了一个高质量的翻译工具。完整代码可通过仓库获取：https://gitcode.com/gh_mirrors/ki/kiss-translator