Translation

LAST EDIT Feb 17 2021

Chat messages can be translated on-demand or automatically, this allows users speaking different languages on the same channel.

Message Translation Endpoint

Copied!

This API endpoint translates an existing message to another language. The source language is inferred from the user language or detected automatically by analysing its text. If possible it is recommended to store the user language, see "Set user language" section later in this page.

1
2
3
4
5
6
7
8
9
10
11
await channel.sendMessage({ 
  id: messageID, 
  text: "Hello, I would like to have more information about your product."} 
); 
 
// returns the message.text translated into French 
const response = await client.translateMessage(messageID, "fr"); 
 
// the translation will be added to the i18n object 
console.log(response.message.i18n.fr_text); 
// "Bonjour, J'aimerais avoir plus d'informations sur votre produit.",
1
2
3
4
5
6
7
8
9
10
11
await channel.sendMessage(Message( 
  id: messageId, 
  text: 'Hello, I would like to have more information about your product.', 
)); 
  
// returns the message.text translated into French  
final response = await channel.translateMessage(messageId, 'fr'); 
 
// the translation will be added to the i18n object 
print(response.message.i18n['fr_text']); 
// "Bonjour, J'aimerais avoir plus d'informations sur votre produit.",
1
2
3
4
5
6
7
8
9
10
11
12
13
14
let channel = Client.shared.channel(type: .messaging, id: "general") 
let message = Message(text: "Hello, I would like to have more information about your product.") 
// Send the message, so it has a valid id 
channel.send(message: message) { result in 
    let message = result.value!.message 
     
    // Translate the message into French 
    message.translate(to: .french) { (result) in 
        let translatedMessage = result.value!.message 
         
        print(translatedMessage.i18n?.translated[.french]) 
        // "Bonjour, J'aimerais avoir plus d'informations sur votre produit.", 
    } 
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Translate message to French 
ChannelClient channelClient = client.channel("messaging", "general"); 
 
Message message = new Message(); 
message.setText("Hello, I would like to have more information about your product."); 
 
channelClient.sendMessage(message).enqueue(result -> { 
    if (result.isSuccess()) { 
        String messageId = result.data().getId(); 
 
        client.translate(messageId, "fr").enqueue(translationResult -> { 
            if (translationResult.isSuccess()) { 
                Message translatedMessage = translationResult.data(); 
                String translation = translatedMessage.getI18n().get("fr_text"); 
            } else { 
                // Handle translationResult.error() 
            } 
        }); 
    } else { 
        // Handle result.error() 
    } 
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Translate message to French 
val channelClient = client.channel("messaging", "general") 
val message = Message(text = "Hello, I would like to have more information about your product.") 
 
channelClient.sendMessage(message).enqueue { result -> 
    if (result.isSuccess) { 
        val messageId = result.data().id 
        val frenchLanguage = "fr" 
 
        client.translate(messageId, frenchLanguage).enqueue { translationResult -> 
            if (translationResult.isSuccess) { 
                val translatedMessage = translationResult.data() 
                val translation = translatedMessage.getTranslation(frenchLanguage) 
            } else { 
                // Handle translationResult.error() 
            } 
        } 
    } else { 
        // Handle result.error() 
    } 
}

The endpoint returns the translated message, updates it and sends a message.updated event to all users on the channel.

Only the text field is translated, custom fields and attachments are not included.

i18n data

Copied!

When a message is translated, the i18n object is added. The i18n includes the message text in all languages and the code of the original language.

The i18n object has one field for each language named using this convention language-code_text

Here is an example after translating a message from english into French and Italian.

1
2
3
4
5
{  
    "fr_text": "Bonjour, J'aimerais avoir plus d'informations sur votre produit.", 
    "it_text": "Ciao, vorrei avere maggiori informazioni sul tuo prodotto.", 
    "language": "en" 
}

Automatic translation

Copied!

Automatic translation translates all messages immediately when they are added to a channel and are delivered to the other users with the translated text directly included.

Automatic translation works really well for 1-1 conversations or group channels with two main languages.

Let's see how this works in practice:

  1. A user sends a message and automatic translation is enabled

  2. The language set for that user is used as source language (if not the source language will be automatically detected)

  3. The message text is translated into the other language in used on the channel by its members

When using auto translation, it is recommended setting the language for all users and add them as channel members

Enabling automatic translation

Copied!

Automatic translation is not enabled by default. You can enable it for your application via API or CLI. You can also enable auto translation on a channel basis.

1
2
3
4
5
6
7
8
9
10
11
// enable auto-translation only for this channel 
await channel.update({auto_translation_enabled: true}); 
 
// ensure all messages are translated in english for this channel 
await channel.update({ 
   auto_translation_enabled: true, 
   auto_translation_language: "en", 
}); 
 
// auto translate messages for all channels 
await client.updateAppSettings({auto_translation_enabled: true});

Set user language

Copied!

In order for auto translation to work, you must set the user language or specify a destination language for the channel using the auto_translation_language field (see previous code example).

1
2
3
4
5
// sets the user language 
await client.setUser({id, language: "en"}) 
 
// watch a channel 
await client.channel("messaging", "melting-pot")
Messages are automatically translated from the user language that posts the message to the most common language in use by the other channel members.

Caveats and limits

Copied!
  • Translation is only done for messages with up to 5,000 characters. Blowin' In The Wind from Bob Dylan contains less than 1,000 characters

  • Error messages and commands are not translated (ie. /giphy hello)

  • When a message is updated, translations are recomputed automatically

  • Changing translation settings or user language have no effect on messages that are already translated

Available Languages

Copied!

Language name

Language code

Afrikaans

af

Albanian

sq

Amharic

am

Arabic

ar

Azerbaijani

az

Bengali

bn

Bosnian

bs

Bulgarian

bg

Chinese (Simplified)

zh

Chinese (Traditional)

zh-TW

Croatian

hr

Czech

cs

Danish

da

Dari

fa-AF

Dutch

nl

English

en

Estonian

et

Finnish

fi

French

fr

French (Canada)

fr-CA

Georgian

ka

German

de

Greek

el

Hausa

ha

Hebrew

he

Hindi

hi

Hungarian

hu

Indonesian

id

Italian

it

Japanese

ja

Korean

ko

Latvian

lv

Malay

ms

Norwegian

no

Persian

fa

Pashto

ps

Polish

pl

Portuguese

pt

Romanian

ro

Russian

ru

Serbian

sr

Slovak

sk

Slovenian

sl

Somali

so

Spanish

es

Spanish (Mexico)

es-MX

Swahili

sw

Swedish

sv

Tagalog

tl

Tamil

ta

Thai

th

Turkish

tr

Ukrainian

uk

Urdu

ur

Vietnamese

vi