Realtime Translation - Flutter

Realtime translation allows you to convert spoken audio into translated text instantly during a live meeting session. This guide explains how to use the startTranslation(), stopTranslation(), and changeTranslationLanguage() methods of the Room class to manage translation in real time in your application.

You can define a participant's translation language when creating the room with createRoom(), or update it at any point during the session with the changeTranslationLanguage() method.

note

The translation language is always a language code, both in the translationLanguage parameter of createRoom() and in changeTranslationLanguage(). Only the codes listed in Supported Languages return translated text. If you pass an unsupported code, no translation output is received.

Integrating Realtime Translation Feature

1. Start Translation: You start realtime translation with the startTranslation() method. The translationStateChanged event then reports TRANSLATION_STARTING, followed by TRANSLATION_STARTED once translation is running.

2. Translation Data: As translation progresses, the translationText event delivers a TranslationText object holding the translated text, the participant who spoke it, the timestamp, and the language.

3. Change Translation Language: A participant can switch to another language while translation is running with changeTranslationLanguage(). The translationLanguageChanged event then reports the newly selected language to that participant.

4. Stop Translation: When you stop translation with stopTranslation(), the translationStateChanged event reports TRANSLATION_STOPPING, followed by TRANSLATION_STOPPED.

Step 1: Configure the translation languages

• You can set the participant's translation language and speaking language while creating the room with createRoom().

Room room = VideoSDK.createRoom(
  roomId: meetingId,
  token: token,
  displayName: displayName,
  micEnabled: true,
  camEnabled: true,
  translationLanguage: "en",
  speakingLanguage: "en",
);

• translationLanguage: The language the participant receives translated text in. The translationText event fires only when the text is in this language, so a participant who does not set translationLanguage receives no translated text until they call changeTranslationLanguage().

• speakingLanguage: Fixes the language the participant speaks in for the whole session. When it is not set, the participant's translationLanguage doubles as their spoken language. Refer to Speaking Language and Translation Language for how the two interact.

Step 2: Start realtime translation

• Initiate the realtime translation using the startTranslation() method.

// Starts realtime translation
room.startTranslation();

Step 3: Change the translation language

• Switch to another language while translation is running using the changeTranslationLanguage() method. The method takes the language code to switch to.

// Changes the translation language to Spanish
room.changeTranslationLanguage("es");

Step 4: Stop realtime translation

• Terminate the realtime translation using the stopTranslation() method.

// Stops realtime translation
room.stopTranslation();

note

startTranslation() and changeTranslationLanguage() return a Future that completes with an error when the request fails, and the room emits an error event carrying START_TRANSLATION_FAILED (4042) or CHANGE_TRANSLATION_LANGUAGE_FAILED (4044).

caution

stopTranslation() returns void rather than a Future, so awaiting it has no effect and a surrounding try/catch does not catch a failed stop request. Watch the error event for STOP_TRANSLATION_FAILED (4043) instead.

note

All three methods return without sending a request when the room has not been joined yet, or while it is reconnecting. In both cases the room emits an error event first — ERROR_MEETING_RECONNECTING (3027) while it is reconnecting, and ERROR_ACTION_PERFORMED_BEFORE_MEETING_JOINED (3022) when it has not been joined. Call them only after the roomJoined event.

Step 5: Listen for the translation events

• Here, you configure the event listeners for the translation events.

import 'package:videosdk/videosdk.dart';

void registerTranslationEvents(Room room) {
  // Listen for translation state changed event
  room.on(Events.translationStateChanged, (TranslationState state) {
    if (state == TranslationState.TRANSLATION_STARTING) {
      print("Realtime Translation is starting");
    } else if (state == TranslationState.TRANSLATION_STARTED) {
      print("Realtime Translation is started");
    } else if (state == TranslationState.TRANSLATION_STOPPING) {
      print("Realtime Translation is stopping");
    } else if (state == TranslationState.TRANSLATION_STOPPED) {
      print("Realtime Translation is stopped");
    }
  });

  // Listen for translation text event
  room.on(Events.translationText, (TranslationText translationText) {
    print(
        "${translationText.participantName} (${translationText.language}): ${translationText.text} ${translationText.timestamp}");
  });

  // Listen for translation language changed event
  room.on(Events.translationLanguageChanged, (String language) {
    print("Translation language changed to $language");
  });
}

• translationStateChanged delivers a TranslationState value, one of TRANSLATION_STARTING, TRANSLATION_STARTED, TRANSLATION_STOPPING, or TRANSLATION_STOPPED.

• translationText delivers a TranslationText object holding text, participantId, participantName, participantLanguage (the language the speaker spoke in), language (the language the text was translated into), timestamp, and a type of either full or partial. It fires only for text in the receiving participant's own translation language.

Example

• The following code snippet allows you to start, stop, and change the language of realtime translation with just a click.

import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';

class TranslationView extends StatefulWidget {
  final Room room;

  const TranslationView({Key? key, required this.room}) : super(key: key);

  @override
  State<TranslationView> createState() => _TranslationViewState();
}

class _TranslationViewState extends State<TranslationView> {
  bool isTranslationOn = false;
  String currentLanguage = "en";
  List<String> translationMessages = [];

  @override
  void initState() {
    super.initState();
    registerTranslationEvents();
  }

