Rocket.Chat 自动翻译服务商热切换机制解析：修复“切换 Provider 后翻译仍用旧服务商”的变更

导读

本文围绕 Rocket.Chat 仓库中一份 Changeset 变更说明 .changeset/autotranslate-provider-switch.md 展开：它记录了一个“切换自动翻译（Auto-Translate）服务商后，消息仍继续按旧服务商进行翻译，直到重启服务或先禁用再重新启用功能才恢复”的缺陷及其修复。读完本文，你将理解 Rocket.Chat 自动翻译的 TranslationProviderRegistry 注册与激活机制、afterSaveMessage 回调翻译流水线、各配置项（AutoTranslate_*）的联动关系，以及这次修复在运行期热切换场景下的验证方法。

一、变更说明：这次修复了什么

仓库中的变更文件 .changeset/autotranslate-provider-switch.md 全文非常简短，但它是一份标准的 Changeset 发布说明，包含两部分信息：

• 影响范围与版本号类型：frontmatter 中标注 '@rocket.chat/meteor': patch，说明该变更由 Meteor 主包（即 apps/meteor/package.json 对应的运行时）以 patch 级别纳入下一个版本；
• 缺陷描述：修复了“切换服务商后，自动翻译仍继续用之前选定的服务商翻译消息，直到重启服务或禁用再启用该功能”的问题。

原文（英文）描述为：

Fixes auto-translate continuing to translate messages with the previously selected service provider after switching providers, until the server was restarted or the feature was disabled and re-enabled.

从这份描述可以提炼出三个关键事实：

1. 缺陷触发条件：在管理后台将 AutoTranslate_ServiceProvider 从一种服务商切换为另一种（例如从 google-translate 切到 microsoft-translate）；
2. 缺陷表现：切换后新保存的消息仍然由旧服务商完成翻译；
3. 旧时的“绕过方式”：重启服务，或将 AutoTranslate_Enabled 关掉再打开，才能让新服务商生效。

“重启才生效、重新启用才恢复”这一症状本身就很有诊断价值：它指向进程内的内存状态与配置存储（Settings）之间不同步，而不是翻译调用本身出错。下面结合源码说明这套机制，以及这个不同步为什么会发生、为什么按上述方式可以绕过。

二、自动翻译模块的代码结构

自动翻译功能的核心服务端实现位于 apps/meteor/server/lib/autotranslate/ 目录，入口文件 apps/meteor/server/lib/autotranslate/index.ts 导出 TranslationProviderRegistry，并按顺序引入权限定义与四个内置服务商实现：

// apps/meteor/server/lib/autotranslate/index.ts
import { TranslationProviderRegistry } from './autotranslate';
import './permissions';
import './googleTranslate';
import './deeplTranslate';
import './libreTranslate';
import './msTranslate';

export { TranslationProviderRegistry };

目录下的关键文件：

文件	职责
autotranslate.ts	核心：TranslationProviderRegistry（服务商注册表/激活器）与抽象基类 AutoTranslate（分词、翻译、落库的通用流水线）
googleTranslate.ts	Google Translate 服务商实现
deeplTranslate.ts	DeepL 服务商实现
libreTranslate.ts	LibreTranslate 服务商实现
msTranslate.ts	Microsoft Translator 服务商实现
functions/saveSettings.ts	用户在房间级保存自动翻译开关与目标语言的逻辑
functions/getSupportedLanguages.ts	获取当前激活服务商支持的源语言列表

三、TranslationProviderRegistry：激活态全部保存在内存中

理解这次缺陷的关键，是理解服务商“激活态”的存储方式。在 apps/meteor/server/lib/autotranslate/autotranslate.ts 中：

const Providers = Symbol('Providers');
const Provider = Symbol('Provider');

