Message translation

The Chat SDK supports translating text messages (TextMessage) and arbitrary text content. You can set a user-level translation language, store an auto-translate preference, configure per-channel translation strategies, and submit translation tasks through NCEngine.translateModule.

tip

Translation requires a network connection. Batch translation requests do not return translated content directly. Register a TranslateHandler to receive translation results and setting-sync events.

User-level global settings

Global settings apply to all devices for the same user. When one device updates a setting, other devices receive a change notification through TranslateHandler.

Set the target language

Call setTranslationLanguage(_:completion:) to set the user-level target language. For supported languages, see Supported languages and codes. The default target language is Chinese (zh).

Swift

swift

import NexconnChatSDK

NCEngine.translateModule.setTranslationLanguage("zh") { error in
    if error == nil {
        print("Target language set successfully.")
    }
}

Objective-C

Objective C

[[NCEngine translateModule] setTranslationLanguage:@"zh"
                                        completion:^(NCError * _Nullable error) {
    if (error == nil) {
        // Target language set successfully
    }
}];

Get the target language

Call getTranslationLanguage(completion:) to retrieve the current user-level target language:

Swift

swift

import NexconnChatSDK

NCEngine.translateModule.getTranslationLanguage { language, error in
    guard let language, error == nil else {
        print("Failed to get translation language: \(error?.localizedDescription ?? "unknown error")")
        return
    }

    print("Current translation language: \(language)")
}

Objective-C

Objective C

[[NCEngine translateModule] getTranslationLanguageWithCompletion:^(NSString * _Nullable language, NCError * _Nullable error) {
    if (error == nil) {
        NSLog(@"Current translation language: %@", language);
    }
}];

Set the auto-translate flag

caution

The Chat SDK does not include built-in auto-translation. This flag only stores and synchronizes your app's auto-translate preference.

Use setAutoTranslateEnabled(_:completion:) to set the user-level auto-translate flag:

Swift

swift

import NexconnChatSDK

NCEngine.translateModule.setAutoTranslateEnabled(true) { error in
    if error == nil {
        print("Auto-translate preference updated.")
    }
}

Objective-C

Objective C

[[NCEngine translateModule] setAutoTranslateEnabled:YES
                                         completion:^(NCError * _Nullable error) {
    if (error == nil) {
        // Auto-translate state set successfully
    }
}];

Get the auto-translate state

Call getAutoTranslateEnabled(completion:) to retrieve the current auto-translate state:

Swift

swift

import NexconnChatSDK

NCEngine.translateModule.getAutoTranslateEnabled { isEnabled, error in
    guard error == nil else {
        print("Failed to get auto-translate state: \(error!.localizedDescription)")
        return
    }

    print("Auto-translate enabled: \(isEnabled)")
}

Objective-C

Objective C

[[NCEngine translateModule] getAutoTranslateEnabledWithCompletion:^(BOOL isEnabled, NCError * _Nullable error) {
    if (error == nil) {
        NSLog(@"Auto-translate enabled: %d", isEnabled);
    }
}];

Channel-level translation strategy

caution

The Chat SDK does not include built-in auto-translation. This setting only stores and synchronizes your app's per-channel preference.

Channel-level settings apply to all devices for the same user. Changes are synced to other devices through ChannelHandler.

Set the channel translation strategy

Call setTranslateStrategy(identifiers:strategy:completion:) to batch-set the translation strategy for channels.

Strategy enum values (NCTranslateStrategy):

• NCTranslateStrategyDefaultStrategy or .defaultStrategy: Follow the user-level auto-translate setting.
• NCTranslateStrategyAutoOn or .autoOn: Auto-translate enabled for this channel.
• NCTranslateStrategyAutoOff or .autoOff: Manual translation only for this channel.

Swift

swift

import NexconnChatSDK

let identifier = ChannelIdentifier(channelType: .direct, channelId: "targetId")

NCEngine.translateModule.setTranslateStrategy(
    identifiers: [identifier],
    strategy: .autoOn
) { error in
    if error == nil {
        print("Channel translate strategy updated.")
    }
}

