消息翻译

小于 1 分钟

消息翻译

功能说明

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

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

如下为按需翻译示例：

功能开通

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

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

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

前提条件

获取翻译服务支持的语言

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

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

[[EMClient sharedClient].chatManager fetchSupportedLanguages:^(NSArray<EMTranslateLanguage *> *languages, EMError *error) {
    if (error) {
        NSLog(@"查询语言失败：%@", error.errorDescription);
        return;
    }
    for (EMTranslateLanguage *language in languages) {
        NSLog(@"%@：%@", language.languageCode, language.languageName);
    }
}];

fetchSupportedLanguages: 的成功回调返回 NSArray<EMTranslateLanguage *> *：

字段类型描述
languageCodeNSString *语言编码，例如 zh-Hans。
languageNameNSString *语言名称。
languageNativeNameNSString *该语言的原生名称。

按需翻译

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

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

[[EMClient sharedClient].chatManager translateMessage:receivedMessage
    targetLanguages:@[@"en", @"ja"]
    completion:^(EMChatMessage *message, EMError *error) {
        if (error) {
            NSLog(@"翻译失败：%@", error.errorDescription);
            return;
        }
        EMTextMessageBody *body = (EMTextMessageBody *)message.body;
        NSLog(@"英文译文：%@", body.translations[@"en"]);
    }];

设置自动翻译

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

通过文本消息体的 targetLanguages 属性设置目标语言。以下为单聊示例：

EMTextMessageBody *body = [[EMTextMessageBody alloc] initWithText:@"你好"];
body.targetLanguages = @[@"en", @"ja"];
EMChatMessage *message = [[EMChatMessage alloc]
    initWithConversationID:@"user2"
    from:[EMClient sharedClient].currentUsername
    to:@"user2"
    body:body
    ext:nil];
[[EMClient sharedClient].chatManager sendMessage:message
    progress:nil
    completion:^(EMChatMessage *sentMessage, EMError *error) {
        if (error) {
            NSLog(@"发送失败：%@", error.errorDescription);
        }
    }];

接收并展示译文

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

在消息接收回调中，读取普通文本消息体的 translations。以下 receivedMessage 为收到的普通文本消息：

EMTextMessageBody *body = (EMTextMessageBody *)receivedMessage.body;
NSString *displayText = body.translations[@"en"] ?: body.text;
NSLog(@"展示内容：%@", displayText);

EMTextMessageBody.translations 为可空的 NSDictionary<NSString *, NSString *> *：

项目类型描述
键NSString *译文的语言编码，例如 en。
值NSString *对应语言的译文。

body.text 保留原文；body.targetLanguages 为可空的目标语言编码数组 NSArray<NSString *> *。

注意事项

  • 翻译仅适用于普通文本消息。v5.x 的 复合消息 不支持按需翻译，也不会自动翻译其中的文本消息体。
  • 请先判断回调中的 error，再读取翻译或发送结果。
  • 如需设置离线推送的展示语言，参见 设置推送翻译 。

常见错误

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

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

接口列表

API所属模块/类说明
fetchSupportedLanguages:EMChatManager查询支持的语言。
translateMessage:targetLanguages:completion:EMChatManager按需翻译普通文本消息。
targetLanguagesEMTextMessageBody设置/获取目标语言。
translationsEMTextMessageBody获取译文映射。
上次编辑于:
环信 IM 文档
© 环信 2026