# Internationalize the player

Translate player labels and announcements: shipped locale packs, custom translations, runtime switching, and server rendering.

Translate every player label, tooltip, and screen-reader announcement. The player ships translations for more than 50 locales and loads them on demand.

## Recommended approach

Wrap the player in the i18n provider. It resolves the locale from your page’s `lang` attribute or an explicit override, then lazy-loads the matching locale pack. Every component label follows that locale.

```tsx
import { Container } from '@videojs/react';
import { I18nProvider } from '@videojs/react/i18n';
import { Video, VideoPlayer } from '@videojs/react/video';

export default function App() {
  return (
    <I18nProvider locale="ja">
      <VideoPlayer>
        <Container>
          <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
        </Container>
      </VideoPlayer>
    </I18nProvider>
  );
}
```

Omit `locale` to inherit a parent provider’s locale or follow the document’s `lang`. Use `langRootRef` to follow a particular DOM ancestor.

Pick a language and every label follows — no remount:

**App.tsx**

```tsx
import { createPlayer } from '@videojs/react';
import { I18nProvider } from '@videojs/react/i18n';
import { Video, VideoSkin, videoFeatures } from '@videojs/react/video';
import { useState } from 'react';

import '@videojs/react/video/skin.css';
import './Language.css';

const { Player } = createPlayer({ features: videoFeatures });
const locales = ['en', 'es', 'fr', 'de', 'ja', 'ar'] as const;

type Locale = (typeof locales)[number];
const languageNames = new Intl.DisplayNames(['en'], { type: 'language' });

export default function Language() {
  const [locale, setLocale] = useState<Locale>('en');

  return (
    <div className="react-i18n-language">
      <label>
        Language
        <select value={locale} onChange={(event) => setLocale(event.currentTarget.value as Locale)}>
          {locales.map((value) => (
            <option key={value} value={value}>
              {languageNames.of(value) ?? value}
            </option>
          ))}
        </select>
      </label>
      <Player>
        <I18nProvider locale={locale}>
          <VideoSkin className="react-i18n-language__player">
            <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
          </VideoSkin>
        </I18nProvider>
      </Player>
    </div>
  );
}
```

**App.css**

```css
.react-i18n-language {
  display: grid;
  gap: 16px;
  padding: 16px;
}

.react-i18n-language label {
  display: flex;
  gap: 8px;
  align-items: center;
}

.react-i18n-language select {
  padding: 4px 8px;
}

.react-i18n-language__player {
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## How it works

Component labels carry a translation key and an English default. The provider loads the resolved locale’s pack on demand. Locale fallback follows [BCP 47](https://www.rfc-editor.org/rfc/rfc5646) parent tags: `es-MX` checks `es`, then `en`.

The provider uses an explicit `locale` or inherits its parent provider’s locale. Otherwise it follows the document’s `lang`, with `'en'` as the fallback. To follow a particular DOM ancestor, pass `langRootRef` to [I18nProvider](https://videojs.org/docs/framework/react/reference/api/i18n-provider).

Each label uses the first available value:

1. The provider’s `translations` prop
2. The shared registry
3. The lazy-loaded locale pack
4. The component’s English default

[`registerI18n(locale, translations)`](https://videojs.org/docs/framework/react/reference/api/register-i18n) adds or replaces keys in the shared registry. Mounted providers pick up later registrations. Registering any strings for a locale prevents its pack from loading automatically. For partial global overrides, import the locale’s `/register` entry first, as shown below. This keeps the full translation available after a locale switch or provider remount.

When no shipped pack matches, the provider can use the browser’s on-device Translation API. Supply your own translations when you need reviewed wording or consistent availability across browsers.

Translate your own UI with the same machinery:

```tsx
import { useTranslator } from '@videojs/react/i18n';

function StartButton() {
  const t = useTranslator();
  return <button type="button">{t('buttons.play', { default: 'Play' })}</button>;
}
```

`default` is the English text. English ships inside component descriptors. There is no built-in `en` pack, so `t(key)` without a `default` renders the key itself under `en`. When a locale pack is active, the key selects its translation.

## Availability and constraints

- English is built in; every other locale is a lazy-loaded pack. Server rendering needs an explicit `locale` since there’s no DOM to resolve from.
- Locale tags are [BCP 47](https://www.rfc-editor.org/rfc/rfc5646) (`es`, `pt-BR`).
- Translation keys are namespaced strings (`buttons.play`, `errors.network`, `menu.quality`). The full list is in [Translation phrases](https://videojs.org/docs/framework/react/reference/api/translation-phrases). The keys are typed, so typos in `registerI18n` objects fail in TypeScript. The translator itself accepts any string; a mistyped `t()` key falls back to its `default`.
- Some strings interpolate parameters; custom translations must keep the placeholders:

```ts
// ✅
registerI18n('es', { seek: { forward: 'Adelantar {seconds} segundos' } });

