# Translation

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

### Message Translation Endpoint

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

<codetabs>

<codetabs-item value="kotlin" label="Kotlin">

```kotlin
// 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 is Result.Success) {
    val messageId = result.value.id
    val frenchLanguage = "fr"

    client.translate(messageId, frenchLanguage).enqueue { translationResult ->
      if (translationResult is Result.Success) {
        val translatedMessage: Message = translationResult.value
        val translation = translatedMessage.getTranslation(frenchLanguage)
      } else {
        // Handle Result.Failure
      }
    }
  } else {
    // Handle Result.Failure
  }
}
```

</codetabs-item>

<codetabs-item value="swift" label="Swift">

```swift
let messageController = chatClient.messageController(cid: <#T##ChannelId#>, messageId: <#T##MessageId#>)
messageController.translate(to: .french) { error in
  if error == nil {
    print(messageController.message?.translations?[.french])
  }
}
```

</codetabs-item>

<codetabs-item value="dart" label="Dart">

```dart
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.",
```

</codetabs-item>

<codetabs-item value="javascript" label="JavaScript">

```js
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.",
```

</codetabs-item>

<codetabs-item value="unreal" label="Unreal">

```cpp
// Not yet supported in the Unreal SDK
```

</codetabs-item>

<codetabs-item value="php" label="PHP">

```php
$response = $client->translateMessage($msgId, "hu");

$response["message"]["i18n"]["fr_text"]
```

</codetabs-item>

<codetabs-item value="python" label="Python">

```python
resp = client.translate_message(msg_id, "fr")

resp["message"]["i18n"]["fr_text"]
```

</codetabs-item>

<codetabs-item value="ruby" label="Ruby">

```ruby
# require 'stream-chat'

resp = client.translate_message(msg_id, "fr")

resp["message"]["i18n"]["fr_text"]
```

</codetabs-item>

<codetabs-item value="go" label="Go">

```go
translated, err := client.TranslateMessage(ctx, message.ID, "fr")
translated.Message.I18n["fr_text"]
```

</codetabs-item>

<codetabs-item value="csharp" label="C#">

```csharp
var resp = await messageClient.TranslateMessageAsync(message.Id, Language.FR);

resp.Message.I18n["fr_text"];
```

</codetabs-item>

<codetabs-item value="unity" label="Unity">

```csharp
// Will be implemented soon, raise a GitHub issue if you need this feature https://github.com/GetStream/stream-chat-unity/issues/
```

</codetabs-item>

<codetabs-item value="java" label="Java">

```java
// Android SDK

// 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()
  }
 });


// Backend SDK
Message.send(channelType, channelId)
  .message(
    MessageRequestObject.builder()
      .id(messageId)
      .text("Hello, I would like to have more information about your product.")
      .userId(userId)
      .build())
  .request();
// returns the message.text translated into French
MessageTranslateResponse response =
  Message.translate(messageId).language(Language.FR).request();
System.out.println(response.getMessage().getI18n().get("fr_text"));
// "Bonjour, J'aimerais avoir plus d'informations sur votre produit."
```

</codetabs-item>

</codetabs>

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

<admonition type="info">

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

</admonition>

### i18n data

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.

<codetabs>

<codetabs-item value="json" label="JSON">

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

</codetabs-item>

</codetabs>

### Automatic translation

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

<admonition type="info">

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

</admonition>

### Enabling automatic translation

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

<codetabs>

<codetabs-item value="javascript" label="JavaScript">

```js
// 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 });
```

</codetabs-item>

<codetabs-item value="java" label="Java">

```java
// Backend SDK

// enable auto-translation only for this channel
Channel.update("channeltype", "channelid")
  .data(ChannelRequestObject.builder().autoTranslationEnabled(true).build())
  .request();

// ensure all messages are translated in english for this channel
Channel.update("channeltype", "channelid")
  .data(ChannelRequestObject
    .builder()
    .autoTranslationEnabled(true)
    .autoTranslationLanguage(Language.EN)
    .build())
  .request();

// auto translate messages for all channels
App.update().autoTranslationEnabled(true).request();
```

</codetabs-item>

<codetabs-item value="php" label="PHP">

```php
// enable auto-translation only for this channel
$channel->update(["auto_translation_enabled" => true]);

// ensure all messages are translated in english for this channel
$channel->update(["auto_translation_enabled" => true, "auto_translation_language" => "en"]);

// auto translate messages for all channels
$client->updateAppSettings(["auto_translation_enabled" => true]);
```

</codetabs-item>

<codetabs-item value="python" label="Python">

```python
# enable auto-translation only for this channel
channel.update({"auto_translation_enabled": True})

# ensure all messages are translated in english for this channel
channel.update({"auto_translation_enabled": True, "auto_translation_language": "en"})

# auto translate messages for all channels
client.update_app_settings(auto_translation_enabled=True)
```

</codetabs-item>

