Implement internationalization (i18n) support for Video.js 10 — translated aria-labels, tooltips, time unit strings, and dialog copy, plus locale-aware Intl formatting. Works with or without a provider by inheriting the native HTML lang attribute, keeps skins presentation-only, and ships CDN-compatible locale modules.
Design doc: internal/design/i18n.md (status: implemented)
Goals
- Opaque camelCase keys —
play, seekForward, etc. English strings live in en.ts as values, not keys
- Global registry —
registerI18n(locale, translations) is the single entry point; locale files are ES modules that self-register
- Ambient
<html lang> inheritance — providers read the native lang attribute; zero config for the common case
- Decoupled from skins — skins are i18n-unaware; providers distribute context, components auto-forward labels via
I18nController
- Typed keys —
Translator enforces per-key param shapes via overloaded signatures and Contains<> template literals
- CDN-compatible — locale files are self-registering ES modules with no global namespace pollution
- Locale-aware formatting — native
Intl.DurationFormat, Intl.NumberFormat, Intl.PluralRules handle time, percent, and plural selection
PR stack (merge order)
Each PR stacks on the previous. All are open and ready for review.
PR 1 — Core foundation (#1589)
@videojs/core/i18n registry, translator, en.ts, browser Translation API fallback- Locale DOM helpers +
formatDuration in @videojs/utils
- Opaque translation keys across core UI components
PR 2 — Locale packs (#1590)
- ~50 v8-parity locale packs,
loadLocale, codegen, CDN locale stubs
- Workspace
check:workspace i18n consistency
PR 3 — HTML layer (#1591)
createI18n(), I18nController, <media-text>, CDN i18n entry- Control wiring and error dialog i18n helpers
PR 4 — React layer (#1595)
createI18n(), I18nProvider, useTranslator, preset wiring
PR 5 — Sandbox (#1593)
- Locale picker on all presets, shared helpers, e2e coverage
PR 6 — Docs (#1600)
- Concept page, how-to guides, API/util reference pages, sidebar wiring
Sub-issues
| Issue |
Tracks |
| #1363 |
Core types, registry, translator |
| #1368 |
Built-in locale packs |
| #1369 |
CDN i18n/locale build |
| #1365 |
HTML i18n layer |
| #1364 |
React i18n layer |
| #1594 |
Sandbox demos + e2e |
| #1373 |
Site docs |
Absorbed / out of scope
Architecture overview
@videojs/core/i18n
Translations · Translator · createTranslator · loadLocale
registerI18n · getI18nTranslations · onI18nRegistryChange
Registry (singleton Map) · en.ts (base layer, always present)
│
├── @videojs/react/i18n
│ createI18n() → { I18nProvider, useTranslator, useLocale }
│
└── @videojs/html/i18n
createI18n() → { I18nController, ProviderMixin, TextMixin }
<media-i18n-provider lang="es">, <media-text key="play">
MediaButtonElement uses I18nController → auto-forwards aria-labels
Implement internationalization (i18n) support for Video.js 10 — translated
aria-labels, tooltips, time unit strings, and dialog copy, plus locale-awareIntlformatting. Works with or without a provider by inheriting the native HTMLlangattribute, keeps skins presentation-only, and ships CDN-compatible locale modules.Design doc:
internal/design/i18n.md(status: implemented)Goals
play,seekForward, etc. English strings live inen.tsas values, not keysregisterI18n(locale, translations)is the single entry point; locale files are ES modules that self-register<html lang>inheritance — providers read the nativelangattribute; zero config for the common caseI18nControllerTranslatorenforces per-key param shapes via overloaded signatures andContains<>template literalsIntl.DurationFormat,Intl.NumberFormat,Intl.PluralRuleshandle time, percent, and plural selectionPR stack (merge order)
Each PR stacks on the previous. All are open and ready for review.
feat/i18n-corefeat/i18n-locale-packsfeat/i18n-htmlfeat/i18n-reactfeat/i18n-sandboxdocs/i18nPR 1 — Core foundation (#1589)
@videojs/core/i18nregistry, translator,en.ts, browser Translation API fallbackformatDurationin@videojs/utilsPR 2 — Locale packs (#1590)
loadLocale, codegen, CDN locale stubscheck:workspacei18n consistencyPR 3 — HTML layer (#1591)
createI18n(),I18nController,<media-text>, CDN i18n entryPR 4 — React layer (#1595)
createI18n(),I18nProvider,useTranslator, preset wiringPR 5 — Sandbox (#1593)
PR 6 — Docs (#1600)
Sub-issues
Absorbed / out of scope
<media-text>migration)Architecture overview