Objective-C

Objective C

NCChannelIdentifier *identifier = [[NCChannelIdentifier alloc] initWithChannelType:NCChannelTypeDirect
                                                                          channelId:@"targetId"];

[[NCEngine translateModule] setTranslateStrategyWithIdentifiers:@[identifier]
                                                       strategy:NCTranslateStrategyAutoOn
                                                     completion:^(NCError * _Nullable error) {
    if (error == nil) {
        // Strategy set successfully
    }
}];

Submit translation tasks

Translate messages

Use translateMessages(params:completion:) to batch-translate up to 10 text messages:

Swift

swift

import NexconnChatSDK

let item = TranslateMessageParam(messageId: "messageId", targetLanguage: "en")
let params = TranslateMessagesParams(list: [item], force: false, mode: .mechanical)

NCEngine.translateModule.translateMessages(params: params) { error in
    if error == nil {
        print("Translation request submitted.")
    }
}

Objective-C

Objective C

NCTranslateMessageParam *item = [[NCTranslateMessageParam alloc] initWithMessageId:@"messageId"
                                                                     targetLanguage:@"en"];
NCTranslateMessagesParams *params = [[NCTranslateMessagesParams alloc] initWithList:@[item]
                                                                              force:NO
                                                                               mode:NCTranslateModeMechanical];

[[NCEngine translateModule] translateMessagesWithParams:params
                                             completion:^(NCError * _Nullable error) {
    if (error == nil) {
        // Translation request submitted
    }
}];

Translate arbitrary text

Use translateTexts(params:completion:) to batch-translate up to 10 custom text entries:

Swift

swift

import NexconnChatSDK

let item = TranslateTextParam(text: "Hello world", targetLanguage: "ja")
let params = TranslateTextsParams(list: [item], mode: .intelligent)

NCEngine.translateModule.translateTexts(params: params) { error in
    if error == nil {
        print("Text translation request submitted.")
    }
}

Objective-C

Objective C

NCTranslateTextParam *item = [[NCTranslateTextParam alloc] initWithText:@"Hello world"
                                                         targetLanguage:@"ja"];
NCTranslateTextsParams *params = [[NCTranslateTextsParams alloc] initWithList:@[item]
                                                                          mode:NCTranslateModeIntelligent];

[[NCEngine translateModule] translateTextsWithParams:params
                                          completion:^(NCError * _Nullable error) {
    if (error == nil) {
        // Text translation request submitted
    }
}];

Listen for translation events

Register a TranslateHandler to receive multi-device setting sync events and translation completion callbacks.

Swift

swift

import NexconnChatSDK

final class TranslationService: NSObject, TranslateHandler {
    func start() {
        NCEngine.addTranslateHandler(identifier: "MyTranslateHandler", handler: self)
    }

    func stop() {
        NCEngine.removeTranslateHandler(forIdentifier: "MyTranslateHandler")
    }

    func onTranslationLanguageChanged(_ event: TranslationLanguageChangedEvent) {
        print("Translation language changed: \(event.language)")
    }

    func onAutoTranslateStateChanged(_ event: AutoTranslateStateChangedEvent) {
        print("Auto-translate changed: \(event.isEnabled)")
    }

    func onTranslationCompleted(_ event: TranslationCompletedEvent) {
        print("Translation completed: \(event.results.count) items")
    }
}

Objective-C

Objective C

[NCEngine addTranslateHandlerWithIdentifier:@"MyTranslateHandler" handler:self];

- (void)onTranslationLanguageChanged:(NCTranslationLanguageChangedEvent *)event {
    NSLog(@"Translation language changed: %@", event.language);
}

- (void)onAutoTranslateStateChanged:(NCAutoTranslateStateChangedEvent *)event {
    NSLog(@"Auto-translate changed: %d", event.isEnabled);
}

- (void)onTranslationCompleted:(NCTranslationCompletedEvent *)event {
    NSLog(@"Translation completed: %lu items", (unsigned long)event.results.count);
}

[NCEngine removeTranslateHandlerForIdentifier:@"MyTranslateHandler"];