Skip to main content

Translation and i18n

The Stream Chat React component library uses the i18next dependency to create a Streami18n class constructor that handles language translation of our UI components. The Stream Chat API also supports automatic translation of chat messages, learn more.

Supported Languages#

The library provides built-in translations for the following languages:

  1. English (en) - default
  2. Dutch (nl)
  3. French (fr)
  4. German (de)
  5. Hindi (hi)
  6. Italian (it)
  7. Japanese (ja)
  8. Korean (ko)
  9. Portuguese (pt)
  10. Russian (ru)
  11. Spanish (es)
  12. Turkish (tr)

If you wish to change the default language in your app without initiating an instance of Streami18n, pass the defaultLanguage prop to the Chat component on load of your application. The below code snippet will change the default language from English to Italian.

const defaultLanguage = 'it';

<Chat client={client} defaultLanguage={defaultLanguage}>

The following screenshots show the state of the UI components in the app before and after setting the defaultLanguage to Italian.

Default language not specified:


Default language set to Italian:


The defaultLanguage prop is only applicable as a fallback language. If the connected user's preferred browser language is supported for translation, the component library will preferentially render the browser language. Meaning, if defaultLanguage was set to Italian but the user's preferred browser language was Spanish, the component library would render Spanish.

Enable Localization#

The library supports two different methods for manually setting the language of the connected user and automatically translates all text built into the UI components. The simpler and less customizable way is to set the language value in the connectUser method on mount of the chat application.

client.connectUser({ id: userId, language: 'es' }, userToken);

If auto translation of messages is enabled in the application, setting the language value on connectUser will result in the auto translation of all message text. If this behavior is undesired, follow the steps below to create a translation instance.

Create a Streami18n Instance#

Additionally, you can create a class instance of Streami18n and pass as a prop into the Chat component. The below example changes the current user's language to Spanish.

const i18nInstance = new Streami18n({ language: 'es' });

<Chat client={client} i18nInstance={i18nInstance}>

Override Default Translations#

Taking it one step further, the below example shows how to override the default text values built into the components.

const i18nInstance = new Streami18n({
language: 'es',
translationsForLanguage: {
'Nothing yet...': 'Nada!', // default is 'Nada aun...'

<Chat client={client} i18nInstance={i18nInstance}>

If you wish to completely override one of our language files, provide your custom translations via the translationsForLanguage key. Your custom language file must include all of the keys of the default file.

import esUpdated from 'path/to/esUpdated.json';

const i18nInstance = new Streami18n({
language: 'es',
translationsForLanguage: esUpdated,

<Chat client={client} i18nInstance={i18nInstance}>

If the language for the connected user is not manually set by passing a Streami18n object to the Chat component, the component library detects the user's default browser language. If the component library has translation support for the detected browser language, either through the languages provided or by a custom added language (described below), the connected user's language is automatically set to this value. If the browser language is not supported for translation, the library defaults to English.


All available translations are found on GitHub and the JSON objects can be imported from the library.

import { esTranslations } from 'stream-chat-react';

Add a Language#

In the following example, we will demonstrate how to add translation support for an additional language not currently supported by the component library. We will add translations for Simplified Chinese, which uses language code zh, by following these steps:

  1. Create a JSON file in your project (ex: zh.json if creating a translation file for Simplified Chinese)
  2. Copy the content of an existing translation file
  3. Change the values to your desired translations
  4. Register the translation file and set the new language
  5. Pass as a prop to the Chat component

The setLanguage method on the class instance of Streami18n is asynchronous, so it's response needs to be awaited before the language translations can be updated.

import zhTranslation from 'path/to/zh.json';

const i18nInstance = new Streami18n();

const App = () => {
const [languageLoaded, setLanguageLoaded] = useState(false);

useEffect(() => {
const loadLanguage = async () => {
i18nInstance.registerTranslation('zh', zhTranslations);
await i18nInstance.setLanguage('zh');

}, []);

if (!languageLoaded) return null;

return (
<Chat client={client} i18nInstance={i18nInstance}>

Translating Messages#

Stream Chat provide 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. For more information, see the full guide to adding automatic translation.

Diacritics and Transliteration#

Searching for users when utilizing the '@' mentions command supports diacritics and, optionally, transliteration using Transliterate. To add transliteration to your search functionality with the external Transliterate library, use the useMentionsTransliteration prop in the MessageInput. This library is dynamically imported if the prop is true. Diacritics support is available by default.


Streami18n API Reference#

The Streami18n class wraps i18next and provides a set of values and methods.

Class Constructor Options#

languageconnected user's languagestring'en'
translationsForLanguageoverrides existing component textobject{}
disableDateTimeTranslationsdisables translation of date timesbooleanfalse
debugenables i18n debug modebooleanfalse
loggerlogs warnings/errorsfunction() => {}
dayjsLocaleConfigForLanguageinternal Day.js config objectobject'enConfig'
DateTimeParsercustom date time parserfunctionDay.js

Class Instance Methods#


Returns an array of language code strings corresponding to available languages.

const availableLanguages = streami18n.getAvailableLanguages();


Returns the instance of i18next used within the Streami18n instance.

const i18nInstance = streami18n.geti18Instance();


Returns the current translation dictionaries for all languages.

const translations = streami18n.getTranslations();


Asynchronous function that returns the current translator functions.

const { t, tDateTimeParser } = await streami18n.getTranslators();


Allows you to register a custom translation, which overrides an existing translation for the given language. The third parameter, which is an optional Day.js locale, is structured the same as dayjsLocaleConfigForLanguage.

Review the enTranslations JSON file exported from stream-chat-react for a current list of translation keys.

streami18n.registerTranslation('es', {
'Nothing yet...': 'Nada!',


Asynchronous function that changes the current language and returns a new translation function. If not initialized, undefined will be returned. If the language fails to update, the current translation function will be returned.

const t = await streami18n.setLanguage('nl');

Did you find this page helpful?