====== 翻译 Web ======

更新时间：2022 年 4 月 29 日

文本消息支持翻译功能，包含按需翻译和自动翻译。

  * 按需翻译：收到消息时，接收方将消息内容翻译成目标语言。
  * 自动翻译：用户发送消息时，SDK 根据设置的目标语言自动翻译消息内容，然后将消息原文和译文一并发送给消息接收方。

**注意:**
翻译服务由 Microsoft Azure Translator API 提供支持。可以在 [[https://docs.microsoft.com/en-us/azure/cognitive-services/translator/language-support|Microsoft Azure Translator Language Suppor]] 页面查看目前支持的语言。
===== 前提条件 =====

开始前，请确保满足以下条件：

  - 完成 ''%%4.0.4 以上版本%%'' SDK 初始化，详见 [[ccim:web:quickstart|快速开始]]。
  - 了解环信即时通讯 IM API 的[[https://docs-im.easemob.com/ccim/limitation|使用限制]]。
  - 已联系商务开通翻译功能。

===== 技术原理 =====

Web SDK 支持你通过调用 API 在项目中实现如下功能：

  * ''%%getSupportedLanguages%%''：获取支持的翻译语言；
  * ''%%translateMessage%%''：翻译文本消息；
  * 设置自动翻译。

按需翻译文本消息示例如下：

{{:ccim:web:web_chat_control.png|}}
===== 实现方法 =====

==== 获取翻译服务支持的语言 ====

翻译前需获取翻译服务支持的语言，示例代码如下：

<code javascript>
conn.getSupportedLanguages().then(res => console.log(res))
</code>

==== 翻译消息 ====

先调用 ''%%getSupportedLanguages%%'' 获取每种语言对应 code，然后可以将文本翻译成一种或多种目标语言。

示例代码如下：

<code javascript>
conn.translateMessage('hello', ['zh']).then(res => console.log(res))
</code>

==== 发消息时自动翻译 ====

设置目标语言后，在发送消息时 SDK 会自动将文本翻译为目标语言，并将目标语言一并发送出去。

示例代码如下：

<code javascript>
// 发送消息。
let option = {
    chatType: 'singleChat',
    type: 'txt',
    to: 'userId',
    msg: 'hello',
    msgConfig:{ languages: ['zh'] } // 设置目标语言。
}
let msg = WebIM.message.create(option);
conn.send(msg)

// 接收消息。
conn.addEventHandler('MESSAGE', {
    onTextMessage: (message) => {
        console.log('message', message.translations)
    }
})
</code>