Translation

The Nexconn SDK supports translating text messages and plain text content. You can configure a user-level translation language and auto-translate state, and set per-channel translation strategies.

The SDK provides two batch translation APIs:

• translateMessages — Translates TextMessage content.
• translateTexts — Translates arbitrary text content.

tip

Translation requires a network connection. Ensure the device is online. Batch translation may take time, and the API does not return results directly. Register a TranslateHandler listener to receive translation results.

User-level global settings

Global settings apply to all devices logged in with the same user. When set on one device, other devices receive change notifications through the TranslateHandler event listener.

Set the translation language

Set the user-level target translation language. See Supported languages and codes for available language codes. The default target language is Chinese (zh).

Kotlin

kotlin

NCEngine.translateModule.setTranslationLanguage("zh") { error ->
    if (error == null) {
        // Set successfully
    }
}

Java

Java

NCEngine.translateModule.setTranslationLanguage("zh", error -> {
    if (error == null) {
        // Set successfully
    }
});

Get the translation language

Retrieve the current user-level target translation language.

Kotlin

kotlin

NCEngine.translateModule.getTranslationLanguage { language, error ->
    if (error == null && language != null) {
        println("Current translation language: $language")
    }
}

Java

Java

NCEngine.translateModule.getTranslationLanguage((language, error) -> {
    if (error == null && language != null) {
        System.out.println("Current translation language: " + language);
    }
});

Set the auto-translate flag

Note

The Nexconn SDK does not include built-in auto-translate functionality. This API only stores the on/off state and syncs it across devices for your app's business logic.

Kotlin

kotlin

NCEngine.translateModule.setAutoTranslateEnabled(true) { error ->
    if (error == null) {
        // Set successfully
    }
}

Java

Java

NCEngine.translateModule.setAutoTranslateEnabled(true, error -> {
    if (error == null) {
        // Set successfully
    }
});

Get the auto-translate flag

Kotlin

kotlin

NCEngine.translateModule.getAutoTranslateEnabled { isEnabled, error ->
    if (error == null && isEnabled != null) {
        println("Auto-translate enabled: $isEnabled")
    }
}

Java

Java

NCEngine.translateModule.getAutoTranslateEnabled((isEnabled, error) -> {
    if (error == null && isEnabled != null) {
        System.out.println("Auto-translate enabled: " + isEnabled);
    }
});

Listen for global setting changes

Multi-device sync for global settings (translation language and auto-translate state) is delivered through TranslateHandler callbacks: onTranslationLanguageChanged and onAutoTranslateStateChanged. See Listen for translation events.

Channel-level translation strategy

Note

The Nexconn SDK does not include built-in auto-translate functionality. This API only stores the on/off state and syncs it across devices for your app's business logic.

The Nexconn SDK supports channel-level configuration, allowing you to set a separate auto-translate strategy for each channel. Channel-level settings apply to all devices logged in with the same user.

TranslateStrategy enum

TranslateStrategy values:

• DEFAULT — Follow the user-level auto-translate setting.
• AUTO_ON — Auto-translate messages in this channel.
• AUTO_OFF — Do not auto-translate messages in this channel.

Get the channel translation strategy

After obtaining a channel object, read its translateStrategy property.

Kotlin

kotlin

val channel = DirectChannel("userId")
channel.reload { updatedChannel, error ->
    if (error == null && updatedChannel != null) {
        when (updatedChannel.translateStrategy) {
            TranslateStrategy.DEFAULT -> {
                // Follows user-level setting
            }
            TranslateStrategy.AUTO_ON -> {
                // Auto-translate enabled for this channel
            }
            TranslateStrategy.AUTO_OFF -> {
                // Auto-translate disabled for this channel
            }
        }
    }
}

Java

Java

DirectChannel channel = new DirectChannel("userId");
channel.reload((updatedChannel, error) -> {
    if (error == null && updatedChannel != null) {
        TranslateStrategy strategy = updatedChannel.getTranslateStrategy();
        switch (strategy) {
            case DEFAULT:
                // Follows user-level setting
                break;
            case AUTO_ON:
                // Auto-translate enabled for this channel
                break;
            case AUTO_OFF:
                // Auto-translate disabled for this channel
                break;
        }
    }
});

