消息文本翻译

从 5.24.0 版本起，IMLib SDK（融云即时通讯能力库）支持对文本消息和纯文本内容进行翻译。您可以设置用户级别的翻译语言和自动翻译状态，也可为不同会话单独配置翻译策略。

IMLib SDK 提供了两个批量翻译接口：

• translateMessagesWithParams：用于翻译文本消息（RCIMIWTextMessage）内容。
• translateTextsWithParams：用于翻译任意文字内容。

提示

翻译功能需网络连接，请确保设备网络通畅。批量翻译内容可能耗时较长，接口不会直接返回翻译结果。请通过设置 RCIMIWEngine 的监听器获取翻译内容。

开启翻译服务

请前往融云控制台开启翻译功能。

用户级全局设置

全局设置对同一用户的所有登录设备生效。一端设置后，其他设备可通过 RCIMIWEngine 的事件监听获得变更通知。

设置翻译目标语言

通过 setTranslationLanguage 接口可以设置用户级别的翻译语言。支持的语种请参考翻译语言代码列表 。未设置时，默认目标语言为中文（zh）。

参数说明

参数	类型	说明
language	String	翻译目标语言
callback	IRCIMIWTranslateResponseCallback?	结果回调

示例代码

Dart

IRCIMIWTranslateResponseCallback callback = IRCIMIWTranslateResponseCallback(
  onTranslateResponse: (int code) {
    if (code == 0) {
      // 设置翻译语言成功
      print('设置翻译语言成功');
    } else {
      // 设置翻译语言失败
      print('设置翻译语言失败，错误码：$code');
    }
  }
);

// 假设您已经创建并保存了引擎实例
RCIMIWEngine? engine = yourEngineInstance; // 替换为您的引擎实例

int result = await engine?.setTranslationLanguage(
  "zh", 
  callback: callback
) ?? -1;

获取翻译语言

通过 getTranslationLanguage 接口可以获取用户级别的翻译语言。

参数说明

参数	类型	说明
callback	IRCIMIWTranslateGetLanguageCallback?	结果回调

示例代码

Dart

IRCIMIWTranslateGetLanguageCallback callback = IRCIMIWTranslateGetLanguageCallback(
  onTranslateGetLanguage: (int code, String? language) {
    if (code == 0) {
      // 获取翻译语言成功
      print('当前翻译语言: $language');
    } else {
      // 获取翻译语言失败
      print('getTranslationLanguage error: $code');
    }
  }
);

// 假设您已经创建并保存了引擎实例
RCIMIWEngine? engine = yourEngineInstance; // 替换为您的引擎实例

int result = await engine?.getTranslationLanguage(
  callback: callback
) ?? -1;

标记自动翻译状态

注意

IMLib SDK 本身不包含自动翻译功能，仅用于向应用的业务逻辑提供开关存储和多端状态同步。

通过 setAutoTranslateEnable 接口可以标记用户级别的自动翻译状态。

参数说明

参数	类型	说明
enable	bool	是否标记为自动翻译
callback	IRCIMIWTranslateResponseCallback?	结果回调

示例代码

Dart

IRCIMIWTranslateResponseCallback callback = IRCIMIWTranslateResponseCallback(
  onTranslateResponse: (int code) {
    if (code == 0) {
      // 标记自动翻译状态成功
      print('标记自动翻译状态成功');
    } else {
      // 标记自动翻译状态失败
      print('标记自动翻译状态失败，错误码：$code');
    }
  }
);

// 假设您已经创建并保存了引擎实例
RCIMIWEngine? engine = yourEngineInstance; // 替换为您的引擎实例

int result = await engine?.setAutoTranslateEnable(
  true,
  callback: callback
) ?? -1;

查询自动翻译状态

通过 getAutoTranslateEnabled 接口可以获取用户级别的自动翻译状态。

参数说明

参数	类型	说明
callback	IRCIMIWGetAutoTranslateEnabledCallback?	结果回调

示例代码

Dart

IRCIMIWGetAutoTranslateEnabledCallback callback = IRCIMIWGetAutoTranslateEnabledCallback(
  onGetAutoTranslateEnabled: (int code, bool? isEnable) {
    if (code == 0) {
      // 获取自动翻译状态成功
      print('自动翻译状态: $isEnable');
    } else {
      // 获取自动翻译状态失败
      print('getAutoTranslateEnabled error: $code');
    }
  }
);

// 假设您已经创建并保存了引擎实例
RCIMIWEngine? engine = yourEngineInstance; // 替换为您的引擎实例

int result = await engine?.getAutoTranslateEnabled(
  callback: callback
) ?? -1;

监听全局配置变更

全局设置（翻译语言、自动翻译状态）的多端同步，通过 onTranslationLanguageChanged 和 onAutoTranslateStateChanged 回调。详见翻译事件监听。

会话级翻译策略