<codetabs-item value="ruby" label="Ruby">

```ruby
# enable auto-translation only for this channel
channel.update({auto_translation_enabled: true})

# ensure all messages are translated in english for this channel
channel.update({auto_translation_enabled: true, auto_translation_language: "en"})

# auto translate messages for all channels
client.update_app_settings(auto_translation_enabled: true)
```

</codetabs-item>

<codetabs-item value="go" label="Go">

```go
// enable auto-translation only for this channel
channel.Update(ctx, map[string]interface{}{"auto_translation_enabled": true}, nil);

// ensure all messages are translated in english for this channel
update := map[string]interface{}{"auto_translation_enabled": true, "auto_translation_language": "en"}
channel.Update(ctx, update, nil);

// auto translate messages for all channels
enabled := true
settings := &AppSettings{AutoTranslationEnabled: &enabled}
client.UpdateAppSettings(ctx, settings)
```

</codetabs-item>

<codetabs-item value="csharp" label="C#">

```csharp
// enable auto-translation only for this channel
var update = new ChannelUpdateRequest { Data = new ChannelRequest { AutoTranslationEnabled = true } };
await channelClient.UpdateAsync(channel.Type, channel.Id, update);

// ensure all messages are translated in english for this channel
var update = new ChannelUpdateRequest { Data = new ChannelRequest { AutoTranslationEnabled = true, AutoTranslationLanguage = Language.EN } };
await channelClient.UpdateAsync(channel.Type, channel.Id, update);

// auto translate messages for all channels
await appClient.UpdateAppSettingsAsync(new AppSettingsRequest { AutoTranslationEnabled = true });
```

</codetabs-item>

<codetabs-item value="unity" label="Unity">

```csharp
// Will be implemented soon, raise a GitHub issue if you need this feature https://github.com/GetStream/stream-chat-unity/issues/
```

</codetabs-item>

</codetabs>

### Set user language

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).

<codetabs>

<codetabs-item value="kotlin" label="Kotlin">

```kotlin
// Sets the user language
client.connectUser(user = User(id = "userId", language = "en"), token = "userToken").await()
```

</codetabs-item>

<codetabs-item value="javascript" label="JavaScript">

```js
// Backend SDK

// sets the user language
await client.connectUser({ id: "userId", language: "en" }, userToken);

// watch a channel
await client.channel("messaging", "melting-pot");
```

</codetabs-item>

<codetabs-item value="java" label="Java">

```java
// Backend SDK

// sets the user language
User.upsert().user(UserRequestObject.builder().id("userId").language(Language.EN).build()).request();
```

</codetabs-item>

<codetabs-item value="php" label="PHP">

```php
// sets the user language
$user = ["id" => "userid", "language" => "en"];
$client->upsertUser($user);
```

</codetabs-item>

<codetabs-item value="python" label="Python">

```python
# sets the user language
user = {"id": "userId", "language": "en"}
client.update_user(user)
```

</codetabs-item>

<codetabs-item value="ruby" label="Ruby">

```ruby
# sets the user language
user = {id: "userId", language: "en"}
client.update_user(user)
```

</codetabs-item>

<codetabs-item value="go" label="Go">

```go
// sets the user language
client.UpsertUser(ctx, &User{ID: "userId", Language: "en"})
```

</codetabs-item>

<codetabs-item value="csharp" label="C#">

```csharp
// sets the user language
await userClient.UpsertAsync(new UserRequest { Id = user.Id, Language = Language.EN });
```

</codetabs-item>

<codetabs-item value="unity" label="Unity">

```csharp
// Will be implemented soon, raise a GitHub issue if you need this feature https://github.com/GetStream/stream-chat-unity/issues/
```

</codetabs-item>

<codetabs-item value="swift" label="Swift">

```swift
// Sets the user language
ChatClient.shared.connectUser(userInfo: UserInfo(id: "userId", language: .english))
```

</codetabs-item>

</codetabs>

<admonition type="info">

Messages are automatically translated from the user language that posts the message to the most common language in use by the other channel members.

</admonition>

### Caveats and limits

- 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

- If there are three or more languages being used by channel members, auto-translate will default to the most common language used by the channel members. Therefore, this feature is best suited for groups with a maximum of **two** main languages.

<admonition type="info">

A workaround to support more than two languages is to use the translateMessage endpoint to store translated messages for multiple languages, and render the appropriate translation depending on the current users language.

</admonition>

### Available Languages

| 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            |
| Haitian Creole        | ht            |
| Hausa                 | ha            |
| Hebrew                | he            |
| Hindi                 | hi            |
| Hungarian             | hu            |
| Indonesian            | id            |
| Italian               | it            |
| Japanese              | ja            |
| Korean                | ko            |
| Latvian               | lv            |
| Lithuanian            | lt            |
| 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            |


---

This page was last updated at 2026-03-05T19:06:02.489Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/python/translation/](https://getstream.io/chat/docs/python/translation/).