消息文本翻译

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

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

• translateMessagesWithParams:completionHandler:：用于翻译文本消息（RCTextMessage）内容。
• translateTextsWithParams:completionHandler:：用于翻译任意文字内容。

提示

翻译功能需网络连接，请确保设备网络通畅。批量翻译内容可能耗时较长，接口不会直接返回翻译结果。请通过设置 RCTranslationDelegate 代理接收翻译内容。

开启翻译服务

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

用户级全局设置

全局设置对同一用户的所有登录设备生效。一端设置后，其他设备可通过 RCTranslationDelegate 代理获得变更通知。

设置翻译目标语言

通过 setTranslationLanguage:completionHandler: 接口可设置用户级别的翻译目标语言。支持的语种请参考翻译语言代码列表 。未设置时，默认目标语言为中文（zh）。

参数说明

参数	类型	说明
language	NSString	翻译目标语言的语言代码
completionHandler	Block	结果回调

示例代码

Objective C

    [[RCCoreClient sharedCoreClient] setTranslationLanguage:@"zh"
                                          completionHandler:^(RCErrorCode code) {
        if (code == RC_SUCCESS) {
            // 设置翻译语言成功
        } else {
            // 设置翻译语言失败
        }
    }];

获取翻译语言

通过 getTranslationLanguage:errorBlock: 接口可获取当前用户级别的翻译目标语言。

参数说明

参数	类型	说明
successBlock	Block	成功回调
errorBlock	Block	失败回调

示例代码

Objective C

 [[RCCoreClient sharedCoreClient] getTranslationLanguage:^(NSString * _Nonnull language) {
        // 获取翻译语言成功
        NSLog(@"当前翻译语言: %@", language);
    } errorBlock:^(RCErrorCode errorCode) {
        // 获取翻译语言失败
        NSLog(@"getTranslationLanguage: code:%ld", errorCode);

    }];

标记自动翻译状态

注意

IMLib SDK 本身不包含自动翻译功能，仅用于向应用的业务逻辑提供开关存储和多端状态同步。

通过 setAutoTranslateState:completionHandler: 接口可标记用户级别的自动翻译状态。

参数说明

参数	类型	说明
isEnable	BOOL	是否标记为自动翻译
completionHandler	Block	结果回调

示例代码

Objective C

    [[RCCoreClient sharedCoreClient] setAutoTranslateState:YES
                                          completionHandler:^(RCErrorCode code) {
        if (code == RC_SUCCESS) {
            // 标记自动翻译状态成功
        } else {
            // 标记自动翻译状态失败
        }
    }];

获取自动翻译状态

通过 getAutoTranslateEnabled:errorBlock: 接口可获取当前用户级别的自动翻译状态。

参数说明

参数	类型	说明
successBlock	Block	成功回调
errorBlock	Block	失败回调

示例代码

Objective C

[[RCCoreClient sharedCoreClient] getAutoTranslateEnabled:^(BOOL isEnable) {
 // 获取自动翻译状态成功
        NSLog(@"getAutoTranslateEnabled: %d", isEnable);
    } errorBlock:^(RCErrorCode errorCode) {
    // 获取自动翻译状态失败
        NSLog(@"getAutoTranslateEnabled code:%ld", errorCode);
    }];

监听全局配置变更

全局设置（翻译语言、自动翻译状态）的多端同步，通过 RCTranslationDelegate 的 translationLanguageDidChange: 和 autoTranslateStateDidChange: 回调。详见翻译事件监听。

会话级翻译策略

注意

IMLib SDK 本身不包含自动翻译功能，仅用于向应用的业务逻辑提供开关存储和多端状态同步。

会话级配置对同一用户的所有设备生效，变更后其他设备可通过 RCConversationStatusChangeDelegate 获取通知。

设置会话翻译策略

通过 batchSetConversationTranslateStrategy:strategy:completionHandler: 接口可批量设置会话翻译策略。

翻译策略枚举

RCTranslateStrategy 枚举：

• RCTranslateStrategyDefault：默认策略，跟随用户级别自动翻译设置。
• RCTranslateStrategyAutoOn：自动翻译，会话内消息自动翻译。
• RCTranslateStrategyAutoOff：手动翻译，会话内消息不自动翻译。

示例代码

Objective C

    RCConversationIdentifier *identifier = [[RCConversationIdentifier alloc] init];
    identifier.type = ConversationType_PRIVATE;
    identifier.targetId = @"targetId";
    
    [[RCCoreClient sharedCoreClient] batchSetConversationTranslateStrategy:@[identifier]
                                                                   strategy:RCTranslateStrategyAuto
                                                          completionHandler:^(RCErrorCode code) {
        if (code == RC_SUCCESS) {
            // 设置会话翻译策略成功
        } else {
            // 设置会话翻译策略失败
        }
    }];

查询会话翻译策略

获取会话对象 RCConversation 后，可通过其 translateStrategy 属性读取当前策略。

示例代码

Objective C

    // 检查会话的翻译策略
    RCConversation *conversation = ...;
    switch (conversation.translateStrategy) {
        case RCTranslateStrategyDefault:
            // 使用默认策略，跟随用户级别设置
            break;
        case RCTranslateStrategyAutoOn:
            // 该会话开启自动翻译
            break;
        case RCTranslateStrategyAutoOff:
            // 该会话关闭自动翻译
            break;
    }

监听会话状态变更