注意

IMLib SDK 本身不包含自动翻译功能，仅用于向应用的业务逻辑提供开关存储和多端状态同步。

IMLib SDK 支持会话级配置，可针对不同会话单独设置自动翻译策略。会话级配置对同一用户的所有设备生效，变更后其他设备可通过 onConversationTranslationStrategySynced 获取通知。

设置会话翻译策略

通过 batchSetConversationTranslateStrategy 接口可以批量设置会话翻译策略。成功设置后，对应会话的 translateStrategy 属性将会被更新。

翻译策略枚举

RCIMIWTranslateStrategy 枚举定义了会话的翻译策略：

• defaultFollowUser：默认策略，会跟随用户级别的自动翻译方式
• autoOn：自动翻译，该会话中的消息会自动翻译
• autoOff：手动翻译，该会话中的消息不会自动翻译

示例代码

Dart

List<RCIMIWConversationType> types = [RCIMIWConversationType.private];
List<String> targetIds = ["targetId"];
List<String> channelIds = [""];

IRCIMIWTranslateResponseCallback callback = IRCIMIWTranslateResponseCallback(
  onTranslateResponse: (int code) {
    if (code == 0) {
      // 设置会话翻译策略成功
      print('设置会话翻译策略成功');
    } else {
      // 设置会话翻译策略失败
      print('设置会话翻译策略失败，错误码：$code');
    }
  }
);

// 假设您已经创建并保存了引擎实例
RCIMIWEngine? engine = yourEngineInstance; // 替换为您的引擎实例

int result = await engine?.batchSetConversationTranslateStrategy(
  types, 
  targetIds,
  channelIds,
  RCIMIWTranslateStrategy.autoOn,
  callback: callback
) ?? -1;

查询会话翻译策略

获取会话对象 RCIMIWConversation 后，可通过其 translateStrategy 属性读取当前策略。

示例代码

Dart

// 检查会话的翻译策略
RCIMIWTranslateStrategy? strategy = conversation.translateStrategy;
switch (strategy) {
  case RCIMIWTranslateStrategy.defaultFollowUser:
    // 使用默认策略，跟随用户级别设置
    print('使用默认翻译策略');
    break;
  case RCIMIWTranslateStrategy.autoOn:
    // 该会话开启自动翻译
    print('该会话开启自动翻译');
    break;
  case RCIMIWTranslateStrategy.autoOff:
    // 该会话关闭自动翻译
    print('该会话关闭自动翻译');
    break;
  default:
    break;
}

监听会话状态变更

多端登录时，设置结果会通过 onConversationTranslationStrategySynced 方法通知其他端。详见翻译事件监听。

批量翻译文本消息

通过 translateMessagesWithParams 接口可以批量翻译文本消息。

参数说明

参数	类型	说明
params	RCIMIWTranslateMessagesParams	翻译的消息参数
callback	IRCIMIWTranslateResponseCallback?	结果回调

RCIMIWTranslateMessagesParams 属性说明

属性	类型	说明
list	List<RCIMIWTranslateMessageParam>	待翻译的消息参数数组。数组长度限制为 1 到 10。
force	boolean	是否强制重新翻译，并忽略已有的翻译缓存。默认为 false。
mode	RCIMIWTranslateMode	翻译模式。目前仅支持高速翻译（mechanical）。

RCIMIWTranslateMessageParam 属性说明

属性	类型	说明
messageUId	String	消息的唯一标识符（必须）。
sourceLanguage	String	源语言。为空时，则自动检测。
targetLanguage	String	目标语言，为空时使用配置的全局语言。

示例代码

Dart

List<RCIMIWTranslateMessageParam> messageParams = [];

RCIMIWTranslateMessageParam param = RCIMIWTranslateMessageParam.create(
  messageUId: "messageUId"
);
// 翻译的语言，为空时，使用配置的全局语言
param.targetLanguage = "zh";
// 消息内容的语言，为空时，会自动识别
param.sourceLanguage = "en";
messageParams.add(param);

RCIMIWTranslateMessagesParams params = RCIMIWTranslateMessagesParams.create(
  list: messageParams
);
// 翻译模式，默认为 RCIMIWTranslateMode.mechanical
params.mode = RCIMIWTranslateMode.mechanical;
// 是否强制重新翻译，默认为 false
params.force = true;

IRCIMIWTranslateResponseCallback callback = IRCIMIWTranslateResponseCallback(
  onTranslateResponse: (int code) {
    if (code == 0) {
      // 翻译请求发送成功
      print('翻译请求发送成功');
    } else {
      // 翻译请求发送失败
      print('翻译请求发送失败，错误码：$code');
    }
  }
);

// 假设您已经创建并保存了引擎实例
RCIMIWEngine? engine = yourEngineInstance; // 替换为您的引擎实例

