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 for app bundles; 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.

Read Internationalization first if you are new to phrase keys and the registry.

Prerequisites

  • A locale tag (BCP 47, e.g. es, pt-BR)
  • A partial translation map keyed by current English phrases (Play, 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 = {
  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', {
  Play: 'Reproducir',
  Pause: 'Pausa',
});

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

What’s next?