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

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

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 Day.js internally by default to format DateTime stamp. Day.js is a lightweight alternative to Moment.js with the same modern API and has locale support as well.

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

You can either provide the Day.js locale config while registering language with Streami18n (either via constructor or registerTranslation()) or you can provide your own Day.js or Moment.js 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 locales
import 'moment/min/locales';

import Moment from moment;

const i18n = new Streami18n({
  language: 'nl',
  DateTimeParser: Moment,
});

Or by providing your own Day.js object:

import Dayjs from 'dayjs';

import 'dayjs/locale/nl';
import 'dayjs/locale/it';
// or if you want to include all locales
import '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 user-base 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 repository and used by default.

dayjsLocaleConfigForLanguage

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

debug

Enable debug mode in internal i18next instance.

disableDateTimeTranslations

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

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)

logger

Function to log warnings & errors from Streami18n.

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...',
  },
});

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.

fallbackLng

Fallback language setting for i18next.

interpolation

i18next interpolation setting for integrating dynamic values into translations.

keySeparator

Override character to separate keys.

lng

Override language to use.

nsSeparator

Override character to split namespace from key.

parseMissingKeyHandler

Function to handle keys missing translations for the selected language.

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

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