# Localization

The Android SDK's UI Components are available in multiple languages out-of-the-box. At the moment we support the following languages (and more will be added in the future):

- [English](https://github.com/GetStream/stream-chat-android/tree/main/stream-chat-android-ui-components/src/main/res/values-en)
- [French](https://github.com/GetStream/stream-chat-android/tree/main/stream-chat-android-ui-components/src/main/res/values-fr)
- [Hindi](https://github.com/GetStream/stream-chat-android/tree/main/stream-chat-android-ui-components/src/main/res/values-hi)
- [Indonesian](https://github.com/GetStream/stream-chat-android/tree/main/stream-chat-android-ui-components/src/main/res/values-in)
- [Italian](https://github.com/GetStream/stream-chat-android/tree/main/stream-chat-android-ui-components/src/main/res/values-it)
- [Japanese](https://github.com/GetStream/stream-chat-android/tree/main/stream-chat-android-ui-components/src/main/res/values-ja)
- [Korean](https://github.com/GetStream/stream-chat-android/tree/main/stream-chat-android-ui-components/src/main/res/values-ko)
- [Spanish](https://github.com/GetStream/stream-chat-android/tree/main/stream-chat-android-ui-components/src/main/res/values-es)

<admonition type="note">

[English](https://github.com/GetStream/stream-chat-android/tree/main/stream-chat-android-ui-components/src/main/res/values) is used as the default language.

</admonition>

<admonition type="warning">

If your app doesn't support all these languages, you might want to [remove some of them](#removing-existing-languages).

</admonition>

| English                                                                         | Italian                                                                         |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| ![English](@chat-sdk/android/v6-latest/_assets/custom_translations_english.png) | ![Italian](@chat-sdk/android/v6-latest/_assets/custom_translations_italian.png) |

## What is Localization?

If you deploy your app to users who speak another language, you might want to internationalize (localize) it. That means you need to write the app in a way that makes it possible to localize values like text and layouts for each language or locale that the app supports. For more information, see the official [Android documentation](https://developer.android.com/guide/topics/resources/localization).

Support for different languages in the SDK is based on the standard [Android mechanism](https://developer.android.com/training/basics/supporting-devices/languages) of switching resources on system locale change. The locale will be set automatically, based on system preferences. You can provide custom localization for the SDK's string resources by overriding them in the locale-specific `/res/values` directories of your project.

All of the string resources names provided by Stream SDK are prefixed with `stream_ui_`, for example:

```xml
<string name="stream_ui_message_list_empty">No messages</string>
```

These strings are also grouped in resource files prefixed with `strings_`. Each file corresponds to a related UI component or specific usage. You can browse them in order to provide translations:

- [strings_attachment_gallery.xml](https://github.com/GetStream/stream-chat-android/blob/main/stream-chat-android-ui-components/src/main/res/values/strings_attachment_gallery.xml)
- [strings_channel_list.xml](https://github.com/GetStream/stream-chat-android/blob/main/stream-chat-android-ui-components/src/main/res/values/strings_channel_list.xml)
- [strings_channel_list_header.xml](https://github.com/GetStream/stream-chat-android/blob/main/stream-chat-android-ui-components/src/main/res/values/strings_channel_list_header.xml)
- [strings_mention_list.xml](https://github.com/GetStream/stream-chat-android/blob/main/stream-chat-android-ui-components/src/main/res/values/strings_mention_list.xml)
- [strings_message_composer.xml](https://github.com/GetStream/stream-chat-android/blob/main/stream-chat-android-ui-components/src/main/res/values/strings_message_composer.xml)
- [strings_message_list.xml](https://github.com/GetStream/stream-chat-android/blob/main/stream-chat-android-ui-components/src/main/res/values/strings_message_list.xml)
- [strings_message_list_header.xml](https://github.com/GetStream/stream-chat-android/blob/main/stream-chat-android-ui-components/src/main/res/values/strings_message_list_header.xml)
- [strings_search.xml](https://github.com/GetStream/stream-chat-android/blob/main/stream-chat-android-ui-components/src/main/res/values/strings_search.xml)
- [strings_mention_list.xml](https://github.com/GetStream/stream-chat-android/blob/main/stream-chat-android-ui-components/src/main/res/values/strings_mention_list.xml)
- [strings_pinned_message_list.xml](https://github.com/GetStream/stream-chat-android/blob/main/stream-chat-android-ui-components/src/main/res/values/strings_pinned_message_list.xml)
- [strings_common.xml](https://github.com/GetStream/stream-chat-android/blob/main/stream-chat-android-ui-components/src/main/res/values/strings_common.xml)

## Adding a New Language

Let's see how you can add support for additional languages in the SDK. As an example, we'll implement a custom Polish language translation for the [`ChannelListHeaderView`](/chat/docs/sdk/android/ui/channel-components/channel-list-header/) UI component.

Usually, base string resources are located in the `/res/values/strings.xml` file. In order to add translations for the new language (PL) we are going to create a new `strings.xml` file under `res/values-pl` directory.

Let's take a look at the [strings_channel_list_header.xml](https://github.com/GetStream/stream-chat-android/blob/main/stream-chat-android-ui-components/src/main/res/values/strings_channel_list_header.xml) file and discover strings defined for `ChannelListHeaderView`:

```xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="stream_ui_channel_list_header_connected">Stream Chat</string>
    <string name="stream_ui_channel_list_header_disconnected">Waiting for network</string>
</resources>
```

As you can see there are two string resources used by this UI component. Let's say we need to localize only the one called `stream_ui_channel_list_header_disconnected`.

In order to do that, we need to add the following string resource to the target locale-specific file. In our case, this will be the `res/values-pl/strings.xml`:

```xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="stream_ui_channel_list_header_disconnected">Oczekiwanie na połączenie</string>
</resources>
```

As the result, your app will display _`Oczekiwanie na połączenie`_ text on devices set to a Polish locale.

## Overriding Existing Languages

To override strings for a language supported by default, create new string resources in the locale-specific `/res/values-XX` directories of your project with the same `name`. [Here](https://github.com/GetStream/stream-chat-android/tree/main/stream-chat-android-ui-components/src/main/res/values) you can find a list of available text resources grouped by component.

## Overriding the Default Language

To change the strings used by default, place the string resources you want to override inside the `/res/values` [directory](https://github.com/GetStream/stream-chat-android/tree/main/stream-chat-android-ui-components/src/main/res/values) directory.

## Removing Existing Languages

The Android UI Components include resources for all of the languages mentioned above. If your app doesn't support all those languages, you can exclude some of them by explicitly defining a list of supported languages inside your `build.gradle` file:

```groovy
defaultConfig {
    resConfigs "en", "es"
}
```

With the configuration here, your app will include only _English_ and _Spanish_ resources.

## Automatic Translation

Stream Chat provides the ability to run users' messages through automatic translation.
While machine translation is never perfect it can enable two users to communicate with
each other without speaking the same language.

In order to enable automatic translation, the following steps are required to do in the Client SDKs:

### Enabling the feature in the UI Components SDK through

```kotlin
ChatUI.autoTranslationEnabled = true
```

### Supporting auto-translation in the custom ChatMessageTextTransformer

Please, take into account, that if you are using a custom `ChatMessageTextTransformer` you need to support the auto-translation feature by yourself.

The following example shows how to do that:

```kotlin
ChatUI.messageTextTransformer = MarkdownTextTransformer(
    context = context
) { item: MessageListItem.MessageItem ->
    if (ChatUI.autoTranslationEnabled) {
        chatClient.getCurrentUser()?.language?.let { language ->
            item.message.getTranslation(language).ifEmpty { item.message.text }
        } ?: item.message.text
    } else {
        item.message.text
    }
}
```

### Enabling the feature for Push Notifications

```kotlin
val notificationConfig = NotificationConfig(
    //...
    autoTranslationEnabled = true,
    //...
)
val notificationHandler = NotificationHandlerFactory.createNotificationHandler(
    //...
    notificationConfig = notificationConfig,
    //...
)
ChatClient.Builder(apiKey, context)
    //...
    .notifications(notificationConfig, notificationHandler)
    //...
    .build()

```

### Providing the language when connecting the user

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

For more information, see the full guide
to [adding automatic translation](/chat/docs/android/translation/).

---

This page was last updated at 2025-08-15T14:15:38.346Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/android/ui/guides/custom-translations/](https://getstream.io/chat/docs/sdk/android/ui/guides/custom-translations/).