Set the channel translation strategy

Kotlin

kotlin

val identifiers = listOf(
    ChannelIdentifier(ChannelType.DIRECT, "targetId")
)

NCEngine.translateModule.setTranslateStrategy(identifiers, TranslateStrategy.AUTO_ON) { error ->
    if (error == null) {
        // Set successfully
    }
}

Java

Java

List<ChannelIdentifier> identifiers = new ArrayList<>();
identifiers.add(new ChannelIdentifier(ChannelType.DIRECT, "targetId"));

NCEngine.translateModule.setTranslateStrategy(identifiers, TranslateStrategy.AUTO_ON, error -> {
    if (error == null) {
        // Set successfully
    }
});

Listen for channel strategy changes

With multi-device login, channel translation strategy changes sync to other devices through the ChannelHandler.

Kotlin

kotlin

NCEngine.addChannelHandler("TranslateStrategyHandler", object : ChannelHandler {
    override fun onChannelTranslateStrategySync(event: ChannelTranslateStrategySyncEvent) {
        println("Channel ${event.channelIdentifier.channelId} translation strategy synced to: ${event.strategy}")
    }
})

Java

Java

NCEngine.addChannelHandler("TranslateStrategyHandler", new ChannelHandler() {
    @Override
    public void onChannelTranslateStrategySync(@NonNull ChannelTranslateStrategySyncEvent event) {
        System.out.println("Channel translation strategy synced: " + event.getStrategy());
    }
});

Translate multiple text messages

Use NCEngine.translateModule.translateMessages() to translate multiple text messages in one request.

info

• Each request supports 1–10 messages.
• Translation results are returned asynchronously. Register a translation listener to receive them.

Parameters

Parameter	Type	Description
params	TranslateMessagesParams	Translation parameters
handler	ErrorHandler	Result callback

TranslateMessagesParams

Property	Type	Description
list	List<TranslateMessageParam>	List of message translation parameters. Length: [1, 10].
force	Boolean	Ignore cached results and force re-translation. Default: false.
mode	TranslateMode	Translation mode. Currently only TranslateMode.MECHANICAL (fast translation) is supported.

TranslateMessageParam

Property	Type	Description
messageId	String	Unique message identifier (required). Pass message.messageId.
sourceLanguage	String	Source language. Default: "auto" (auto-detection).
targetLanguage	String?	Target language. null uses the user-level language setting.

Code example

Kotlin

kotlin

val messageParams = listOf(
    TranslateMessageParam(message.messageId ?: "").apply {
        targetLanguage = "zh"
        sourceLanguage = "en"
    }
)

val params = TranslateMessagesParams(messageParams).apply {
    mode = TranslateMode.MECHANICAL
    force = true
}

NCEngine.translateModule.translateMessages(params) { error ->
    if (error == null) {
        // Translation request sent
    }
}

Java

Java

List<TranslateMessageParam> messageParams = new ArrayList<>();

TranslateMessageParam param = new TranslateMessageParam(message.getMessageId());
param.setTargetLanguage("zh");
param.setSourceLanguage("en");
messageParams.add(param);

TranslateMessagesParams params = new TranslateMessagesParams(messageParams);
params.setMode(TranslateMode.MECHANICAL);
params.setForce(true);

NCEngine.translateModule.translateMessages(params, error -> {
    if (error == null) {
        // Translation request sent
    }
});

Translate multiple text strings

Use NCEngine.translateModule.translateTexts() to translate multiple text strings in one request.

info

• Each request supports 1–10 text items.
• Translation results are returned asynchronously. Register a translation listener to receive them.

Parameters

Parameter	Type	Description
params	TranslateTextsParams	Translation parameters
handler	ErrorHandler	Result callback

TranslateTextsParams

Property	Type	Description
list	List<TranslateTextParam>	List of text translation parameters. Length: [1, 10].
mode	TranslateMode	Translation mode. Currently only TranslateMode.MECHANICAL (fast translation) is supported.

