Skip to main content

Adding Internationalization (i18n)

If you deploy your app to users who speak another language, you'll need to internationalize it. Stream’s Chat Client provides the option to translate the user-created contents of messages in addition to the UI. The React Native 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):

Usage#

The Streami18n provides static translations for React Native components from the Stream Chat SDK. Streami18n is a class that uses a configuration of i18next with a subset of the functionality exposed. Streami18n is provided by stream-chat-react-native and can be imported from the library.

The only step you need to start using Streami18n is to create an instance of the class.

const streami18n = new Streami18n();

Streami18n will default to English (en). If you choose to use the default English settings with Day.js you do not need to deal directly with an instance of Streami18n, this is taken care of for you.

If you choose to change the language, translation, or date handling, you will need to provide your modified instance of Streami18n to the component library. Two components require your custom instance of Streami18n to properly pass your translation and time-date functions to the component library, OverlayProvider and Chat. Both components accept an instance of Streami18n via the prop i18nInstance. Providing this prop will provide your instance of Streami18n to all of the components via context instead of the default instance.

import { StreamChat } from 'stream-chat'; import { Chat, OverlayProvider, Streami18n } from 'stream-chat-react-native';
const client = StreamChat.getInstance('api_key');const streami18n = new Streami18n();
export const App = () =>  <OverlayProvider i18nInstance={streami18n}>    <Chat client={client} i18nInstance={streami18n}>      {/** App components */}    </Chat>  </OverlayProvider>;

Setting language for components#

Stream provides built in translations for some languages out-of-the-box. Streami18n accepts two optional parameters when being instantiated, options and i18nextConfig. These parameters allow you to modify the Streami18n instance to your preferences.

As an example, let's say we need to localize the UI of the application for a Dutch audience:

const streami18n = new Streami18n({ language: 'nl' }); // Instantiate Streami18n with Dutch strings.

Alternatively, you can also use setLanguage method on Streami18n class. This is useful especially if you want to build language toggle functionality within your app.

For example, let's say an application needs to default to English but support French:

const streami18n = new Streami18n();
...// Logic for how a user can change the language...
streami18n.setLanguage('fr'); // The UI will change to French.

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:

const streami18n = new Streami18n();streami18n.registerTranslation('pl', {  'Copy Message': 'Kopiuj wiadomość',  'Delete Message': 'Usuń wiadomość',  '{{ firstUser }} and {{ secondUser }} are typing...':    '{{ firstUser }} i {{ secondUser }} piszą...',})

Please take a look at all the available texts here.

Overriding existing languages#

You can also make line item changes to the strings for existing UI components. This is useful if you want to tweak an existing language to use regional spelling variants (American English vs. UK English, for example) same process as Adding a new language. As an example, we'll override the translations for Dutch language:

const streami18n = new Streami18n();
streami18n.registerTranslation('nl', {  "Delete Message": "Verwijder bericht"})

Using device locale to set language#

react-native-localize package provides a toolbox for React Native app localization. You can use this package to access user preferred locale, and use it to set language for chat components:

import * as RNLocalize from "react-native-localize";const streami18n = new Streami18n();
const userPreferredLocales = RNLocalize.getLocales();
streami18n.setLanguage(userPreferredLocales[0].languageCode);

Overriding DateTime format#

React Native SDK uses dayjs internally by default to format datetime stamp. Dayjs is a lightweight alternative to Momentjs with the same modern API and has locale support as well.

Dayjs provides locale config for plenty of languages, you can check the whole list of locale configs here

You can either provide the dayjs locale config while registering language with Streami18n (either via constructor or registerTranslation()) or you can provide your own Dayjs or Moment instance to Streami18n constructor, which will be then used internally (using the language locale) in components.

const i18n = new Streami18n({ language: 'nl', dayjsLocaleConfigForLanguage: {   months: [...],   monthsShort: [...],   calendar: {     sameDay: '...'   } }});

You can add locale config for moment while registering translation via registerTranslation function:

const i18n = new Streami18n();
i18n.registerTranslation( 'mr', {   'Nothing yet...': 'काहीही नाही  ...',   '{{ firstUser }} and {{ secondUser }} are typing...':    '{{ firstUser }} आणि {{ secondUser }} टीपी करत आहेत ', }, {   months: [...],   monthsShort: [...],   calendar: {     sameDay: '...'   } });

Alternatively, you can use a utility library to handle DateTime by providing your own Moment object:

