翻译功能

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

开启翻译服务

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

消息翻译结果

RCIMIWTextMessage 新增了 translateInfo 属性，用于存储翻译结果信息。

RCIMIWTranslateInfo 属性说明

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

翻译状态枚举

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

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

示例代码

Dart

// 检查文本消息是否有翻译信息
if (message.content is RCIMIWTextMessage) {
  RCIMIWTextMessage textMessage = message.content as RCIMIWTextMessage;
  RCIMIWTranslateInfo? translateInfo = textMessage.translateInfo;
  
  if (translateInfo != null) {
    switch (translateInfo.status) {
      case RCIMIWTranslateStatus.success:
        // 翻译成功，可以显示翻译结果
        String? translatedText = translateInfo.translatedText;
        String? targetLanguage = translateInfo.targetLanguage;
        print('翻译成功: $translatedText (目标语言: $targetLanguage)');
        break;
      case RCIMIWTranslateStatus.translating:
        // 翻译中，显示加载状态
        print('翻译中...');
        break;
      case RCIMIWTranslateStatus.failed:
        // 翻译失败，显示错误信息
        print('翻译失败');
        break;
      default:
        break;
    }
  }
}

会话翻译策略

RCIMIWConversation 新增了 translateStrategy 属性，用于标识会话级别的翻译策略。

会话翻译策略属性

属性	类型	说明
translateStrategy	RCIMIWTranslateStrategy?	会话的翻译策略

翻译策略枚举

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

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

示例代码

Dart

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

批量翻译文本消息

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

参数说明

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

示例代码

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;

翻译请求发送成功后，翻译的结果会通过翻译监听器中的 onTranslateFinished(List<RCIMIWTranslateItem> translateItems) 方法回调给用户。

批量翻译文本内容

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

参数说明

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

示例代码

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;

翻译请求发送成功后，翻译的结果会通过翻译监听器中的 onTranslateFinished(List<RCIMIWTranslateItem> translateItems) 方法回调给用户。

设置翻译语言

通过 setTranslationLanguage 接口可以设置用户级别的翻译语言。

参数说明

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

信息

设置的 language，请使用开发者文档中支持的语言设置。

示例代码

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;

在多端登录的情况下，该方法设置的结果会通过翻译监听器中的 onTranslationLanguageChanged(String language) 方法通知其他端。

获取翻译语言

通过 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;

设置自动翻译开关

通过 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;

在多端登录的情况下，该方法设置的结果会通过翻译监听器中的 onAutoTranslateStateChanged(bool isEnable) 方法通知其他端。

获取自动翻译开关状态

通过 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;

批量设置会话翻译策略

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

参数说明

参数	类型	说明
types	List<int>	会话类型数组
targetIds	List<String>	会话目标ID数组
channelIds	List<String>	频道ID数组
strategy	RCIMIWTranslateStrategy	翻译策略
callback	IRCIMIWTranslateResponseCallback?	结果回调

示例代码

Dart

List<int> types = [RCIMIWConversationType.private.index];
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;

在多端登录的情况下，该方法设置的结果会通过翻译监听器中的 onConversationTranslationStrategySynced 方法通知其他端。

翻译事件监听

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

设置翻译事件监听器

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

示例代码

Dart

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

// 翻译完成监听
engine?.onTranslateFinished = (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');
};

注意事项

• 翻译结果会通过翻译监听器方法异步返回。
• 建议在使用翻译功能前先设置翻译语言，否则使用默认语言（中文）进行翻译。
• 单次翻译请求的消息或文本数量限制为 1-10 条。
• 翻译模式分为机械翻译 (RCIMIWTranslateMode.mechanical) 和智能翻译 (RCIMIWTranslateMode.intelligent) 两种。