TranslateTextParam

Property	Type	Description
text	String	Text content to translate (required).
sourceLanguage	String	Source language. Default: "auto" (auto-detection).
targetLanguage	String	Target language. Empty to use the global setting.

Kotlin

kotlin

val textParams = listOf(
    TranslateTextParam("Hello, World!").apply {
        targetLanguage = "zh"
        sourceLanguage = "en"
    }
)

val params = TranslateTextsParams(textParams).apply {
    mode = TranslateMode.MECHANICAL
}

NCEngine.translateModule.translateTexts(params) { error ->
    if (error == null) {
        // Translation request sent
    }
}

Java

Java

List<TranslateTextParam> textParams = new ArrayList<>();

TranslateTextParam param = new TranslateTextParam("Hello, World!");
param.setTargetLanguage("zh");
param.setSourceLanguage("en");
textParams.add(param);

TranslateTextsParams params = new TranslateTextsParams(textParams);
params.setMode(TranslateMode.MECHANICAL);

NCEngine.translateModule.translateTexts(params, error -> {
    if (error == null) {
        // Translation request sent
    }
});

Listen for translation results

Translation results are returned asynchronously through the TranslateHandler.onTranslationCompleted method. The TextMessage object's translateInfo property is also updated automatically.

Translation result data structures

TranslateResult

Property	Type	Description
identifier	String	Translation identifier (message UID or content hash)
error	NCError?	Error info. null indicates success.
translateInfo	TranslateInfo?	Translation result

TranslateInfo

Property	Type	Description
translatedText	String	Translated content
status	TranslateStatus	Translation status
targetLanguage	String	Target language

TranslateStatus enum

• NONE — No translation status
• TRANSLATING — Translation in progress
• SUCCESS — Translation succeeded
• FAILED — Translation failed

Listen for translation events

info

• All translation event callbacks are delivered through TranslateHandler asynchronously.
• Remove translation listeners at the appropriate time to avoid memory leaks.

Add a translation event listener

Use NCEngine.addTranslateHandler() to register a translation event listener.

Kotlin

kotlin

NCEngine.addTranslateHandler("TranslateListener", object : TranslateHandler {
    override fun onTranslationCompleted(event: TranslationCompletedEvent) {
        event.results.forEach { result ->
            if (result.error == null) {
                val info = result.translateInfo
                println("Translation result: ${info?.translatedText}")
                println("Target language: ${info?.targetLanguage}")
                println("Status: ${info?.status}")
            } else {
                println("Translation failed: ${result.error?.message}")
            }
        }
    }

    override fun onTranslationLanguageChanged(event: TranslationLanguageChangedEvent) {
        println("Translation language changed to: ${event.language}")
    }

    override fun onAutoTranslateStateChanged(event: AutoTranslateStateChangedEvent) {
        println("Auto-translate state: ${event.isEnabled}")
    }
})

Java

Java

NCEngine.addTranslateHandler("TranslateListener", new TranslateHandler() {
    @Override
    public void onTranslationCompleted(@NonNull TranslationCompletedEvent event) {
        for (TranslateResult result : event.getResults()) {
            if (result.getError() == null) {
                TranslateInfo info = result.getTranslateInfo();
                if (info != null) {
                    System.out.println("Translation result: " + info.getTranslatedText());
                    System.out.println("Target language: " + info.getTargetLanguage());
                    System.out.println("Status: " + info.getStatus());
                }
            } else {
                System.out.println("Translation failed: " + result.getError().getMessage());
            }
        }
    }

    @Override
    public void onTranslationLanguageChanged(@NonNull TranslationLanguageChangedEvent event) {
    }

    @Override
    public void onAutoTranslateStateChanged(@NonNull AutoTranslateStateChangedEvent event) {
    }
});

Remove a translation event listener

Use NCEngine.removeTranslateHandler() to remove a translation event listener.

Kotlin

kotlin

NCEngine.removeTranslateHandler("TranslateListener")

Java

Java

NCEngine.removeTranslateHandler("TranslateListener");