多端登录时，设置结果会通过 RCConversationStatusChangeDelegate 代理中的- (void)conversationStatusDidChange:(NSArray<RCConversationStatusInfo *> *)conversationStatusInfos;方法通知其他端，其中，RCConversationStatusInfo的conversationStatusType 将被设置为RCConversationStatusType_Translation, conversationStatusValue则对应当前会话的翻译策略。

批量翻译文本消息

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

参数说明

参数	类型	说明
params	RCTranslateMessagesParams	翻译的消息参数 (list 数组最多包含 10 条翻译内容)
completionHandler	Block	结果回调

RCTranslateMessagesParams 属性说明

属性	类型	说明
list	NSArray<RCTranslateMessagesParam *>	待翻译的消息参数数组。数组长度限制为 1 到 10。
force	boolean	是否强制重新翻译，并忽略已有的翻译缓存。默认为 NO。
mode	RCTranslateMode	翻译模式。目前仅支持高速翻译（RCTranslateModeMechanical）。

示例代码

Objective C

NSMutableArray *array =[NSMutableArray array];

RCTranslateMessageParam *param = [RCTranslateMessageParam new];

// 翻译的语言，为空时，使用配置的全局语言。
param.targetLanguage = @"zh";

/// 消息内容的语言，为空时，会自动识别。
param.sourceLanguage = @"en";
param.messageUId = @"messageUId";
[array addObject:param];

RCTranslateMessagesParams *params = [RCTranslateMessagesParams new];
/// 待翻译消息信息数组，最多 10 条消息。
params.list = array;

// 翻译模式，默认为 `RCTranslateModeMechanical`。
params.mode = RCTranslateModeMechanical;

// 是否强制重新翻译，默认为 NO。
params.force = YES;

    [[RCCoreClient sharedCoreClient] translateMessagesWithParams:params
                                               completionHandler:^(RCErrorCode code) {
        if (code == RC_SUCCESS) {
            // 翻译请求发送成功
        } else {
            // 翻译请求发送失败
        }
    }];

批量翻译文本内容

通过 translateTextsWithParams:completionHandler: 接口可批量翻译任意文本内容。

参数说明

参数	类型	说明
params	RCTranslateTextsParams	翻译文本参数 (list 数组最多包含 10 条翻译内容)
completionHandler	Block	结果回调

RCTranslateTextsParams 属性说明

属性	类型	说明
list	NSArray<RCTranslateTextsParam *>	待翻译的文本内容参数数组。数组长度限制为 1 到 10。
mode	RCTranslateMode	翻译模式。目前仅支持高速翻译（RCTranslateModeMechanical）。

示例代码

Objective C

NSMutableArray *array =[NSMutableArray array];

RCTranslateTextParam *param = [RCTranslateTextParam new];

// 翻译的语言，为空时，使用配置的全局语言。
param.targetLanguage = @"zh";

/// 消息内容的语言，为空时，会自动识别。
param.sourceLanguage = @"en";
param.text = @"content";
[array addObject:param];

RCTranslateTextsParams *params = [[RCTranslateTextsParams alloc] init];
// 待翻译消息信息数组，最多 10 条内容。
params.list = array;
    
// 翻译模式，默认为 `RCTranslateModeMechanical`。
params.mode = RCTranslateModeMechanical;

    [[RCCoreClient sharedCoreClient] translateTextsWithParams:params
                                             completionHandler:^(RCErrorCode code) {
        if (code == RC_SUCCESS) {
            // 翻译请求发送成功
        } else {
            // 翻译请求发送失败
        }
    }];

监听翻译结果

翻译结果通过 RCTranslationDelegate 代理的 - (void)translationDidFinished:(NSArray<RCTranslateItem *> *)items 方法异步返回。同时，应用层可通过RCTranslateItem对象更新对应的数据源。

翻译结果数据结构

RCTranslateItem

- (void)translationDidFinished: 回调返回 RCTranslateItem 列表。

属性	类型	说明
identifier	NSString	翻译内容标识：消息的 UId 或内容的 hash。
code	RCErrorCode	翻译结果的状态码。
translateInfo	RCTranslateInfo	翻译结果信息。
from	RCTranslateResultType	翻译来源：消息或自定义文本。

RCTranslateInfo

RCTextMessage 的 translateInfo 属性以及 RCTranslateItem 中的 translateInfo 属性，都使用 RCTranslateInfo 对象存储翻译结果。

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

翻译状态枚举

RCTranslateStatus 枚举，定义了翻译的如下状态：

• RCTranslateStatusNone：无翻译状态
• RCTranslateStatusTranslating：翻译中
• RCTranslateStatusSuccess：翻译成功
• RCTranslateStatusFailed：翻译失败

翻译事件监听

信息

• 翻译相关的事件回调都通过 RCTranslationDelegate 异步返回。

添加翻译事件代理

通过 addTranslationDelegate: 接口可以添加翻译事件代理。

示例代码

Objective C

    // 添加翻译事件监听
    [[RCCoreClient sharedCoreClient] addTranslationDelegate:self];
    
    // 在代理方法中处理翻译事件
    - (void)translationDidFinished:(NSArray<RCTranslateItem *> *)items {
        // 批量翻译完成回调
    }

    - (void)translationLanguageDidChange:(NSString *)language {
        // 用户级翻译语言变更通知
    }

    - (void)autoTranslateStateDidChange:(BOOL)isEnable {
        // 用户级自动翻译状态变更通知
    }

移除翻译事件代理

通过 removeTranslationDelegate: 接口可以移除翻译事件代理。

示例代码

Objective C

    // 移除翻译事件监听
    [[RCCoreClient sharedCoreClient] removeTranslationDelegate:self];