  void registerTranslationEvents() {
    // Listen for translation state changed event
    widget.room.on(Events.translationStateChanged, (TranslationState state) {
      if (state == TranslationState.TRANSLATION_STARTED) {
        setState(() => isTranslationOn = true);
      } else if (state == TranslationState.TRANSLATION_STOPPING ||
          state == TranslationState.TRANSLATION_STOPPED) {
        setState(() => isTranslationOn = false);
      }
    });

    // Listen for translation text event
    widget.room.on(Events.translationText, (TranslationText translationText) {
      setState(() {
        translationMessages.add(
            "${translationText.participantName}: ${translationText.text}");
      });
    });

    // Listen for translation language changed event
    widget.room.on(Events.translationLanguageChanged, (String language) {
      setState(() => currentLanguage = language);
    });
  }

  Future<void> startTranslation() async {
    try {
      await widget.room.startTranslation();
    } catch (error) {
      print("startTranslation failed: $error");
    }
  }

  Future<void> changeLanguage(String languageCode) async {
    try {
      await widget.room.changeTranslationLanguage(languageCode);
    } catch (error) {
      print("changeTranslationLanguage failed: $error");
    }
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text(isTranslationOn
            ? "Translation active ($currentLanguage)"
            : "Translation inactive"),
        Row(
          children: [
            ElevatedButton(
              onPressed: isTranslationOn ? null : startTranslation,
              child: const Text("Start Translation"),
            ),
            ElevatedButton(
              // stopTranslation() returns void, so it is called directly
              onPressed:
                  isTranslationOn ? () => widget.room.stopTranslation() : null,
              child: const Text("Stop Translation"),
            ),
          ],
        ),
        Wrap(
          children: [
            for (final entry in {
              "French": "fr",
              "Spanish": "es",
              "German": "de",
              "Hindi": "hi",
            }.entries)
              ElevatedButton(
                onPressed:
                    isTranslationOn ? () => changeLanguage(entry.value) : null,
                child: Text(entry.key),
              ),
          ],
        ),
        Expanded(
          child: ListView.builder(
            itemCount: translationMessages.length,
            itemBuilder: (context, index) => Text(translationMessages[index]),
          ),
        ),
      ],
    );
  }
}

Speaking Language and Translation Language

The speakingLanguage parameter defines the language a participant speaks in, while translationLanguage defines the language they want to receive translated text in. The two examples below show how translation behaves with and without a speaking language.

Example 1: Without speakingLanguage

Both participants set only their translation language, so each participant's translation language doubles as their spoken language.

// Participant 1 (Spanish)
Room room = VideoSDK.createRoom(
  roomId: meetingId,
  token: token,
  displayName: displayName,
  translationLanguage: "es", // Spanish
);

// Participant 2 (German)
Room room = VideoSDK.createRoom(
  roomId: meetingId,
  token: token,
  displayName: displayName,
  translationLanguage: "de", // German
);

Participant 1 selected Spanish (es) as their translation language, so Spanish is also their spoken language. Participant 2 selected German (de), so German is also their spoken language.

Speaker	Speaking Language (Input)	Receiver	Translated Output
Participant 1	Spanish (es)	Participant 2	German (de)
Participant 2	German (de)	Participant 1	Spanish (es)

In this case each participant must speak in their own translation language, because no speaking language is defined.

Example 2: With speakingLanguage on one participant

Here only Participant 1 sets a speakingLanguage. That fixes the input language for their audio, while Participant 2's translation language still doubles as their spoken language.

// Participant 1 (speaks English, receives Spanish)
Room room = VideoSDK.createRoom(
  roomId: meetingId,
  token: token,
  displayName: displayName,
  translationLanguage: "es", // Spanish (output)
  speakingLanguage: "en", // English (input)
);

// Participant 2 (no speakingLanguage, receives German)
Room room = VideoSDK.createRoom(
  roomId: meetingId,
  token: token,
  displayName: displayName,
  translationLanguage: "de", // German (output)
);

Participant 1 speaks in English (en) and receives translations in Spanish (es). Participant 2 has no speakingLanguage, so German (de) is both the language they speak and the language they receive translations in.

Speaker	Speaking Language (Input)	Receiver	Translated Output
Participant 1	English (en)	Participant 2	German (de)
Participant 2	German (de)	Participant 1	Spanish (es)

Participant 1 speaks English and Participant 2 receives it translated into German, while Participant 1 receives Participant 2's German speech translated into Spanish.

Key takeaways

• When speakingLanguage is not set, the participant's translation language doubles as their speaking language.
• When only one participant sets a speakingLanguage, that participant's input language is fixed, while the others keep using their translation language as their input language.
• Setting speakingLanguage gives you better control and consistency, especially in multilingual meetings.

Supported Languages

These are the supported language codes:

• Multilingual (Spanish + English): multi
• Bulgarian: bg
• Catalan: ca
• Chinese (Mandarin, Simplified): zh, zh-CN, zh-Hans
• Chinese (Mandarin, Traditional): zh-TW, zh-Hant
• Chinese (Cantonese, Traditional): zh-HK
• Czech: cs
• Danish: da, da-DK
• Dutch: nl
• English: en, en-US, en-AU, en-GB, en-NZ, en-IN
• Estonian: et
• Finnish: fi
• Flemish: nl-BE
• French: fr, fr-CA
• German: de
• German (Switzerland): de-CH
• Greek: el
• Hindi: hi
• Hungarian: hu
• Indonesian: id
• Italian: it
• Japanese: ja
• Korean: ko, ko-KR
• Latvian: lv
• Lithuanian: lt
• Malay: ms
• Norwegian: no
• Polish: pl
• Portuguese: pt, pt-BR, pt-PT
• Romanian: ro
• Russian: ru
• Slovak: sk
• Spanish: es, es-419
• Swedish: sv, sv-SE
• Thai: th, th-TH
• Turkish: tr
• Ukrainian: uk
• Vietnamese: vi