// ❌ The interpolated value is lost
registerI18n('es', { seek: { forward: 'Adelantar' } });
```

- The Browser Translation API fallback needs Chrome with `globalThis.Translator` and downloads an on-device model on first use. It’s best-effort; ship a real pack for languages you support officially.

## Common variations

### Override specific strings

Pass `translations` on [`I18nProvider`](https://videojs.org/docs/framework/react/reference/api/i18n-provider) to scope overrides to one subtree. These overrides take precedence over the registry and lazy-loaded packs:

```tsx
<I18nProvider locale="ja" translations={{ buttons: { play: '再生', pause: '一時停止' } }}>
  {/* player */}
</I18nProvider>
```

Nested providers inherit the parent locale when you only pass `translations`.

For global overrides, register the full locale pack before your custom strings:

```ts
import '@videojs/react/i18n/locales/ja/register';
import { registerI18n } from '@videojs/react/i18n';

registerI18n('ja', { buttons: { play: '再生', pause: '一時停止' } });
```

The pack supplies the remaining labels. Later calls replace only the keys you pass.

### Register your own locale

Register strings for a locale your application supports. Missing keys fall back to registered parent strings, then a shipped parent pack, then English. For example, register a few `es-MX` labels and the `es` pack supplies the rest. If the tag has its own shipped pack, registering strings for it prevents that pack from loading. Use the full-pack pattern above for that case.

```ts
import { registerI18n, type Translations } from '@videojs/react/i18n';

const esMX = {
  buttons: {
    play: 'Reproducir',
    pause: 'Pausa',
    mute: 'Silenciar',
    unmute: 'Activar sonido',
  },
} satisfies Partial<Translations>;

registerI18n('es-MX', esMX);
```

### Register a pack with the bundle

Skip lazy loading by registering a shipped locale at startup with a side-effect import. Labels render in that language on first paint:

```ts
import '@videojs/react/i18n/locales/ja/register';
```

### Switch locale at runtime

The simplest switch updates the document language and lets providers pick it up — no remount required:

```ts
document.documentElement.lang = 'fr';
```

Switching through the document language works only when `I18nProvider` has no explicit `locale`. To switch from React state instead:

```tsx
import { useState, type ReactNode } from 'react';
import { I18nProvider } from '@videojs/react/i18n';

export default function LocaleSwitcher({ children }: { children: ReactNode }) {
  const [locale, setLocale] = useState<'en' | 'es' | 'fr'>('en');

  return (
    <>
      <label>
        Language
        <select value={locale} onChange={(event) => setLocale(event.target.value as typeof locale)}>
          <option value="en">English</option>
          <option value="es">Español</option>
          <option value="fr">Français</option>
        </select>
      </label>
      <I18nProvider locale={locale}>{children}</I18nProvider>
    </>
  );
}
```

Wrap your player in `LocaleSwitcher`.

Changing `locale` lazy-loads the pack, which can briefly show English. Preload the locales your picker offers:

```tsx
import '@videojs/react/i18n/locales/es/register';
import '@videojs/react/i18n/locales/fr/register';
```

Or prefetch and register right before switching when you can’t register everything up front:

```tsx
import { registerI18n } from '@videojs/react/i18n';

const loaders = {
  es: () => import('@videojs/react/i18n/locales/es'),
  fr: () => import('@videojs/react/i18n/locales/fr'),
};