import 'moment/locale/nl';import 'moment/locale/it';// or if you want to include all localesimport 'moment/min/locales';
import Moment from moment
const i18n = new Streami18n({ language: 'nl', DateTimeParser: Moment})

Or by providing your own Dayjs object:

import Dayjs from 'dayjs'
import 'dayjs/locale/nl';import 'dayjs/locale/it';// or if you want to include all localesimport 'dayjs/min/locales';
const i18n = new Streami18n({ language: 'nl', DateTimeParser: Dayjs})

If you would like to stick with English language for date-times in Stream components, you can set disableDateTimeTranslations to true.

Translating messages#

If your application has a userbase that speaks more than one language, Stream's Chat Client provides the option to automatically translate messages. For more information on using automatic machine translation for messages, see the Chat Client Guide on Translation.

Options#

options is the first optional parameter passed to Streami18n, it is an object with all keys being optional.

DateTimeParser#

Used for translating dates and times into the desired local format. Either Day.js or Moment can be used. Day.js is a dependency of the repo and used by default.

TYPEDEFAULT
Dayjs | MomentDayjs

dayjsLocaleConfigForLanguage#

You can customize and create new locales using Day.js. To allow accessability to this option when using the default Day.js instance you can pass these customizations via the dayjsLocaleConfigForLanguage key.

TYPE
object

debug#

Enable debug mode in internal i18next instance.

TYPEDEFAULT
booleanfalse

disableDateTimeTranslations#

Use the default English language date-times instead of those dictated by the language set.

TYPEDEFAULT
booleanfalse

language#

Language code for language to be used. The following options are available:

  • English (en)
  • French (fr)
  • Hindi (hi)
  • Italian (it)
  • Dutch (nl)
  • Turkish (tr)
  • Russian (ru)
  • Japanese (ja)
  • Korean (ko)
TYPEDEFAULT
stringen

logger#

Function to log warnings & errors from Streami18n.

TYPEDEFAULT
(msg?: string) => voidconsole.warn

translationsForLanguage#

Allows you to override the provided translations for given keys.

const streami18n = new Streami18n({  language: 'nl',  translationsForLanguage: {    'Nothing yet...': 'Nog Niet...',    '{{ firstUser }} and {{ secondUser }} are typing...':      '{{ firstUser }} en {{ secondUser }} zijn aan het typen...',  },});
TYPE
object

I18NextConfig#

i18NextConfig is the second optional parameter passed to Streami18n, it is an object with all keys being optional. i18nextConfig is used in the instantiation of the i18next instance and mostly aligns with the i18next options.

debug#

Enable debug mode in internal i18next instance. This overrides the debug key on options if provided.

TYPE
boolean

fallbackLng#

Fallback language setting for for i18next.

TYPE
FallbackLng

interpolation#

i18next interpolation setting for integrating dynamic values into translations.

TYPEDEFAULT
object{ escapeValue: false }

keySeparator#

Override character to separate keys.

TYPEDEFAULT
string | booleanfalse

lng#

Override language to use.

TYPE
string

nsSeparator#

Override character to split namespace from key.

TYPEDEFAULT
string | booleanfalse

parseMissingKeyHandler#

Function to handle keys missing translations for the selected language.

TYPEDEFAULT
(key: string) => string(key) => key

Methods#

getAvailableLanguages#

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

const availableLanguages = streami18n.getAvailableLanguages();

geti18Instance#

Returns instance of i18next used within the Streami18n instance.

const i18n = streami18n.geti18Instance();

getTranslations#

Returns the current translations dictionaries for all languages.

const translations = streami18n.getTranslations();

getTranslators#

Asynchronous function that returns the current translator functions.

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

registerTranslation#

Allows you to register a custom translation, this will override a translation if one already exists for the given language code. The third parameter, which is optional, is a Day.js locale, which is structured the same as dayjsLocaleConfigForLanguage.

It is suggested you look at the enTranslations json file exported from stream-chat-react-native for a current list of used translation keys.

streami18n.registerTranslation(  'mr',  {    'Nothing yet...': 'काहीही नाही  ...',    '{{ firstUser }} and {{ secondUser }} are typing...':      '{{ firstUser }} आणि {{ secondUser }} टीपी करत आहेत',  });

Parameters#

NAMETYPEREQUIRED
languagestring✔️
translationobject✔️
customDayjsLocaleobject

setLanguage#

Asynchronous function that changes the current language and returns the 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');

Parameters#

NAMETYPEREQUIRED
languagestring✔️

Did you find this page helpful?