Switch locale dynamically

Change the player language at runtime in HTML and React

Video.js starts in English and re-resolves translations when you opt into another active locale.

Prerequisites

A target locale from a shipped lazy-loaded pack, a registered custom pack, or a Chrome browser translation fallback

Ambient `<html lang>`

The simplest switch updates the document language and lets providers pick it up:

document.documentElement.lang = 'fr';

Mounted <media-i18n> providers observe lang on <html> and ancestors. No remount required.

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:

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 React’s locale is explicit, the player applies its resolved lang and dir to the container. A lang or dir passed to that container overrides the rendered DOM boundary only; translations still come from I18nProvider locale.

In HTML, <media-i18n lang> sets the provider locale and derives its direction. An explicit dir on <media-i18n> overrides that derived direction.

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

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

RTL preserves playback control ordering and time-semantic media icons while mirroring menu motion and navigation chevrons. 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.

Explicit provider language

import { useState } from 'react';
import { I18nProvider } from '@videojs/react/i18n';
import { VideoPlayer, VideoSkin, Video } from '@videojs/react/video';

function App() {
  const [locale, setLocale] = useState<'en' | 'es' | 'fr'>('en');

  return (
    <>
      <button type="button" onClick={() => setLocale('es')}>
        Español
      </button>
      <VideoPlayer>
        <I18nProvider locale={locale}>
          <VideoSkin>
            <Video src="..." playsInline />
          </VideoSkin>
        </I18nProvider>
      </VideoPlayer>
    </>
  );
}

Changing locale triggers lazy loadLocale for built-in packs.

<media-i18n lang="es" id="provider">
  <video-player>...</video-player>
</media-i18n>

<script type="module">
  document.querySelector('#lang-picker').addEventListener('change', (e) => {
    document.getElementById('provider').lang = e.target.value;
  });
</script>

Or set document.documentElement.lang when the mounted <media-i18n> inherits ambient language.

Avoid flash while switching

Async lazy loads and browser translation fallback can briefly show English. Preload copy before the active locale changes with one of three common patterns:

Preload at bootstrap

Side-effect locale modules register shipped packs before the provider renders. Preload every language in a fixed picker to avoid the async gap.

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

// Switching locale is instant: no remount, no lazy-load gap
<I18nProvider locale={userLocale}>
  <VideoSkin>...</VideoSkin>
</I18nProvider>

import '@videojs/html/i18n/locales/es/register';
import '@videojs/html/i18n/locales/fr/register';

<media-i18n id="provider">
  <video-player>...</video-player>
</media-i18n>

<script type="module">
  document.getElementById('provider').lang = 'fr';
</script>

Prefetch before switching

When you cannot register every locale up front, import and register immediately before updating locale:

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) {
  const { default: translations } = await loaders[next]();
  registerI18n(next, translations);
  setLocale(next);
}

<I18nProvider locale={locale}>
  ...
</I18nProvider>

You still pay the import cost once per locale, but later switches to the same tag stay synchronous.

Scoped overrides with `translations`

Pass translations on I18nProvider when overrides should apply to one subtree only, or when you want copy colocated with the switch handler:

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

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

<I18nProvider locale={state.locale} translations={state.translations}>
  ...
</I18nProvider>

Approach	Scope	Best for
Side-effect locale imports	Global, all providers	Language picker with a fixed set of shipped locales
`registerI18n` before switch	Global, all providers	On-demand prefetch before changing `locale`
`I18nProvider translations`	Single provider subtree	Scoped overrides, SSR first paint

Browser translation fallback

If a switched locale has no registered or shipped pack, Video.js can use Chrome’s Browser Translation API when the browser exposes globalThis.Translator and already has the target model installed. This is automatic after lazy loading is attempted.

Do not rely on it for instant switching. Preload or register reviewed packs when the language picker should update without a flash of English.

What’s next?

SSR with locale
useLocale: Read the active locale in React