THEOplayer · MattiasBuelens · May 29, 2026 · May 6, 2025 · May 6, 2025 · May 6, 2025
diff --git a/.changeset/gold-pants-sleep.md b/.changeset/gold-pants-sleep.md
@@ -0,0 +1,6 @@
+---
+'@theoplayer/react-ui': minor
+'@theoplayer/web-ui': minor
+---
+
+Added localization support. Use `addLocale()` to register a locale, and set the `lang` attribute on the UI to apply it.
diff --git a/docs/guides/custom-component.mdx b/docs/guides/custom-component.mdx
@@ -1,6 +1,7 @@
 ---
 description: Build custom components that integrate with the player, and which you can use in your own custom UI.
 sidebar_position: 2
+sidebar_custom_props: { 'icon': '🧩' }
 ---
 
 # Making a custom component

diff --git a/docs/guides/custom-ui.md b/docs/guides/custom-ui.md
@@ -4,6 +4,7 @@ title: Making a custom UI
 permalink: /guides/custom-ui
 description: Build a custom player from scratch, starting from a basic player and gradually adding more features.
 sidebar_position: 1
+sidebar_custom_props: { 'icon': '🎨' }
 ---
 
 Although the default UI was designed to support a variety of usage scenarios, you may still run into a case that it doesn't handle very well. Perhaps you want to move some buttons around, or add like and dislike buttons to the control bar, or perhaps integrate a text chat component inside your player. In these situations, you may want to build a custom player UI to create a truly unique experience for your viewers.

