# 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)](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/i18n/en.json)
- [Spanish (es)](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/i18n/es.json)
- [French (fr)](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/i18n/fr.json)
- [Hebrew (he)](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/i18n/he.json)
- [Hindi (hi)](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/i18n/hi.json)
- [Italian (it)](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/i18n/it.json)
- [Japanese (ja)](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/i18n/ja.json)
- [Korean (ko)](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/i18n/ko.json)
- [Dutch (nl)](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/i18n/nl.json)
- [Russian (ru)](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/i18n/ru.json)
- [Turkish (tr)](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/i18n/tr.json)
- [Brazilian Portuguese (pt-BR)](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/i18n/pt-BR.json)

## 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](https://www.i18next.com/) config and exposes a focused API via `stream-chat-react-native`.

Create an instance to start using it:

```tsx
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`](https://react.dev/reference/react/createContext).

```tsx
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:

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

You can also call [`setLanguage`](/chat/docs/sdk/react-native/basics/translations/#setlanguage/) to support a language toggle.

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

```tsx
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:

```tsx
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](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/i18n/en.json).

### 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](#adding-a-new-language):

```tsx
const streami18n = new Streami18n();

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

### Using device locale to set language

You can use [`react-native-localize`](https://github.com/zoontek/react-native-localize#-react-native-localize) to read the user’s preferred locale and set the UI language:

```tsx
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](https://day.js.org/en/) by default to format dates and times. Day.js supports locales via [locale support](https://day.js.org/docs/en/i18n/i18n).

See all Day.js locale configs [here](https://github.com/iamkun/dayjs/tree/dev/src/locale).

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.

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

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

```tsx
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`](https://momentjs.com/) instance:

```tsx
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](https://day.js.org/docs/en/installation/installation) instance:

```tsx
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](/chat/docs/react-native/translation/).

### Timezone location

To display dates in a specific timezone, pass `timezone` to the `Streami18n` constructor using a valid [timezone identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). If omitted, the device timezone is used.

<admonition type="note">

Timezone support requires `moment-timezone` (not default Day.js) due to [this issue](https://github.com/iamkun/dayjs/issues/1377). Pass the `moment-timezone` object as `DateTimeParser` in the `Streami18n` constructor.

</admonition>

```tsx
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](https://day.js.org/) or [Moment](https://momentjs.com/) 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](https://day.js.org/docs/en/customization/customization) 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.

| Type   |
| ------ |
| Object |

### debug

Enable [debug mode](https://www.i18next.com/overview/configuration-options#logging) in internal i18next instance.

| TYPE    | DEFAULT |
| ------- | ------- |
| Boolean | false   |

### disableDateTimeTranslations

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

| TYPE    | DEFAULT |
| ------- | ------- |
| Boolean | false   |

### 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`)

| TYPE   | DEFAULT |
| ------ | ------- |
| String | `en`    |

### logger

Function to log warnings & errors from `Streami18n`.

| TYPE                   | DEFAULT      |
| ---------------------- | ------------ |
| (msg?: string) => void | console.warn |

### translationsForLanguage

Allows you to override the provided translations for given keys.

```tsx
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](https://www.i18next.com/translation-function/essentials#overview-options).

### debug

Enable [debug mode](https://www.i18next.com/overview/configuration-options#logging) in internal i18next instance. This overrides the [`debug key on options`](/chat/docs/sdk/react-native/basics/translations/#debug/) if provided.

| Type    |
| ------- |
| Boolean |

### `fallbackLng`

Fallback language setting for i18next.

| Type                                                                  |
| --------------------------------------------------------------------- |
| [`FallbackLng`](https://www.i18next.com/principles/fallback#fallback) |

### `interpolation`

i18next interpolation setting for integrating dynamic values into translations.

| TYPE                                                                               | DEFAULT                  |
| ---------------------------------------------------------------------------------- | ------------------------ |
| [Object](https://www.i18next.com/translation-function/interpolation#interpolation) | `{ escapeValue: false }` |

### `keySeparator`

Override character to separate keys.

| TYPE              | DEFAULT |
| ----------------- | ------- |
| String \| Boolean | false   |

### `lng`

Override language to use.

| Type   |
| ------ |
| String |

### `nsSeparator`

Override character to split namespace from key.

| TYPE              | DEFAULT |
| ----------------- | ------- |
| String \| boolean | false   |

### `parseMissingKeyHandler`

Function to handle keys missing translations for the selected language.

| TYPE                      | DEFAULT      |
| ------------------------- | ------------ |
| `(key: string) => string` | (key) => key |

## Methods

### `getAvailableLanguages`

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

```tsx
const availableLanguages = streami18n.getAvailableLanguages();
```

### `geti18Instance`

Returns instance of i18next used within the `Streami18n` instance.

```tsx
const i18n = streami18n.geti18Instance();
```

### `getTranslations`

Returns the current translations dictionaries for all languages.

```tsx
const translations = streami18n.getTranslations();
```

### `getTranslators`

Asynchronous function that returns the current translator functions.

```tsx
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](#dayjslocaleconfigforlanguage).

It is suggested you look at the [`enTranslations.json file`](https://github.com/GetStream/stream-chat-react/blob/master/src/i18n/en.json) exported from `stream-chat-react-native` for a current list of used translation keys.

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

#### Parameters

| NAME                | TYPE   | REQUIRED |
| ------------------- | ------ | -------- |
| `language`          | String | ✔️       |
| `translation`       | Object | ✔️       |
| `customDayjsLocale` | Object |          |

### `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.

```tsx
const t = await streami18n.setLanguage("nl");
```

#### Parameters

| NAME       | TYPE   | REQUIRED |
| ---------- | ------ | -------- |
| `language` | String | ✔️       |


---

This page was last updated at 2026-03-06T17:06:10.193Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react-native/basics/translations/](https://getstream.io/chat/docs/sdk/react-native/basics/translations/).