消息翻译

小于 1 分钟

消息翻译

功能说明

为方便用户在聊天过程中 翻译文本消息，环信即时通讯 IM SDK 集成了 Microsoft Azure Translation API，支持以下两种方式：

  • 按需翻译：接收方收到文本消息后，将消息内容翻译为目标语言。
  • 自动翻译：发送方设置目标语言后，SDK 在发送消息前翻译文本，将原文和译文一起发送给接收方。

如下为按需翻译示例：

功能开通

消息翻译为增值服务，使用前请先在 环信控制台开通。

单次翻译请求最多支持 10,000 个字符。计费字符数按 源文本字符数 × 目标语言数量 计算。例如，将 500 个字符翻译为 4 种语言，计费字符数为 2,000。

该服务的费用详见 计费策略 。

前提条件

获取翻译服务支持的语言

你可以调用 fetchSupportLanguages() 查询翻译服务支持的语言，并从返回结果中选取目标语言编码。无论是按需翻译还是自动翻译，都需要在翻译前确认目标语言受支持。

已知有效语言编码时，无需在每次翻译前重复查询。

EMClient.getInstance().chatManager().fetchSupportLanguages(
    new EMValueCallBack<List<EMLanguage>>() {
        @Override
        public void onSuccess(List<EMLanguage> languages) {
            for (EMLanguage language : languages) {
                Log.d("Translation", language.LanguageCode + ": " + language.LanguageName);
            }
        }

        @Override
        public void onError(int code, String description) {
            Log.e("Translation", code + ": " + description);
        }
    });

fetchSupportLanguages() 的成功回调返回 List<EMLanguage>。以下字段名的首字母为大写：

字段类型描述
LanguageCodeString语言编码，例如 zh-Hans。
LanguageNameString语言名称。
LanguageLocalNameString该语言的本地显示名称。

按需翻译

接收方调用 translateMessage() 翻译收到的文本消息。翻译成功后，从回调返回消息的文本消息体中读取译文。按需翻译不会将译文自动发送给对端。

以下 message 为收到的普通文本消息：

List<String> languages = Arrays.asList("en", "ja");
EMClient.getInstance().chatManager().translateMessage(
    message, languages, new EMValueCallBack<EMMessage>() {
        @Override
        public void onSuccess(EMMessage translatedMessage) {
            EMTextMessageBody body = (EMTextMessageBody) translatedMessage.getBody();
            for (EMTextMessageBody.EMTranslationInfo item : body.getTranslations()) {
                Log.d("Translation", item.languageCode + ": " + item.translationText);
            }
        }

        @Override
        public void onError(int code, String description) {
            Log.e("Translation", code + ": " + description);
        }
    });

设置自动翻译

创建文本消息时设置目标语言，再发送消息。SDK 会先翻译，再将原文与译文一起发送。

调用文本消息体的 setTargetLanguages() 方法设置目标语言。以下为单聊示例：

EMMessage message = EMMessage.createTextSendMessage("你好", "user2");
EMTextMessageBody body = (EMTextMessageBody) message.getBody();
body.setTargetLanguages(Arrays.asList("en", "ja"));
EMClient.getInstance().chatManager().sendMessage(message);

接收并展示译文

接收方收到文本消息后，可以读取译文并选择展示语言。没有所需语言的译文时，可回退展示原文。

在消息接收回调中，对普通文本消息调用 getTranslations()。以下 receivedMessage 为收到的普通文本消息：

EMTextMessageBody body = (EMTextMessageBody) receivedMessage.getBody();
for (EMTextMessageBody.EMTranslationInfo item : body.getTranslations()) {
    Log.d("Translation", item.languageCode + ": " + item.translationText);
}
// 原文可通过 body.getMessage() 获取。

EMTextMessageBody.getTranslations() 返回 List<EMTextMessageBody.EMTranslationInfo>：

字段类型描述
languageCodeString译文的语言编码。
translationTextString译文文本。

目标语言通过 setTargetLanguages(List<String>) 设置，通过 getTargetLanguages() 获取。

注意事项

  • 翻译仅适用于普通文本消息。v5.x 的 复合消息 不支持按需翻译，也不会自动翻译其中的文本消息体。
  • 翻译失败时，通过 EMValueCallBack.onError() 或消息发送回调获取错误；按需翻译应在 onSuccess() 中读取结果。
  • 如需设置离线推送的展示语言，参见 设置推送翻译 。

常见错误

v4.x 和 v5.x 的以下翻译错误码一致，错误名称以对应平台的错误码文档为准。更多错误参见 v4.x 错误码 和 v5.x 错误码 。

错误码错误信息描述可能原因解决方法
1110TRANSLATE_PARAM_INVALID翻译参数错误。传入的翻译参数不符合接口要求。结合错误描述和 SDK 日志检查翻译接口的参数；目标语言应使用查询接口返回的有效语言编码。
1111TRANSLATE_SERVICE_NOT_ENABLE翻译服务未启用。当前应用尚未开通翻译服务。在 环信控制台open in new window 开通翻译服务后重试。
1112TRANSLATE_USAGE_LIMIT翻译用量达到上限。当前应用的翻译额度已用尽。联系环信商务续费或增加翻译用量后重试。
1113TRANSLATE_MESSAGE_FAIL消息翻译失败。具体原因需结合错误描述和 SDK 日志确认。保留错误码、错误描述和 SDK 日志，排查失败原因；若持续失败，联系技术支持。

接口列表

API所属模块/类说明
fetchSupportLanguagesEMChatManager查询支持的语言。
translateMessageEMChatManager按需翻译普通文本消息。
setTargetLanguages / getTargetLanguagesEMTextMessageBody设置/获取目标语言。
getTranslationsEMTextMessageBody获取译文列表。
上次编辑于:
环信 IM 文档
© 环信 2026