diff --git a/docs/guides/localization.md b/docs/guides/localization.md
@@ -0,0 +1,96 @@
+---
+layout: page
+title: Localization
+permalink: /guides/localization
+description: Localize your UI to support different languages.
+sidebar_position: 3
+sidebar_custom_props: { 'icon': '🌍' }
+---
+
+The Open Video UI for Web can be localized to different languages,
+enabling you to reach audiences from different regions of the world.
+
+Localization works by [registering one or more locales](#register-a-locale)
+and then [selecting one of the registered locales using the `lang` attribute](#select-a-language).
+
+## Register a locale
+
+A locale is a JavaScript object mapping translation IDs to translated messages.
+You can register a locale with the `addLocale` function:
+
+```javascript title="French locale"
+import { addLocale } from '@theoplayer/web-ui';
+
+addLocale('fr', {
+    playAria: 'lire',
+    pauseAria: 'pauser',
+    replayAria: 'revoir'
+    // ...
+});
+```
+
+Some messages may need to be formatted with one or more values, based on the configuration or active state of the
+player. For those messages, the translation ID maps to a JavaScript function that takes those values as arguments
+and returns the formatted translation.
+
+```javascript title="French locale (continued)"
+addLocale('fr', {
+    // ...
+    seekForwardAria: (offset) => `avancer de ${offset}`,
+    seekBackwardAria: (offset) => `reculer de ${offset}`
+    // ...
+});
+```
+
+Refer to the [`Locale` interface definition](https://theoplayer.github.io/web-ui/api/interfaces/Locale.html)
+in the API references for the complete list of translatable messages.
+
+## Select a language
+
+The UI automatically selects the locale based on the `lang` attribute of the `<theoplayer-ui>`
+(or `<theoplayer-default-ui>`) element, or from the closest parent element with such an attribute.
+
+The value of the `lang` attribute must exactly match the locale name as it was passed to `addLocale`.
+
+```html title="Setting the language on the UI"
+<theoplayer-default-ui lang="fr" source='{"sources":{"src":"https://example.com/stream.m3u8"}}'></theoplayer-default-ui>
+```
+
+You can also put the `lang` attribute on any parent element. For example, if the entire page is in French, you could put
+the attribute on the `<html>` element:
+
+```html title="Setting the language on the HTML document"
+<!doctype html>
+<!-- highlight-next-line -->
+<html lang="fr">
+    <head>
+        <title>Ma page</title>
+    </head>
+    <body>
+        <theoplayer-default-ui source='{"sources":{"src":"https://example.com/stream.m3u8"}}'></theoplayer-default-ui>
+    </body>
+</html>
+```
+
+## Remarks
+
+### Update translations when upgrading Open Video UI
+
+Newer versions of the Open Video UI for Web may add new messages that need to be translated.
+We follow [semantic versioning](https://semver.org/), so new messages can only be added in _major_ or _minor_ versions.
+
+When using custom translations in your app, we recommend pinning the `@theoplayer/web-ui` dependency
+in your app's `package.json` to a specific minor version using a tilde constraint (`~`).
+Avoid using a caret constraint (`^`), since this may cause upgrading past your currently selected minor version.
+
+```json title="package.json"
+{
+    "dependencies": {
+        "@theoplayer/web-ui": "~2.2.0"
+    }
+}
+```
+
+When you decide to upgrade Open Video UI to the latest version, make sure to also update your translations.
+Check the history for [`i18n/Locale.ts`](https://github.com/THEOplayer/web-ui/commits/main/src/i18n/Locale.ts)
+to see whether any messages were added or changed since the previous version.
diff --git a/docs/guides/migrating-to-v2.md b/docs/guides/migrating-to-v2.md
@@ -3,6 +3,7 @@ layout: page
 title: Migrating to Open Video UI for Web 2.x
 permalink: /guides/migrating-to-v2
 sidebar_position: 10
+sidebar_custom_props: { 'icon': '⬆️' }
 ---
 
 This article will guide you through updating to Open Video UI for Web version 2 (from version 1),

diff --git a/docs/react/guides/localization.md b/docs/react/guides/localization.md
@@ -0,0 +1,79 @@
+---
+layout: page
+title: Localization
+slug: /react/guides/localization
+description: Localize your UI to support different languages.
+sidebar_position: 1
+sidebar_custom_props: { 'icon': '🌍' }
+---
+
+The Open Video UI for React can be localized to different languages,
+enabling you to reach audiences from different regions of the world.
+
+Localization works by [registering one or more locales](#register-a-locale)
+and then [selecting one of the registered locales using the `lang` prop](#select-a-language).
+
+## Register a locale
+
+A locale is a JavaScript object mapping translation IDs to translated messages.
+You can register a locale with the `addLocale` function:
+
+```javascript title="French locale"
+import { addLocale } from '@theoplayer/react-ui';
+
+addLocale('fr', {
+    playAria: 'lire',
+    pauseAria: 'pauser',
+    replayAria: 'revoir'
+    // ...
+});
+```
+
+Some messages may need to be formatted with one or more values, based on the configuration or active state of the
+player. For those messages, the translation ID maps to a JavaScript function that takes those values as arguments
+and returns the formatted translation.
+
+```javascript title="French locale (continued)"
+addLocale('fr', {
+    // ...
+    seekForwardAria: (offset) => `avancer de ${offset}`,
+    seekBackwardAria: (offset) => `reculer de ${offset}`
+    // ...
+});
+```
+
+Refer to the [`Locale` interface definition](https://theoplayer.github.io/web-ui/react-api/interfaces/Locale.html)
+in the API references for the complete list of translatable messages.
+
+## Select a language
+
+The UI automatically selects the locale based on the `lang` prop of the `<UIContainer>` (or `<DefaultUI>`) component.
+
+The value of the `lang` prop must exactly match the locale name as it was passed to `addLocale`.
+
+```jsx title="Setting the language on the UI"
+<DefaultUI lang="fr" source={{ sources: { src: 'https://example.com/stream.m3u8' } }} />
+```
+
+## Remarks
+
+### Update translations when upgrading Open Video UI
+
+Newer versions of the Open Video UI for React may add new messages that need to be translated.
+We follow [semantic versioning](https://semver.org/), so new messages can only be added in _major_ or _minor_ versions.
+
+When using custom translations in your app, we recommend pinning the `@theoplayer/react-ui` dependency
+in your app's `package.json` to a specific minor version using a tilde constraint (`~`).
+Avoid using a caret constraint (`^`), since this may cause upgrading past your currently selected minor version.
+
+```json title="package.json"
+{
+    "dependencies": {
+        "@theoplayer/react-ui": "~2.2.0"
+    }
+}
+```
+
+When you decide to upgrade Open Video UI to the latest version, make sure to also update your translations.
+Check the history for [`i18n/Locale.ts`](https://github.com/THEOplayer/web-ui/commits/main/src/i18n/Locale.ts)
+to see whether any messages were added or changed since the previous version.
diff --git a/docs/react/guides/migrating-to-v2.md b/docs/react/guides/migrating-to-v2.md
@@ -2,6 +2,8 @@
 layout: page
 title: Migrating to Open Video UI for React 2.x
 slug: /react/guides/migrating-to-v2
+sidebar_position: 10
+sidebar_custom_props: { 'icon': '⬆️' }
 ---
 
 This article will guide you through updating to Open Video UI for React version 2 (from version 1),

diff --git a/examples/default-ui.html b/examples/default-ui.html
@@ -46,6 +46,8 @@
         <script async src="https://ga.jspm.io/npm:es-module-shims@2.6.2/dist/es-module-shims.js" crossorigin="anonymous"></script>
         <script type="module">
             import * as THEOplayerUI from '@theoplayer/web-ui';
+            import './locale/nl.js';
+
             self.THEOplayerUI = THEOplayerUI;
         </script>
         <!-- Legacy browsers -->
@@ -70,6 +72,15 @@ <h1>Default UI</h1>
                 </select>
             </label>
         </div>
+        <div>
+            <label style="user-select: none">
+                Language:
+                <select id="language-select">
+                    <option value="en" selected>English</option>
+                    <option value="nl">Nederlands (Dutch)</option>
+                </select>
+            </label>
+        </div>
         <script>
             const ui = document.querySelector('theoplayer-default-ui');
             const sources = {
@@ -112,6 +123,9 @@ <h1>Default UI</h1>
             document.querySelector('#source-select').addEventListener('change', (e) => {
                 ui.source = sources[e.target.value];
             });
+            document.querySelector('#language-select').addEventListener('change', (e) => {
+                ui.lang = e.target.value;
+            });
         </script>
     </body>
 </html>
diff --git a/examples/locale/nl.js b/examples/locale/nl.js
@@ -0,0 +1,92 @@
+import { addLocale } from '@theoplayer/web-ui';
+
+/**
+ * Dutch (Nederlands)
+ */
+addLocale('nl', {
+    playAria: 'afspelen',
+    pauseAria: 'pauzeren',
+    replayAria: 'opnieuw afspelen',
+    muteAria: 'dempen',
+    unmuteAria: 'dempen opheffen',
+    volumeAria: 'volume',
+    seekAria: 'zoeken',
+    seekForwardAria: (offset) => `spring voorwaarts met ${offset}`,
+    seekBackwardAria: (offset) => `spring achterwaarts met ${offset}`,
+    live: 'LIVE',
+    seekToLiveAria: 'spring naar live',
+    fullscreenAria: 'volledig scherm',
+    fullscreenExitAria: 'volledig scherm sluiten',
+    airplayAria: 'start met afspelen op AirPlay',
+    airplayConnectedAria: 'stop met afspelen op AirPlay',
+    chromecastAria: 'start met afspelen op Chromecast',
+    chromecastConnectedAria: 'stop met afspelen op Chromecast',
+    chromecastHeading: 'Aan het afspelen op',
+    chromecastDefaultReceiverName: 'Chromecast',
+    timeOfTotalAria: (currentTime, totalDuration) => `${currentTime} van ${totalDuration}`,
+    playbackTimeAria: 'afspeeltijd',
+    unknownTimeAria: 'video niet ingeladen, onbekende tijd',
+    adText: 'Advertentie',
+    adBreakText: (currentAd, totalAds) => `Advertentie ${currentAd} van ${totalAds}`,
+    adClickThroughText: 'Adverteerder bezoeken',
+    adCountdownText: (remainingDuration) => `Video wordt hervat in ${remainingDuration}`,
+    adSkipButtonText: 'Overslaan',
+    adSkipCountdownText: (remainingDuration) => `Overslaan in ${remainingDuration}`,
+    liveStreamLoading: 'Laden...',
+    liveStreamOffline: `De livestream is nog niet gestart`,
+    closeMenuAria: 'menu sluiten',
+    openLanguageMenuAria: 'taalmenu openen',
+    languageMenuHeading: 'Taal',
+    audioMenuHeading: 'Audio',
+    subtitleMenuHeading: 'Ondertitels',
+    subtitleOff: 'Uit',
+    openPlaybackRateMenuAria: 'afspeelsnelheidmenu openen',
+    playbackRateMenuHeading: 'Afspeelsnelheid',
+    formatPlaybackRate: (rate) => (rate === 1 ? 'Normaal' : `${rate}x`),
+    openSettingsMenuAria: 'instellingenmenu openen',
+    settingsMenuHeading: 'Instellingen',
+    qualityMenuHeading: 'Kwaliteit',
+    textTrackStyleMenuHeading: 'Opties voor ondertitels',
+    textTrackStyleFontFamily: 'Lettertype',
+    textTrackStyleFontColor: 'Tekstkleur',
+    textTrackStyleFontOpacity: 'Ondoorzichtigheid van tekst',
+    textTrackStyleFontSize: 'Lettergrootte',
+    textTrackStyleBackgroundColor: 'Achtergrondkleur',
+    textTrackStyleBackgroundOpacity: 'Ondoorzichtigheid van achtergrond',
+    textTrackStyleWindowColor: 'Vensterkleur',
+    textTrackStyleWindowOpacity: 'Ondoorzichtigheid van venster',
+    textTrackStyleEdgeStyle: 'Randstijl van tekens',
+    textTrackStyleDefaultLabel: 'Standaard',
+    textTrackStyleCustomLabel: 'Aangepast',
+    textTrackStyleResetLabel: 'Opnieuw instellen',
+    fontFamilyLabels: {
+        'Monospace Serif': 'Serif met gelijke tekenbreedte',
+        'Proportional Serif': 'Proportionele serif',
+        'Monospace Sans': 'Sans-serif met gelijke tekenbreedte',
+        'Proportional Sans': 'Proportionele sans-serif'
+    },
+    colorLabels: {
+        White: 'Wit',
+        Yellow: 'Geel',
+        Green: 'Groen',
+        Cyan: 'Cyaan',
+        Blue: 'Blauw',
+        Magenta: 'Magenta',
+        Red: 'Rood',
+        Black: 'Zwart'
+    },
+    edgeStyleLabels: {
+        none: 'Geen',
+        dropshadow: 'Slagschaduw',
+        raised: 'Verhoogd',
+        depressed: 'Verlaagd',
+        uniform: 'Uniform'
+    },
+    automaticQualityLabel: 'Automatisch',
+    unknownQualityLabel: 'Onbekend',
+    highQualityLabel: 'Hoge kwaliteit',
+    lowQualityLabel: 'Lage kwaliteit',
+    errorHeading: 'Er is een fout opgetreden',
+    openBadNetworkModeMenuAria: 'menu voor slecht netwerk openen',
+    formatRemainingDuration: (duration) => `${duration} resterend`
+});