int result = await engine?.translateMessagesWithParams(
  params, 
  callback: callback
) ?? -1;

批量翻译文本内容

通过 translateTextsWithParams 接口可以批量翻译文本内容。

参数说明

参数	类型	说明
params	RCIMIWTranslateTextParams	翻译的文本参数
callback	IRCIMIWTranslateResponseCallback?	结果回调

RCIMIWTranslateTextParams 属性说明

属性	类型	说明
list	List<RCIMIWTranslateTextParam>	待翻译的文本内容参数数组。数组长度限制为 1 到 10。
mode	RCIMIWTranslateMode	翻译模式。目前仅支持高速翻译（mechanical）。

RCIMIWTranslateTextParam 属性说明

属性	类型	说明
text	String	待翻译的文本内容（必须）。
sourceLanguage	String	源语言，为空时，则自动检测。
targetLanguage	String	目标语言，为空时使用配置的全局语言。

示例代码

Dart

List<RCIMIWTranslateTextParam> textParams = [];

RCIMIWTranslateTextParam param = RCIMIWTranslateTextParam.create(
  text: "Hello, World!"
);
// 翻译的语言，为空时，使用配置的全局语言
param.targetLanguage = "zh";
// 消息内容的语言，为空时，会自动识别
param.sourceLanguage = "en";
textParams.add(param);

RCIMIWTranslateTextParams params = RCIMIWTranslateTextParams.create(
  list: textParams
);
// 翻译模式，默认为 RCIMIWTranslateMode.mechanical
params.mode = RCIMIWTranslateMode.mechanical;

IRCIMIWTranslateResponseCallback callback = IRCIMIWTranslateResponseCallback(
  onTranslateResponse: (int code) {
    if (code == 0) {
      // 翻译请求发送成功
      print('翻译请求发送成功');
    } else {
      // 翻译请求发送失败
      print('翻译请求发送失败，错误码：$code');
    }
  }
);

// 假设您已经创建并保存了引擎实例
RCIMIWEngine? engine = yourEngineInstance; // 替换为您的引擎实例

int result = await engine?.translateTextsWithParams(
  params,
  callback: callback
) ?? -1;

监听翻译结果

翻译结果通过 onTranslationDidFinished 方法异步返回。同时，消息对象 RCIMIWTextMessage 的 translateInfo 属性也会更新。

翻译结果数据结构

RCIMIWTranslateItem

onTranslationDidFinished 回调返回 RCIMIWTranslateItem 列表。

属性	类型	说明
errorCode	int	翻译结果的状态码。
translateInfo	RCIMIWTranslateInfo?	翻译结果信息。

RCIMIWTranslateInfo

RCIMIWTextMessage 的 translateInfo 属性以及 RCIMIWTranslateItem 中的 translateInfo 属性，都使用 RCIMIWTranslateInfo 对象存储翻译结果。

属性	类型	说明
translatedText	String?	翻译后的内容
status	RCIMIWTranslateStatus?	翻译状态（无、翻译中、成功、失败）
targetLanguage	String?	翻译目标语言

翻译状态枚举

RCIMIWTranslateStatus 枚举定义了翻译的各种状态：

• none：无翻译状态
• translating：翻译中
• success：翻译成功
• failed：翻译失败

翻译事件监听

可以通过设置 RCIMIWEngine 的监听器属性来监听翻译相关的事件。

设置翻译事件监听器

Dart

// 设置翻译事件监听
// 假设您已经创建并保存了引擎实例
RCIMIWEngine? engine = yourEngineInstance; // 替换为您的引擎实例

// 批量翻译完成回调
engine?.onTranslationDidFinished = (List<RCIMIWTranslateItem> translateItems) {
  for (RCIMIWTranslateItem item in translateItems) {
    if (item.errorCode == 0) {
      // 翻译成功，获取翻译结果
      RCIMIWTranslateInfo? info = item.translateInfo;
      if (info != null) {
        String? translatedText = info.translatedText;
        String? targetLanguage = info.targetLanguage;
        RCIMIWTranslateStatus? status = info.status;
        print('翻译成功: $translatedText (目标语言: $targetLanguage, 状态: $status)');
      }
    } else {
      print('翻译失败，错误码：${item.errorCode}');
    }
  }
};

// 用户级翻译语言变更通知
engine?.onTranslationLanguageChanged = (String language) {
  print('翻译语言已变更为: $language');
};

// 用户级自动翻译状态变更通知
engine?.onAutoTranslateStateChanged = (bool isEnable) {
  print('自动翻译状态已变更为: $isEnable');
};

// 会话翻译策略变更通知
engine?.onConversationTranslationStrategySynced = (
  RCIMIWConversationType? type,
  String? targetId,
  String? channelId,
  RCIMIWTranslateStrategy? strategy
) {
  print('会话翻译策略已同步: type=$type, targetId=$targetId, strategy=$strategy');
};