Localization

If your app targets multiple languages, the React Native UI components include built-in translations, and the Chat Client can translate message content. Supported UI languages include:

• English (en)
• Spanish (es)
• French (fr)
• Hebrew (he)
• Hindi (hi)
• Italian (it)
• Japanese (ja)
• Korean (ko)
• Dutch (nl)
• Russian (ru)
• Turkish (tr)
• Brazilian Portuguese (pt-BR)

Best Practices

• Create a single Streami18n instance and pass it to both OverlayProvider and Chat.
• Register custom translations before rendering UI to avoid flicker.
• Use device locale as a default but allow user overrides.
• Keep date/time localization aligned with your translation language.
• Validate key coverage by comparing against the English base file.

Usage

Streami18n provides static translations for the React Native UI components. It wraps an i18next config and exposes a focused API via stream-chat-react-native.

Create an instance to start using it:

const streami18n = new Streami18n();

Streami18n defaults to English (en). If you keep defaults with Day.js, the SDK manages the instance for you.

If you change language, translations, or date handling, pass your custom instance to OverlayProvider and Chat via i18nInstance. This provides it to all components via context.

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

Streami18n accepts optional options and i18nextConfig params to customize the instance.

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.

You can also call setLanguage to support a language toggle.

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

To add a language, register custom strings. Example with Polish:

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

See all available keys in the English file.

Overriding existing languages

You can also override specific strings for an existing language (for example, regional spelling). Use the same process as Adding a new language:

const streami18n = new Streami18n();

streami18n.registerTranslation("nl", {
  "Delete Message": "Verwijder bericht",
});

Using device locale to set language

You can use react-native-localize to read the user’s preferred locale and set the UI language:

import * as RNLocalize from "react-native-localize";
const streami18n = new Streami18n();

const userPreferredLocales = RNLocalize.getLocales();

streami18n.setLanguage(userPreferredLocales[0].languageCode);

Overriding DateTime format

The SDK uses Day.js by default to format dates and times. Day.js supports locales via locale support.

See all Day.js locale configs here.

You can provide a Day.js locale config when registering a language, or supply your own Day.js or Moment.js instance to the Streami18n constructor.

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, provide your own Moment instance:

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 provide your own Day.js instance:

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

To keep English date/time strings, set disableDateTimeTranslations to true.

Translating messages

If your user base speaks multiple languages, the Chat Client can auto-translate messages. See the Chat Client Guide on Translation.

Timezone location

To display dates in a specific timezone, pass timezone to the Streami18n constructor using a valid timezone identifier. If omitted, the device timezone is used.

import { Streami18n } from "stream-chat-react";
import momentTimezone from "moment-timezone";

const streami18n = new Streami18n({
  DateTimeParser: momentTimezone,
  timezone: "Europe/Budapest",
});

Moment Timezone will automatically load and extend the moment module, then return the modified instance. This will also prevent multiple versions of moment being installed in a project.

Options

options are 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.

| TYPE | DEFAULT | | ------ | ------- | ----- | | Dayjs | Moment | Dayjs |

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)
• Spanish (es)
• French (fr)
• Hebrew (he)
• Hindi (hi)
• Italian (it)
• Japanese (ja)
• Korean (ko)
• Dutch (nl)
• Russian (ru)
• Turkish (tr)

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