# Localization

Built-in translation service powered by [`i18next`](https://www.i18next.com/) for language switching and custom translations.

## Best Practices

- Use `useI18n()` hook to access the `t()` translation function.
- Override translations via `translationsOverrides` prop on `StreamVideo`.
- Set language via `language` prop - must match a key in your translations.
- For advanced control, create your own `StreamI18n` instance and pass via `i18nInstance`.

## Integration

The service is made available through the `StreamVideo` provider. That means that all the child components of this provider can access the `StreamI18nContextValue` object by using the `useI18n` context consumer.

The `StreamI18nContextValue` carries the following properties:

1. **the translator function `t`** - expects to receive a string to translate and returns its translation or the original value, if no translation for the given key and language could be found.
2. **the `StreamI18n` instance** - allows for more control over the service

It is also possible to use `StreamI18nProvider` without the `StreamVideo` provider. Again, all the child components of this provider can access the `StreamI18nContextValue` object by using the `useI18n` context consumer.

### Configuration

What ends up in the `StreamI18nContextValue` depends on what configuration parameters we provide to the `StreamI18nProvider`. These are:

```ts
type StreamI18nProviderProps = {
  i18nInstance?: StreamI18n;
  language?: string;
  fallbackLanguage?: string;
  translationsOverrides?: TranslationsMap;
};
```

<Admonition type="note">

`StreamVideo` internally forwards these parameters to `StreamI18nProvider`.

</Admonition>

In the following sections, we will look more into these individual configuration parameters.

#### Custom translations

In case you would like to add to or change the default translations, you can use the `translationsOverrides` prop. This should be an object that will match the type `TranslationsMap`.

```ts
type TranslationsMap = Record<TranslationLanguage, TranslationSheet>;

type TranslationLanguage = keyof typeof defaultTranslations | string;

type TranslationSheet = typeof defaultTranslations.en | Record<string, string>;
```

The translations are merged with the SDK's defaults. That means that the defaults are overridden or new keys are added to the translation sheets.

```tsx
const translations = {
  en: {
    // ...
    terminate: "terminate",
    // ...
  },
  de: {
    // ...
    terminate: "beended",
    // ...
  },
  // ...
};

const App = () => {
  // ...
  return (
    <StreamVideo client={client} translationsOverrides={translations}>
      // ...
    </StreamVideo>
  );
};
```

#### Provide your own instance of `StreamI18n`

You may want to initialize the service somewhere else and pass the instance through the prop `i18nInstance`. If an instance of `StreamI18n` is provided, it will be forwarded to the context without any changes.

```tsx
type CreateI18nParams = {
  language?: string;
  translationsOverrides?: TranslationsMap;
};

const useCreateI18n = ({
  language,
  translationsOverrides,
}: CreateI18nParams) => {
  const i18nRef = useRef(
    new StreamI18n({ currentLanguage: language, translationsOverrides }),
  );

  useEffect(() => {
    const i18n = i18nRef.current;
    if (i18n.isInitialized && language && i18n?.currentLanguage !== language) {
      i18n.changeLanguage(language);
    } else if (!i18n.isInitialized) {
      // sets the default language
      if (!language) i18n.changeLanguage();
      i18n.init();
    }
  }, [language, translationsOverrides]);

  return i18n;
};

const App = () => {
  const i18n = useCreateI18n();

  return (
    <StreamVideo client={client} i18nInstance={i18n}>
      ...
    </StreamVideo>
  );
};
```

#### Language

You can set the current language for the translation service with `language` prop. This should be a language code (for example `en`, `de` etc.) that matches a key in `translationsOverrides` or is among the SDK's default language mutations which are specified by the type `TranslationLanguage`.

```tsx
const App = () => {
  /*  a hook that keeps track of the current language in your app  */
  const { language, setLanguage } = useLanguage();
  // ...
  return (
    <StreamVideo
      client={client}
      language={language}
      translationsOverrides={translations}
    >
      {/*...*/}
    </StreamVideo>
  );
};
```

## Translation function

This is the central feature of the service. The function is passed a string we want to translate and returns its translation. If the translated key is not found, then the returned value is the original string. We rely on the translation function provided by the library `i18next`. This function is exposed on `StreamI18n` object as well as in the `StreamI18nContextValue`.

### Accessing the translation function

You can access the translation function in any child component of `StreamVideo` resp. `StreamI18nProvider` through the context consumer `useI18n`:

```tsx
import { useI18n } from "@stream-io/video-react-sdk";

const CustomButton = () => {
  const { t } = useI18n();

  return <button>{t("Submit")}</button>;
};
```

## Final recommendations

As the translation service is based on `i18next` which `i18n` instance is made available through `StreamI18n`, we encourage you to consult the library's documentation in order to learn about:

- the use of <a href="https://www.i18next.com/translation-function/essentials" target="_blank">the translation function</a>
- how to dynamically insert text with <a href="https://www.i18next.com/translation-function/interpolation" target="_blank">interpolation documentation article</a>
- how to format interpolated value <a href="https://www.i18next.com/translation-function/formatting" target="_blank">i18next's formatting guide</a>
- how to specify different plural forms with <a href="https://www.i18next.com/translation-function/plurals" target="_blank">the pluralization guide</a>


---

This page was last updated at 2026-08-10T16:01:04.695Z.

For the most recent version of this documentation, visit [https://getstream.io/video/docs/react/guides/localization/](https://getstream.io/video/docs/react/guides/localization/).