跳到主要内容

消息文本翻译

IMLib SDK（融云即时通讯能力库）自 5.24.0 版本起，内置了翻译功能。与原有 IM 翻译插件不同，内置翻译功能不限于新加坡数据中心，且无需额外安装依赖。

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

提示

批量翻译内容可能耗时较长，接口不会直接返回翻译结果。请通过监听 Events.TRANSLATE_RESPONSE 事件获取翻译内容。由于服务有并发限制，同一批次的翻译内容会分批下发，事件也会多次触发。

开启翻译服务​

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

用户级全局设置​

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

设置翻译目标语言​

调用 setTranslationLanguage设置全局目标翻译语言。未设置时，默认目标语言为中文（zh）。

JavaScript
RongIMLib
  .setTranslationLanguage('en')
  .then((res) => {
    if (res.isOk) {
      console.log('设置成功');
    } else {
      console.log('设置失败：', res.code);
    }
  })

查询翻译目标语言​

调用 getTranslationLanguage 查询当前全局默认的目标语言。

JavaScript
RongIMLib
  .getTranslationLanguage()
  .then((res) => {
    if (res.isOk) {
      console.log('查询成功，当前目标语言配置：', res.data);
    } else {
      console.log('查询失败：', res.code);
    }
  })

设置自动翻译开关​

注意

该设置仅对 IMKit SDK 生效。IMLib SDK 本身不包含自动翻译功能，仅用于向 IMKit SDK 提供开关存储和多端状态同步。

调用 setAutoTranslateEnabled 配置用户级自动翻译开关。

JavaScript
RongIMLib
  .setAutoTranslateEnabled(true)
  .then((res) => {
    if (res.isOk) {
      console.log('设置成功');
    } else {
      console.log(`设置失败：${res.code}`);
    }
  })

查询自动翻译开关​

调用 getAutoTranslateEnabled 查询当前用户级自动翻译开关状态。

JavaScript
RongIMLib
  .getAutoTranslateEnabled()
  .then((res) => {
    if (res.isOk) {
      console.log('查询成功，当前开关状态：', res.data ? '开启' : '关闭');
    } else {
      console.log('查询失败：', res.code);
    }
  })

监听全局配置变更​

通过事件监听全局配置变更。

JavaScript
RongIMLib.addEventListener(Events.USER_SETTINGS_CHANGED, (evt) => {
  switch (evt.key) {
    case RongIMLib.UserSettingsChangedKey.TranslationLanguage:
      console.log(`默认翻译语言变更：${evt.value}`);
      break;
    case RongIMLib.UserSettingsChangedKey.AutoTranslateEnable:
      console.log(`自动翻译开关变更：${evt.value}`);
      break;
  }
});

会话级自动翻译开关配置​

注意

该设置仅对 IMKit SDK 生效。IMLib SDK 本身不包含自动翻译功能，仅用于开关存储和多端状态同步。

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

设置自动翻译策略​

调用 batchSetConversationTranslateStrategy 可同时对多个会话设置翻译策略。

枚举定义值说明
TranslateStrategy.DEFAULT0默认，按用户级全局开关配置
TranslateStrategy.AUTO_ON1开启会话内消息自动翻译
TranslateStrategy.AUTO_OFF2关闭会话内消息自动翻译
JavaScript
const conversations = [
  { conversationType: RongIMLib.ConversationType.PRIVATE, targetId: '<会话 TargetId>' },
];

const strategy = RongIMLib.TranslateStrategy.AUTO_ON;

RongIMLib
  .batchSetConversationTranslateStrategy(conversations, strategy)
  .then((res) => {
    if (res.isOk) {
      console.log('设置成功');
    } else {
      console.log(`设置失败：${res.code}`);
    }
  });

查询自动翻译策略​

获取会话数据后，可通过 translateStrategy 属性读取当前策略。

监听会话状态变更​

JavaScript
RongIMLib.addEventListener(Events.CONVERSATION, ({ conversationList }) => {
  conversationList.forEach((item) => {
    const { conversation, updatedItems } = item;
    if (updatedItems.translateStrategy) {
      console.log('会话自动翻译策略变更：', updatedItems.translateStrategy.val)
    }
  });
});

翻译文本消息​

如需翻译文本消息，构建 TranslateMessageParam 类型参数。该对象的 identifier 属性为消息的 messageUId，用于后续匹配 Events.TRANSLATE_RESPONSE 事件回调的翻译结果。

JavaScript
const msgParam = new TranslateMessageParam(
  '<messaegUId>',
  '', // sourceLanguage，即未翻译前的语种，选填
  '', // targetLanguage，翻译目标语言，若不传则使用用户级全局配置
  '[content]' // 消息内容，非 Electron 平台需要传递该参数，Electron 平台下该参数无效
)
console.log('identifier:', msgParam.identifier);

调用 translateMessagesWithParams 可批量翻译文本消息。参数定义参考 [TranslateMessagesParams]。

JavaScript
const params = {
  list: [ msgParam ], // 支持同时翻译多条文本消息，最多一次翻译 10 条
  force: false,  // 可选填，用于在已存在翻译结果缓存的情况下，忽略缓存重新翻译
  mode: RongIMLib.TranslateMode.MECHANICAL, // 可选填，当前版本仅支持机器翻译
};
RongIMLib
  .translateMessagesWithParams(params)
  .then((res) => {
    if (res.isOk) {
      console.log('翻译请求发送成功，结果将通过 Events.TRANSLATE_RESPONSE 事件返回');
    } else {
      console.log('翻译请求发送失败', res.code);
    }
  });

翻译任意文本​

如需翻译任意文字内容，构建 TranslateTextParam 类型参数。其 identifier 属性用于匹配 Events.TRANSLATE_RESPONSE 事件回调的翻译结果。

JavaScript
const textParam = new TranslateTextParam(
  '<待翻译内容>', // 单条内容不可超过 1024 个字符
  '', // sourceLanguage，即未翻译前的语种，选填
  '', // targetLanguage，翻译目标语言，若不传则使用用户级全局配置
)
console.log('identifier:', textParam.identifier);

调用 translateTextsWithParams 可批量翻译任意文本。参数定义参考 [TranslateTextsParams]。

JavaScript
const params = {
  list: [ textParam ], // 支持同时翻译多条内容，最多一次翻译 10 条
  mode: RongIMLib.TranslateMode.MECHANICAL, // 可选填，当前版本仅支持机器翻译
};
RongIMLib
  .translateTextsWithParams(params)
  .then((res) => {
    if (res.isOk) {
      console.log('翻译请求发送成功，结果将通过 Events.TRANSLATE_RESPONSE 事件返回');
    } else {
      console.log('翻译请求发送失败', res.code);
    }
  });

监听翻译结果​

翻译结果通过 Events.TRANSLATE_RESPONSE 事件异步返回，回调参数为 TranslateItem 列表。

JavaScript
RongIMLib.addEventListener(Events.TRANSLATE_RESPONSE, (list) => {
  list.forEach(item => {
    console.log('信息来源：', item.from) // 0 为文本消息翻译结果，1 为文字翻译结果
    console.log('内容标识：', item.idenfitier); // 用于业务层匹配翻译内容
    console.log('翻译状态码：', item.code); // 0 表示翻译成功

    if (item.code === ErrorCode.SUCCESS) {
      const { targetLanguage, translatedText } = item.translateInfo;
      console.log('翻译结果：', translatedText)
      console.log('翻译目标语言：', targetLanguage)
    }
  });
});
最后于 更新