export class TranslationProviderRegistry {
	static [Providers]: { [k: string]: AutoTranslate } = {};  // 已注册的服务商实例表
	static enabled = false;                                    // 功能总开关
	static [Provider]: string | null = null;                   // 当前激活的服务商名

三个静态成员构成了整个功能的活动状态：

• [Providers]：一张以服务商名为 key 的实例表。每个服务商在构造完成后调用 registerProvider(provider) 把自己登记进来，并以 _getProviderMetadata() 返回的 name 作为 key（见 autotranslate.ts#L48-L57）；
• enabled：功能总开关，getActiveProvider() 在第一行就检查它，为 false 时直接返回 null，整条翻译链路短路（autotranslate.ts#L62-L72）；
• [Provider]：当前激活服务商的名字字符串。setCurrentProvider(provider) 是唯一的写入口，只改这个静态字段（autotranslate.ts#L95-L97）。

setEnable(enabled) 除了翻转开关，还会触发 registerCallbacks()（autotranslate.ts#L99-L117）：

static setEnable(enabled: boolean): void {
	TranslationProviderRegistry.enabled = enabled;
	TranslationProviderRegistry.registerCallbacks();
}

static registerCallbacks(): void {
	if (!TranslationProviderRegistry.enabled) {
		callbacks.remove('afterSaveMessage', 'autotranslate');
		return;
	}
	callbacks.add(
		'afterSaveMessage',
		(message, { room }) => TranslationProviderRegistry.translateMessage(message, room),
		callbacks.priority.MEDIUM,
		'autotranslate',
	);
}

也就是说：“是否翻译”由 enabled 控制，“用谁翻译”由内存字段 [Provider] 控制，两者都不直接读数据库。那么谁来把数据库里的配置同步进内存？答案是文件末尾的 Meteor.startup 钩子（autotranslate.ts#L374-L387）：

Meteor.startup(() => {
	/** Register the active service provider on the 'AfterSaveMessage' callback.
	 *  So the registered provider will be invoked when a message is saved.
	 *  All the other inactive service provider must be deactivated.
	 */
	settings.watch<string>('AutoTranslate_ServiceProvider', (providerName) => {
		TranslationProviderRegistry.setCurrentProvider(providerName);
	});

	// Get Auto Translate Active flag
	settings.watch<boolean>('AutoTranslate_Enabled', (value) => {
		TranslationProviderRegistry.setEnable(value);
	});
});

settings.watch 是 Meteor 设置系统的订阅式接口：启动时立即以当前值执行一次回调，之后每当该设置项被更新时再执行。因此：

• 修改 AutoTranslate_ServiceProvider（切换服务商）→ 触发 setCurrentProvider(新服务商名) → 内存 [Provider] 更新；
• 修改 AutoTranslate_Enabled（总开关）→ 触发 setEnable(新值) → 翻转 enabled 并注册/移除 afterSaveMessage 回调。

这正是变更说明中“禁用再启用即可恢复”的原因：重新启用会走 setEnable(true) → registerCallbacks() 路径，把整条链路重新拉齐；重启则会让 watch 以数据库中最新值重新初始化所有内存字段。而缺陷发生的那段窗口里，切换 AutoTranslate_ServiceProvider 所应触发的内存更新没有落到实际生效的状态上（从源码结构看，问题就出在“设置变更 → setCurrentProvider 内存字段”这一同步环节上，而非翻译调用逻辑本身）。

四、消息翻译流水线：从保存消息到翻译落库

知道了激活态在哪里，再看完整链路。当 enabled 为 true 时，回调挂接在 afterSaveMessage 上，消息保存后即触发 TranslationProviderRegistry.translateMessage(message, room)（autotranslate.ts#L78-L89），其内部再次通过 getActiveProvider() 取实例——这里就是“用错服务商”最终体现为业务后果的位置：getActiveProvider() 读的是内存 [Provider]，如果该字段还停留在旧服务商名，翻译请求就会发往旧服务商的 API。

具体翻译流程在抽象基类 AutoTranslate.translateMessage（autotranslate.ts#L286-L325）中，步骤如下：

1. 确定目标语言：若显式传入 targetLanguage 则单语翻译；否则查询 Subscriptions.getAutoTranslateLanguagesByRoomAndNotUser(room._id, message.u?._id)，即“该房间中开启了自动翻译且不是本条消息作者的订阅”各自选择的目标语言集合。
2. setImmediate 异步执行，不阻塞消息保存主流程。先对消息副本做 分词（tokenize）：tokenize() 依次调用 tokenizeEmojis（:emoji: 短代码）、tokenizeCode（Markdown 代码块/行内代码，先经 Markdown.parseMessageNotEscaped 解析）、tokenizeURLs（[text](http://...) 与 <http://...|Text> 两种链接）、tokenizeMentions（@用户 与 #频道），把它们替换为形如 <i class=notranslate>{N}</i> 的占位符并存入 message.tokens。
3. 调用服务商私有方法 _translateMessage 完成真正的 REST 翻译调用（各服务商实现见第五节）。
4. 落库并通知：非空结果通过 Messages.addTranslations(message._id, translations, TranslationProviderRegistry[Provider] || '') 写入——注意第三个参数把当前服务商名一并持久化，这是每条翻译记录“由谁翻译”的证据字段；随后 notifyTranslatedMessage 触发 notifyOnMessageChange 让客户端刷新。
5. 附件翻译：对带 text/description 的 attachment 单独走 _translateAttachmentDescriptions，结果写入 Messages.addAttachmentTranslations。
6. 反分词（deTokenize）：deTokenize() 用 tokens 表把占位符还原为原始 emoji/代码/链接/mention，保证翻译结果中这些元素不被服务商误改。

其中值得注意的工程细节：链接与 Markdown 的正则（markdownLinkRegex、pipedLinkRegex、wrappedParagraphRegex）在模块顶层编译一次而非每条消息编译，注释明确说明共享 /g 标志是安全的，因为 String.prototype.replace 每次调用都会重置 lastIndex（autotranslate.ts#L22-L28）。

五、四个内置服务商：注册方式与 API Key 的热更新

每个服务商都是一个继承 AutoTranslate 的类，遵循相同的模式——以 Google 为例（apps/meteor/server/lib/autotranslate/googleTranslate.ts）：

class GoogleAutoTranslate extends AutoTranslate {
	apiKey: string;
	apiEndPointUrl: string;

	constructor() {
		super();
		this.name = 'google-translate';
		this.apiEndPointUrl = 'https://translation.googleapis.com/language/translate/v2';
		// Get the service provide API key.
		settings.watch<string>('AutoTranslate_GoogleAPIKey', (value) => {
			this.apiKey = value;
		});
	}
	...
}

可以看到，API Key 同样是 settings.watch 热更新到实例内存的，改 Key 不需要重启。四个服务商的实例名（即注册 key 与设置值）分别是 google-translate、deepl-translate、libre-translate、microsoft-translate，各自的 getSupportedLanguages(target) 实现由服务商 API 提供源语言列表，统一入口是 apps/meteor/server/lib/autotranslate/functions/getSupportedLanguages.ts。

提示：libre-translate 为自托管服务，其配置项（服务 URL 等）与其他三家的 API Key 不同；四个服务商的配置项全部集中在 apps/meteor/server/settings/message.ts 的 Message 组 AutoTranslate 分区内定义。

六、配置项全景：AutoTranslate_* 与 enableQuery 联动

在 apps/meteor/server/settings/message.ts 中，服务商选择项定义为：

await this.add('AutoTranslate_ServiceProvider', 'google-translate', {
	type: 'select',
	group: 'Message',
	section: 'AutoTranslate',
	values: [
		{ key: 'google-translate',  i18nLabel: 'AutoTranslate_Google' },
		{ key: 'deepl-translate',   i18nLabel: 'AutoTranslate_DeepL' },
		{ key: 'microsoft-translate', i18nLabel: 'AutoTranslate_Microsoft' },
		{ key: 'libre-translate',   i18nLabel: 'AutoTranslate_LibreTranslate' },
	],
	enableQuery: [{ _id: 'AutoTranslate_Enabled', value: true }],
	i18nLabel: 'AutoTranslate_ServiceProvider',
	public: true,
});

参数要点：

• 默认值 google-translate：即未显式配置时，内存中的 [Provider] 初始化为 Google；
• enableQuery：该设置项只有在 AutoTranslate_Enabled === true 时才在管理界面可编辑，这就是 UI 层面的“总开关”联动；
• 各家 API Key 设置项（AutoTranslate_GoogleAPIKey、AutoTranslate_DeepLAPIKey、AutoTranslate_MicrosoftAPIKey 等）使用复合 enableQuery，需要“总开关开启 且 当前选中的服务商等于对应 key”才显示。例如 Google 的 Key（message.ts#L329-L345 对应区段）要求 _id: 'AutoTranslate_Enabled', value: true 且 _id: 'AutoTranslate_ServiceProvider', value: 'google-translate'。

实操注意：切换服务商后，新服务商的 API Key 输入框此时才出现，务必在不重启的前提下确认新服务商的 Key 已填写——这也是复现与验证本缺陷时必须检查的状态之一。

用户侧（房间级）配置则由 apps/meteor/server/lib/autotranslate/functions/saveSettings.ts 处理：仅允许 autoTranslate（开关）与 autoTranslateLanguage（目标语言）两个字段，需具备 auto-translate 权限，且明确禁止在 E2E 加密房间开启自动翻译（因为服务端拿不到明文，无法代翻）：

const room = await Rooms.findE2ERoomById(rid, { projection: { _id: 1 } });
if (room && value === '1') {
	throw new Meteor.Error('error-e2e-enabled', 'Enabling auto-translation in E2E encrypted rooms is not allowed', {
		method: 'saveAutoTranslateSettings',
	});
}

七、缺陷机理小结与修复后的验证方法

把前面的证据串起来，可以得到一个自洽的诊断链路（注意：以下关于“为什么不同步”的表述属于从源码结构推断）：

1. 翻译用哪个服务商，完全取决于内存字段 TranslationProviderRegistry[Provider]；
2. 该字段的唯一更新来源是 settings.watch('AutoTranslate_ServiceProvider', ...) 回调里的 setCurrentProvider；
3. 缺陷窗口内，切换服务商后内存激活态未随之更新，于是 getActiveProvider() 持续返回旧服务商实例，addTranslations 落库的 provider 字段也持续是旧名——与变更说明“继续用之前选定的服务商翻译”完全吻合；
4. 重启服务会重新执行 Meteor.startup，watch 以数据库最新值重新初始化内存字段，故“重启后恢复”；禁用再启用则通过 setEnable → registerCallbacks 重新整条链路，故“重新启用后恢复”。

修复后的行为应当是：在管理后台将 AutoTranslate_ServiceProvider 从一种服务商切换为另一种后，无需重启服务，之后保存的消息即由新服务商完成翻译。可以按以下步骤在当前版本上验证：

1. 管理后台 → 设置 → Message → AutoTranslate：开启 AutoTranslate_Enabled，选择 google-translate 并填入有效 Key；
2. 在一个普通（非 E2E）频道中开启自动翻译，发送一条外语消息，确认出现翻译；
3. 切换到 microsoft-translate（或 deepl-translate），填写对应 Key，不重启；
4. 再发送一条外语消息，检查翻译结果的服务商归属：客户端显示的翻译来源，以及数据库中该消息翻译记录持久化的 provider 字段（Messages.addTranslations 写入的第三个参数）应变为新服务商名；
5. 反向切换回原服务商重复验证，确认双向热切换均即时生效。

八、顺带一提：.changeset 文件在发布流程中的角色

仓库根目录的 .changeset/ 目录使用 Changesets 工作流管理版本说明：每个待发布变更对应一个 markdown 文件，frontmatter 声明受影响包与版本类型（如本篇的 '@rocket.chat/meteor': patch），正文即面向用户的变更描述。当执行版本化发布时，这些文件会被消费、汇总进各包 CHANGELOG.md 并从目录中移除——所以这类文件通常只在“已提交、未发布”的窗口期存在于仓库中。本文分析的自动翻译热切换修复，正是以 .changeset/autotranslate-provider-switch.md 为载体进入该流程的一次 patch 级变更。

小结

• 自动翻译的“是否翻译 / 用谁翻译”分别由内存态 enabled 与 [Provider] 决定，配置同步依赖 settings.watch 在 Meteor.startup 中建立的回调（apps/meteor/server/lib/autotranslate/autotranslate.ts#L374-L387）；
• 本次变更修复的是“切换 AutoTranslate_ServiceProvider 后内存激活态未及时切换、导致翻译持续走旧服务商，直到重启或禁用再启用”的同步缺陷；
• 翻译流水线（afterSaveMessage → 分词 → 服务商 API → addTranslations 落库 → 反分词）本身不依赖重启，服务商 API Key 亦通过 settings.watch 热更新，因此正确的运维预期是：切换服务商属于运行期操作，任何“必须重启才生效”的行为都应视为异常。