Skip to content
FrameworkStyle

Register a custom locale

Register translation packs for HTML, React, and CDN players

Video.js is English by default. Built-in packs lazy-load automatically when your app imports Video.js packages. Use registerI18n when you have custom strings, need synchronous first paint, or load locales from the CDN.

To opt into another language, mount <media-i18n> and set its lang attribute or an ancestor lang attribute.

Prerequisites

  • A locale tag (BCP 47, e.g. es, pt-BR)
  • A partial translation map keyed by semantic groups and names (buttons.play, buttons.pause, …)

Use a shipped pack synchronously

Built-in packs include side-effect modules that register a language before the player renders:

import '@videojs/html/video';
import '@videojs/html/i18n/locales/es/register';
<html lang="es">
  <media-i18n>
    <video-player>
      <video-skin>
        <video src="..." playsinline></video>
      </video-skin>
    </video-player>
  </media-i18n>
</html>

Without the side-effect import, <media-i18n> lazy-loads es when it resolves lang="es". The import makes the first paint synchronous.

Register your own pack

import type { Translations } from '@videojs/html/i18n';

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

export default es;
import { registerI18n } from '@videojs/html/i18n';
import es from './my-es';

registerI18n('es', es);

All keys are optional. Missing keys follow the locale fallback chain through a built-in pack, browser-translated copy in supported Chrome builds, or English.

CDN

Load the player and a locale chunk. CDN locale modules call registerI18n on import:

<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/html/cdn/video.js"></script>
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/html/cdn/locales/es.js"></script>

<html lang="es">
  <media-i18n>
    <video-player>
      <video-skin>
        <video src="..." playsinline></video>
      </video-skin>
    </video-player>
  </media-i18n>
</html>

Custom CDN locale

import { registerI18n } from 'https://cdn.jsdelivr.net/npm/@videojs/html/cdn/i18n.js';

registerI18n('es', {
  buttons: {
    play: 'Reproducir',
    pause: 'Pausa',
  },
});

Load your module after the player script and before playback starts.

What’s next?