Built-in translation

The Chat SDK supports translating text messages and plain text content. Configure user-level translation language and auto-translate status, or set per-channel translation strategies.

tip

Translation requires a network connection. Requests for multiple items can take time and don't return results directly. Register a TranslateHandler with NCEngine.addTranslateHandler to receive translation results.

User-level settings

Global settings apply across all logged-in devices. Changes sync to other devices via callbacks.

Set translation language

Dart

await NCEngine.translate.setTranslationLanguage('zh', (error) {
  if (error?.isSuccess == true) print('Language set');
});

Get translation language

Dart

await NCEngine.translate.getTranslationLanguage((language, error) {
  if (error == null) print('Language: $language');
});

Set auto-translate status

info

The SDK does not perform auto-translation. It only stores the toggle state and syncs it across devices.

Dart

await NCEngine.translate.setAutoTranslateEnabled(true, (error) {
  if (error?.isSuccess == true) print('Auto-translate enabled');
});

Get auto-translate status

Dart

await NCEngine.translate.getAutoTranslateEnabled((isEnable, error) {
  if (error == null) print('Auto-translate: $isEnable');
});

Channel-level translation strategy

Set per-channel translation strategies that sync across devices.

TranslateStrategy values

Enum	Description
defaultFollowUser	Follow user-level auto-translate setting
autoOn	Enable auto-translate for this channel
autoOff	Disable auto-translate for this channel

Set strategy

Dart

final channels = [
  ChannelIdentifier(channelType: ChannelType.direct, channelId: 'user1'),
  ChannelIdentifier(channelType: ChannelType.group, channelId: 'group1'),
];

await NCEngine.translate.setTranslateStrategy(
  channels,
  TranslateStrategy.autoOn,
  (error) {
    if (error?.isSuccess == true) print('Strategy set');
  },
);

Read strategy

Dart

TranslateStrategy? strategy = channel.translateStrategy;

Translate multiple messages

Dart

await NCEngine.translate.translateMessages(
  TranslateMessagesParams(
    force: true,
    mode: TranslateMode.mechanical,
    list: [
      TranslateMessageParam(
        messageId: message.messageId,
        targetLanguage: 'zh',
        sourceLanguage: 'en',
      ),
    ],
  ),
  (error) {
    if (error?.isSuccess == true) print('Translation request submitted');
  },
);

Translate multiple text strings

Dart

await NCEngine.translate.translateTexts(
  TranslateTextsParams(
    list: ['Hello, World!'],
    mode: TranslateMode.mechanical,
  ),
  (error) {
    if (error?.isSuccess == true) print('Text translation request submitted');
  },
);

Listen for translation results

Translation results are delivered asynchronously. Register a TranslateHandler to receive them.

TranslateResult properties

Property	Type	Description
identifier	String?	Identifier of the source item this result corresponds to
error	NCError?	Per-item result status. In the current wrapper, successful items also report NCError(code: 0)
sourceType	TranslateResultType?	Type of source content this result corresponds to
translateInfo	TranslateInfo?	Detailed translation payload for this item

TranslateInfo properties

Property	Type	Description
translatedText	String?	Translated content
targetLanguage	String?	Target language code used for translation
status	TranslateStatus?	Translation status for the item

Register handler

Dart

NCEngine.addTranslateHandler('translate-handler', TranslateHandler(
  onTranslationCompleted: (event) {
    for (final item in event.results ?? []) {
      print('Translated: ${item.translateInfo?.translatedText}');
    }
  },
  onTranslationLanguageChanged: (event) {
    print('Translation language changed: ${event.language}');
  },
  onAutoTranslateStateChanged: (event) {
    print('Auto-translate toggled: ${event.isEnabled}');
  },
));