async function switchTo(next: keyof typeof loaders, setLocale: (locale: keyof typeof loaders) => void) {
  const { default: translations } = await loaders[next]();
  registerI18n(next, translations);
  setLocale(next);
}
```

Call `switchTo(next, setLocale)` from your language picker.

### Set text direction

`lang` identifies the content language. `dir` controls text and layout direction. Browsers do not infer one from the other, so set both when the locale applies to the whole document:

```ts
document.documentElement.lang = 'ar';
document.documentElement.dir = 'rtl';
```

Set `dir` back to `ltr` when you switch to a left-to-right language. This prevents the previous direction from remaining active.

When `I18nProvider` has an explicit `locale`, the player applies its resolved `lang` and `dir` to the container. A `lang` or `dir` you pass to that container changes only the container’s rendered attributes. Translations still come from the `I18nProvider` `locale`.

Providers without an explicit locale inherit ambient document language and direction. In that case, set `lang` and `dir` on `<html>` or another ancestor:

```html
<html lang="ar" dir="rtl">
```

In RTL layouts, playback controls keep their order and time-related media icons keep their direction. Menu motion and navigation chevrons mirror. Horizontal time and volume sliders retain a physical left-to-right value scale: Left Arrow decreases the value, Right Arrow increases it, and the minimum remains on the left.

### Replace a component’s visible text

Translation overrides change built-in labels everywhere they appear. To replace only one component’s visible content, set its children — and use the translation machinery when that content should still follow the active locale:

```tsx
import { LiveButton } from '@videojs/react';

<LiveButton>On air</LiveButton>
```

Authored children are literal; use `useTranslator` when custom children also need localization. For state-dependent text, render one element per state and show or hide them with the component’s `data-*` state attributes (the same pattern used for icons).

The component still derives its accessible name from media state unless you also set its label API. Keep custom visible text consistent with that name.

### Server rendering

Render the document language on the server (`<html lang="es">`) and make translations available before first paint so labels match on server and client:

Import the pack on the server and pass it as `translations` so server-rendered labels and the first client render use the same strings. The provider can still load a locale pack on the client; the supplied strings take precedence:

```tsx
import type { ReactNode } from 'react';
import { I18nProvider } from '@videojs/react/i18n';

const loaders = {
  es: () => import('@videojs/react/i18n/locales/es'),
  fr: () => import('@videojs/react/i18n/locales/fr'),
};

export async function Player({ locale, children }: { locale: string; children: ReactNode }) {
  const load = loaders[locale as keyof typeof loaders];
  if (!load) throw new Error(`Unsupported locale: ${locale}`);
  const { default: translations } = await load();

  return (
    <I18nProvider locale={locale} translations={translations}>
      {children}
    </I18nProvider>
  );
}
```

Pass `locale` explicitly on the server — there’s no DOM to resolve `lang` from, and an explicit value avoids hydration mismatches. With app routers, pass the tag your framework negotiates (for next-intl, `await getLocale()`); Video.js doesn’t replace framework i18n, it consumes the tag you give it.

## Troubleshooting

### Labels stay in English

Check that a provider is mounted and that its `locale`/`lang` value matches a shipped pack. Regional tags fall back to their base language, so `pt-BR` works. An unmatched language falls back to English unless the browser’s Translation API supplies translations; register your own pack for consistent coverage.

### Some strings are translated, others aren’t

If you registered partial global overrides before the locale pack loaded, the loader skips that pack. Import its `/register` entry before your overrides. For a custom locale, supply missing keys in your pack; they fall back to English until you do.

### Translations flash in after load or after switching

The lazy pack loads after first paint (or after the switch). Register the pack with the bundle (the `/register` side-effect import), or prefetch and register before changing the locale.

### Server-rendered labels don’t match the client

The provider resolved different locales on server and client. Pass an explicit `locale` and first-render `translations` instead of relying on ambient `lang`.

## Related pages

### Components

- [I18nProvider](https://videojs.org/docs/framework/react/reference/api/i18n-provider): React provider that resolves locale and supplies a typed translator to descendants

### API

- [registerI18n](https://videojs.org/docs/framework/react/reference/api/register-i18n): Register or merge translation strings for a BCP 47 locale tag in the global i18n registry
- [Translation phrases](https://videojs.org/docs/framework/react/reference/api/translation-phrases): Semantic i18n keys, their English defaults, and the player UI that uses them
- [useTranslator](https://videojs.org/docs/framework/react/reference/api/use-translator): React hook that returns the typed translator for the nearest I18nProvider
- [useLocale](https://videojs.org/docs/framework/react/reference/api/use-locale): React hook that returns the active BCP 47 locale from the nearest I18nProvider
- [getI18nTranslations](https://videojs.org/docs/framework/react/reference/api/get-i18n-translations): Read the merged translation map for a locale using BCP 47 parent-chain fallback

### Guides

- [Show captions and subtitles](https://videojs.org/docs/framework/react/guides/captions): Show captions and subtitles, and let users turn them on and pick a language.
- [Accessibility](https://videojs.org/docs/framework/react/guides/accessibility): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player

---

React documentation: https://videojs.org/docs/framework/react/llms.txt
All documentation: https://videojs.org/llms.txt
