Add localization support

.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.

react/src/DefaultUI.tsx

@@ -6,6 +6,7 @@ import { createComponent, type WebComponentProps } from '@lit/react';
 import { usePlayer } from './util';
 import { PlayerContext } from './context';
 import { type Menu, SlotContainer } from './components';
+import { type addLocale, type Locale } from './i18n';
 
 const RawDefaultUI = createComponent({
     tagName: 'theoplayer-default-ui',
@@ -51,6 +52,14 @@ export interface DefaultUIProps extends PropsWithoutRef<Omit<WebComponentProps<D
      *  - {@link menu}
      */
     children?: never;
+    /**
+     * The language of the UI.
+     *
+     * When set, this also updates the {@link Locale} of the UI if one is registered with {@link addLocale}.
+     *
+     * @see {@link HTMLElement.lang}
+     */
+    lang?: string;
     /**
      * Called when the backing player is created.
      *

react/src/UIContainer.tsx

@@ -6,6 +6,7 @@ import { createComponent, type WebComponentProps } from '@lit/react';
 import { usePlayer } from './util';
 import { PlayerContext } from './context';
 import { type ChromecastButton, type ErrorDisplay, type Menu, type PlayButton, SlotContainer, type TimeRange } from './components';
+import { type addLocale, type Locale } from './i18n';
 
 const RawUIContainer = createComponent({
     tagName: 'theoplayer-ui',
@@ -51,6 +52,14 @@ export interface UIContainerProps extends PropsWithoutRef<WebComponentProps<UICo
      * A slot for an error display, to show when the player encounters a fatal error (see {@link ErrorDisplay}).
      */
     error?: ReactNode;
+    /**
+     * The language of the UI.
+     *
+     * When set, this also updates the {@link Locale} of the UI if one is registered with {@link addLocale}.
+     *
+     * @see {@link HTMLElement.lang}
+     */
+    lang?: string;
     /**
      * Use a named slot instead, such as:
      *  - {@link topChrome}

react/src/i18n.ts

@@ -0,0 +1 @@
+export { type Locale, type PartialLocale, type Duration, type KnownColor, type KnownFontFamily, addLocale } from '@theoplayer/web-ui';

react/src/index.ts

@@ -4,4 +4,5 @@ export * from './DefaultUI';
 export * from './THEOliveDefaultUI';
 export * from './components/index';
 export * from './hooks/index';
+export * from './i18n';
 export * from './version';

react/typedoc.config.mjs

@@ -1,3 +1,5 @@
+import webConfig from '../typedoc.config.mjs';
+
 /** @type {import('typedoc').TypeDocOptions} */
 export default {
     extends: ['../typedoc.config.mjs'],
@@ -21,6 +23,7 @@ export default {
         }
     },
     externalSymbolLinkMappings: {
+        ...webConfig.externalSymbolLinkMappings,
         react: {
             '*': 'https://react.dev/reference/react'
         }

src/DefaultUI.ts

@@ -13,6 +13,7 @@ import type { StreamType } from './util/StreamType';
 import { USER_IDLE_CHANGE_EVENT } from './events/UserIdleChangeEvent';
 import { READY_EVENT } from './events/ReadyEvent';
 import { ACCIDENTAL_CLICK_DELAY } from './util/Constants';
+import { closestRecursive } from './util/CommonUtils';
 import { createCustomEvent } from './util/EventUtils';
 
 /**
@@ -94,6 +95,7 @@ export class DefaultUI extends LitElement {
 
     private _configuration: UIPlayerConfiguration = {};
     private _source: SourceDescription | undefined = undefined;
+    private _language: string = '';
     private _userIdleTimeout: number | undefined = undefined;
     private _deviceType: DeviceType = 'desktop';
     private _dvrThreshold: number = DEFAULT_DVR_THRESHOLD;
@@ -183,6 +185,25 @@ export class DefaultUI extends LitElement {
     @property({ reflect: true, type: Boolean, attribute: Attribute.FLUID })
     accessor fluid: boolean = false;
 
+    /**
+     * The language of this element.
+     *
+     * When set, this also updates the {@link Locale} of the UI if one is registered with {@link addLocale}.
+     *
+     * @see {@link HTMLElement.lang}
+     */
+    get lang(): string {
+        return this._uiRef.value?.lang ?? this._language;
+    }
+
+    @property({ reflect: true, type: String, attribute: Attribute.LANG })
+    set lang(value: string | null) {
+        this._language = value ?? '';
+        if (this._uiRef.value) {
+            this._uiRef.value.lang = this._language;
+        }
+    }
+
     /**
      * Whether the player's audio is muted.
      *
@@ -281,6 +302,9 @@ export class DefaultUI extends LitElement {
     connectedCallback(): void {
         super.connectedCallback();
 
+        if (!this.hasAttribute(Attribute.LANG)) {
+            this.lang = closestRecursive<HTMLElement>(this, '[lang]')?.lang ?? '';
+        }
         if (!this.hasAttribute(Attribute.DEVICE_TYPE)) {
             this.deviceType = isMobile() ? 'mobile' : isTv() ? 'tv' : 'desktop';
         }
@@ -337,6 +361,7 @@ export class DefaultUI extends LitElement {
         return html`<theoplayer-ui
             ${ref(this._uiRef)}
             .configuration=${this.configuration}
+            .lang=${this.lang}
             .fluid=${this.fluid}
             .muted=${this.muted}
             .autoplay=${this.autoplay}

src/UIContainer.ts

@@ -7,6 +7,7 @@ import elementCss from './UIContainer.css';
 import {
     arrayFind,
     arrayRemove,
+    closestRecursive,
     containsComposedNode,
     getFocusableChildren,
     getSlottedElements,
@@ -38,6 +39,7 @@ import { isArrowKey, isBackKey, KeyCode } from './util/KeyCode';
 import { READY_EVENT } from './events/ReadyEvent';
 import { addGlobalStyles } from './Global';
 import { ACCIDENTAL_CLICK_DELAY } from './util/Constants';
+import { type addLocale, type Locale } from './i18n';
 
 // Load components used in template
 import './components/GestureReceiver';
@@ -140,6 +142,7 @@ export class UIContainer extends LitElement {
     private _deviceType: DeviceType = 'desktop';
     private _streamType: StreamType = 'vod';
     private _fluid: boolean = false;
+    private _language: string = '';
     private _userIdle: boolean = false;
     private _userIdleTimeout: number | undefined = undefined;
     private _isUserActive: boolean = false;
@@ -244,6 +247,27 @@ export class UIContainer extends LitElement {
         this._updateAspectRatio();
     }
 
+    /**
+     * The language of this element.
+     *
+     * When set, this also updates the {@link Locale} of the UI if one is registered with {@link addLocale}.
+     *
+     * @see {@link HTMLElement.lang}
+     */
+    get lang(): string {
+        return this._language;
+    }
+
+    @property({ reflect: true, type: String, attribute: Attribute.LANG })
+    set lang(value: string | null) {
+        this._language = value ?? '';
+        for (const receiver of this._stateReceivers) {
+            if (receiver[StateReceiverProps].indexOf('lang') >= 0) {
+                receiver.lang = this._language;
+            }
+        }
+    }
+
     /**
      * Whether the player's audio is muted.
      */
@@ -485,6 +509,9 @@ export class UIContainer extends LitElement {
         super.connectedCallback();
         addGlobalStyles();
 
+        if (!this.hasAttribute(Attribute.LANG)) {
+            this.lang = closestRecursive<HTMLElement>(this, '[lang]')?.lang ?? '';
+        }
         if (!this.hasAttribute(Attribute.DEVICE_TYPE)) {
             this.deviceType = isMobile() ? 'mobile' : isTv() ? 'tv' : 'desktop';
         }
@@ -651,6 +678,9 @@ export class UIContainer extends LitElement {
         if (receiverProps.indexOf('player') >= 0) {
             receiver.player = this._player;
         }
+        if (receiverProps.indexOf('lang') >= 0) {
+            receiver.lang = this.lang;
+        }
         if (receiverProps.indexOf('fullscreen') >= 0) {
             receiver.fullscreen = this.fullscreen;
         }

src/components/ActiveQualityDisplay.ts

@@ -3,6 +3,8 @@ import { customElement, property } from 'lit/decorators.js';
 import { stateReceiver } from './StateReceiverMixin';
 import type { VideoQuality } from 'theoplayer/chromeless';
 import { formatQualityLabel } from '../util/TrackUtils';
+import { Attribute } from '../util/Attribute';
+import { getLocale } from '../i18n';
 
 /**
  * A control that displays the name of the active video quality.
@@ -22,21 +24,25 @@ export class ActiveQualityDisplay extends LitElement {
     @property({ reflect: false, attribute: false })
     accessor targetVideoQualities: VideoQuality[] | undefined = undefined;
 
+    @property({ reflect: true, type: String, attribute: Attribute.LANG })
+    accessor lang: string = '';
+
     protected override render(): HTMLTemplateResult {
+        const locale = getLocale(this.lang);
         // If no target quality is selected, or more than one target quality is selected,
         // treat as "automatic" quality selection.
         const hasSingleTargetQuality = this.targetVideoQualities !== undefined && this.targetVideoQualities.length === 1;
         const targetQuality = hasSingleTargetQuality ? this.targetVideoQualities![0] : undefined;
         // Always show the target quality immediately, even if it's not the active quality yet.
         const selectedQuality = targetQuality ?? this.activeVideoQuality;
-        const qualityLabel = formatQualityLabel(selectedQuality);
+        const qualityLabel = formatQualityLabel(locale, selectedQuality);
         let label: string;
         if (hasSingleTargetQuality) {
             // Manual quality selection: "720p" or "Unknown"
-            label = qualityLabel ?? `Unknown`;
+            label = qualityLabel ?? locale.unknownQualityLabel;
         } else {
             // Automatic quality selection: "Automatic" or "Automatic (720p)"
-            label = `Automatic${qualityLabel ? ` (${qualityLabel})` : ''}`;
+            label = `${locale.automaticQualityLabel}${qualityLabel ? ` (${qualityLabel})` : ''}`;
         }
         return html`<span>${label}</span>`;
     }

src/components/AirPlayButton.ts

@@ -1,16 +1,18 @@
-import { customElement } from 'lit/decorators.js';
+import { type PropertyValues } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
 import type { ChromelessPlayer } from 'theoplayer/chromeless';
 import { stateReceiver } from './StateReceiverMixin';
 import { CastButton } from './CastButton';
 import airPlayButtonHtml from './AirPlayButton.html';
 import airPlayButtonCss from './AirPlayButton.css';
+import { getLocale } from '../i18n';
 import { Attribute } from '../util/Attribute';
 
 /**
  * A button to start and stop casting using AirPlay.
  */
 @customElement('theoplayer-airplay-button')
-@stateReceiver(['player'])
+@stateReceiver(['player', 'lang'])
 export class AirPlayButton extends CastButton {
     static styles = [...CastButton.styles, airPlayButtonCss];
 
@@ -30,16 +32,17 @@ export class AirPlayButton extends CastButton {
         this.castApi = player?.cast?.airplay;
     }
 
-    override attributeChangedCallback(attrName: string, oldValue: any, newValue: any) {
-        super.attributeChangedCallback(attrName, oldValue, newValue);
-        if (AirPlayButton.observedAttributes.indexOf(attrName as Attribute) >= 0) {
-            this._updateAriaLabel();
-        }
+    @property({ reflect: true, type: String, attribute: Attribute.LANG })
+    accessor lang: string = '';
+
+    override willUpdate(changedProperties: PropertyValues) {
+        super.willUpdate(changedProperties);
+        this._updateAriaLabel();
     }
 
     private _updateAriaLabel(): void {
-        const label = this.castState === 'connecting' || this.castState === 'connected' ? 'stop playing on AirPlay' : 'start playing on AirPlay';
-        this.setAttribute(Attribute.ARIA_LABEL, label);
+        const locale = getLocale(this.lang);
+        this.ariaLabel = this.castState === 'connecting' || this.castState === 'connected' ? locale.airplayConnectedAria : locale.airplayAria;
     }
 
     protected override render() {

src/components/Button.ts

@@ -113,6 +113,9 @@ export class Button extends LitElement {
         }
     }
 
+    @property({ reflect: true, state: true, type: String, attribute: Attribute.ARIA_LABEL })
+    override accessor ariaLabel: string | null = null;
+
     private _enable(): void {
         this.removeEventListener('click', this._onClick);
         this.removeEventListener('keydown', this._onKeyDown);

src/components/ChromecastButton.ts

@@ -1,18 +1,20 @@
+import { type PropertyValues } from 'lit';
 import type { ChromelessPlayer } from 'theoplayer/chromeless';
 import { stateReceiver } from './StateReceiverMixin';
 import { CastButton } from './CastButton';
 import chromecastButtonHtml from './ChromecastButton.html';
 import chromecastButtonCss from './ChromecastButton.css';
+import { customElement, property } from 'lit/decorators.js';
+import { getLocale } from '../i18n';
 import { Attribute } from '../util/Attribute';
-import { customElement } from 'lit/decorators.js';
 
 let chromecastButtonId = 0;
 
 /**
  * A button to start and stop casting using Chromecast.
  */
 @customElement('theoplayer-chromecast-button')
-@stateReceiver(['player'])
+@stateReceiver(['player', 'lang'])
 export class ChromecastButton extends CastButton {
     static styles = [...CastButton.styles, chromecastButtonCss];
 
@@ -37,17 +39,17 @@ export class ChromecastButton extends CastButton {
         this.castApi = player?.cast?.chromecast;
     }
 
-    override attributeChangedCallback(attrName: string, oldValue: any, newValue: any) {
-        super.attributeChangedCallback(attrName, oldValue, newValue);
-        if (ChromecastButton.observedAttributes.indexOf(attrName as Attribute) >= 0) {
-            this._updateAriaLabel();
-        }
+    @property({ reflect: true, type: String, attribute: Attribute.LANG })
+    accessor lang: string = '';
+
+    override willUpdate(changedProperties: PropertyValues) {
+        super.willUpdate(changedProperties);
+        this._updateAriaLabel();
     }
 
     private _updateAriaLabel(): void {
-        const label =
-            this.castState === 'connecting' || this.castState === 'connected' ? 'stop casting to Chromecast' : 'start casting to Chromecast';
-        this.setAttribute(Attribute.ARIA_LABEL, label);
+        const locale = getLocale(this.lang);
+        this.ariaLabel = this.castState === 'connecting' || this.castState === 'connected' ? locale.chromecastConnectedAria : locale.chromecastAria;
     }
 
     protected override render() {