@videojs/react 10.0.0-beta.25 → 10.0.0-beta.26

package/docs/how-to/i18n-override-translations.md

@@ -0,0 +1,114 @@
+# Override translations
+
+Patch individual i18n strings without replacing an entire locale pack
+
+`registerI18n` **merges**. Each call adds or replaces translations for that locale tag without wiping prior registrations. Use this to tweak shipped packs or A/B test copy.
+
+Read [Internationalization](../concepts/i18n.md) for the translation model and merge order, and [Translation keys](../reference/translation-phrases.md) for the supported keys.
+
+## Override after a built-in pack
+
+ts
+
+```
+import { registerI18n } from '@videojs/react/i18n';
+import '@videojs/react/i18n/locales/es/register';
+
+registerI18n('es', { buttons: { play: 'Comenzar' } }); // only `buttons.play` changes
+```
+
+Later registrations win for the same key. The rest of the `es` pack stays intact.
+
+## React provider overrides
+
+Pass `translations` on [`I18nProvider`](../reference/i18n-provider.md) to scope overrides to one subtree. This layer sits **above** registry and lazy packs:
+
+tsx
+
+```
+import { I18nProvider } from '@videojs/react/i18n';
+import { Provider, VideoSkin, Video } from '@videojs/react/video';
+
+<Provider>
+  <I18nProvider locale="es" translations={{ buttons: { play: 'Comenzar' } }}>
+    <VideoSkin>
+      <Video src="..." playsInline />
+    </VideoSkin>
+  </I18nProvider>
+</Provider>
+```
+
+Nested providers inherit the parent locale when you only pass `translations`:
+
+tsx
+
+```
+<I18nProvider locale="de">
+  <I18nProvider translations={{ buttons: { play: 'Override' } }}>
+    {/* locale stays `de`; only `buttons.play` differs */}
+  </I18nProvider>
+</I18nProvider>
+```
+
+## Override component text
+
+Translation overrides change the built-in accessible labels, tooltips, and default visible text that use the same key. Set a component’s text content or `children` when you only need to replace its visible content.
+
+Pass `children` to replace a component’s default visible text:
+
+tsx
+
+```
+import { LiveButton } from '@videojs/react';
+
+<LiveButton>On air</LiveButton>
+```
+
+Authored React children are literal. Use `useTranslator` when custom children also need localization, or use a translation override when the same copy should apply to the component’s built-in text surfaces.
+
+For content that changes with component state, switch `<span>` elements with the component’s state attributes:
+
+tsx
+
+```
+import { PlayButton } from '@videojs/react';
+
+<PlayButton className="play-button">
+  <span className="play-text">Play video</span>
+  <span className="pause-text">Pause video</span>
+  <span className="replay-text">Watch again</span>
+</PlayButton>
+```
+
+css
+
+```
+.play-text,
+.pause-text,
+.replay-text { display: none; }
+
+.play-button[data-paused]:not([data-ended]) .play-text { display: inline; }
+.play-button:not([data-paused]) .pause-text { display: inline; }
+.play-button[data-ended] .replay-text { display: inline; }
+```
+
+The component still derives its accessible name from media state unless you also set its label API. Keep custom visible text consistent with that name.
+
+## Parametric translations
+
+Keep required placeholders when overriding:
+
+ts
+
+```
+// ✅
+registerI18n('es', { seek: { forward: 'Adelantar {seconds} segundos' } });
+
+// ❌ The interpolated value is lost
+registerI18n('es', { seek: { forward: 'Adelantar' } });
+```
+
+## What’s next?
+
+*   [Switch locale dynamically](./i18n-switch-locale.md)
+*   [`getI18nTranslations`](../reference/get-i18n-translations.md): Inspect the merged map

package/docs/how-to/i18n-register-locale.md

@@ -0,0 +1,74 @@
+# 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`](../reference/register-i18n.md) when you have custom strings, need synchronous first paint, or load locales from the CDN.
+
+To opt into another language, mount `I18nProvider`. Pass its `locale` prop to force a tag, or omit it to inherit `lang`.
+
+## Prerequisites
+
+*   A locale tag ([BCP 47](https://www.rfc-editor.org/rfc/rfc5646), 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:
+
+app.tsx
+
+```
+import { I18nProvider } from '@videojs/react/i18n';
+import '@videojs/react/i18n/locales/es/register';
+import { Provider, VideoSkin, Video } from '@videojs/react/video';
+
+export function App() {
+  return (
+    <Provider>
+      <I18nProvider locale="es">
+        <VideoSkin>
+          <Video src="..." playsInline />
+        </VideoSkin>
+      </I18nProvider>
+    </Provider>
+  );
+}
+```
+
+Wrap the player subtree with [`I18nProvider`](../reference/i18n-provider.md). Omit `locale` to inherit `<html lang="es">`.
+
+## Register your own pack
+
+my-es.ts
+
+```
+import type { Translations } from '@videojs/react/i18n';
+
+const es = {
+  buttons: {
+    play: 'Reproducir',
+    pause: 'Pausa',
+    mute: 'Silenciar',
+    unmute: 'Activar sonido',
+  },
+} satisfies Partial<Translations>;
+
+export default es;
+```
+
+ts
+
+```
+import { registerI18n } from '@videojs/react/i18n';
+import es from './my-es';
+
+registerI18n('es', es);
+```
+
+All keys are optional. Missing keys follow the [locale fallback chain](../concepts/i18n.md) through a built-in pack, browser-translated copy in supported Chrome builds, or English.
+
+## What’s next?
+
+*   [Override individual keys](./i18n-override-translations.md)
+*   [Switch locale at runtime](./i18n-switch-locale.md)
+*   [`registerI18n` reference](../reference/register-i18n.md)

package/docs/how-to/i18n-ssr.md

@@ -0,0 +1,104 @@
+# SSR and locale
+
+Render translated player UI on the server without a flash of English
+
+Video.js is English by default. Server-rendered pages that opt into another language should mount the relevant provider, output the correct `lang`, and supply translations on the first client render. Lazy `loadLocale` and browser translation fallback run after hydration, so controls briefly show English without preloaded copy.
+
+Read [Internationalization](../concepts/i18n.md) for provider resolution and merge order.
+
+## Set `<html lang>`
+
+Render the document language on the server:
+
+html
+
+```
+<html lang="es">
+```
+
+React providers use a server snapshot of `undefined` for ambient lang, then read `<html lang>` on hydration. Passing the `locale` prop explicitly avoids any mismatch.
+
+## Preload translations
+
+Import the locale pack on the server (or in a server component) and pass it to [`I18nProvider`](../reference/i18n-provider.md):
+
+tsx
+
+```
+import { I18nProvider } from '@videojs/react/i18n';
+import { Provider, VideoSkin, Video } from '@videojs/react/video';
+
+const loaders = {
+  es: () => import('@videojs/react/i18n/locales/es'),
+  fr: () => import('@videojs/react/i18n/locales/fr'),
+};
+
+export async function Player({ locale }: { locale: string }) {
+  const load = loaders[locale as keyof typeof loaders];
+  if (!load) throw new Error(`Unsupported locale: ${locale}`);
+  const { default: translations } = await load();
+
+  return (
+    <Provider>
+      <I18nProvider locale={locale} translations={translations}>
+        <VideoSkin>
+          <Video src="..." playsInline />
+        </VideoSkin>
+      </I18nProvider>
+    </Provider>
+  );
+}
+```
+
+`translations` on the first render skips the async lazy layer and Chrome-only browser translation fallback. Labels match on server and client.
+
+## Register on the server
+
+For a shipped pack, import its side-effect module in server bootstrap code before rendering players:
+
+ts
+
+```
+import '@videojs/react/i18n/locales/es/register';
+```
+
+For a custom pack, call [`registerI18n`](../reference/register-i18n.md) instead:
+
+ts
+
+```
+import { registerI18n } from '@videojs/react/i18n';
+import es from './locales/es';
+
+registerI18n('es', es);
+```
+
+The registry is module singleton state. Registration in server entry points carries into the client bundle when shared.
+
+## next-intl and app routers
+
+tsx
+
+```
+import { getLocale } from 'next-intl/server';
+
+const locale = await getLocale();
+const loaders = {
+  es: () => import('@videojs/react/i18n/locales/es'),
+  fr: () => import('@videojs/react/i18n/locales/fr'),
+};
+const load = loaders[locale as keyof typeof loaders];
+if (!load) throw new Error(`Unsupported locale: ${locale}`);
+const { default: translations } = await load();
+
+<I18nProvider locale={locale} translations={translations}>
+  ...
+</I18nProvider>
+```
+
+Match your app’s locale negotiation. Video.js does not replace framework i18n; it consumes the tag you pass.
+
+## What’s next?
+
+*   [Switch locale at runtime](./i18n-switch-locale.md)
+*   [Register a custom locale](./i18n-register-locale.md)

package/docs/how-to/i18n-switch-locale.md

@@ -0,0 +1,170 @@
+# Switch locale dynamically
+
+Change the player language at runtime in HTML and React
+
+Video.js starts in English and re-resolves translations when you opt into another active locale.
+
+## Prerequisites
+
+*   A target locale from a shipped lazy-loaded pack, a registered custom pack, or a Chrome browser translation fallback
+
+## Ambient `<html lang>`
+
+The simplest switch updates the document language and lets providers pick it up:
+
+ts
+
+```
+document.documentElement.lang = 'fr';
+```
+
+Note
+
+Ambient switching only applies when `I18nProvider` has no explicit `locale` prop.
+
+An [`I18nProvider`](../reference/i18n-provider.md) without `locale` reads `<html lang>`. Updating it is enough when you are not forcing an explicit locale.
+
+## Explicit provider language
+
+tsx
+
+```
+import { useState } from 'react';
+import { I18nProvider } from '@videojs/react/i18n';
+import { Provider, VideoSkin, Video } from '@videojs/react/video';
+
+function App() {
+  const [locale, setLocale] = useState<'en' | 'es' | 'fr'>('en');
+
+  return (
+    <>
+      <button type="button" onClick={() => setLocale('es')}>
+        Español
+      </button>
+      <Provider>
+        <I18nProvider locale={locale}>
+          <VideoSkin>
+            <Video src="..." playsInline />
+          </VideoSkin>
+        </I18nProvider>
+      </Provider>
+    </>
+  );
+}
+```
+
+Changing `locale` triggers lazy `loadLocale` for built-in packs.
+
+## Avoid flash while switching
+
+Async lazy loads and browser translation fallback can briefly show English. Preload copy before the active locale changes with one of three common patterns:
+
+### Preload at bootstrap
+
+Side-effect locale modules register shipped packs before the provider renders. Preload every language in a fixed picker to avoid the async gap.
+
+tsx
+
+```
+import '@videojs/react/i18n/locales/es/register';
+import '@videojs/react/i18n/locales/fr/register';
+
+// Switching locale is instant: no remount, no lazy-load gap
+<I18nProvider locale={userLocale}>
+  <VideoSkin>...</VideoSkin>
+</I18nProvider>
+```
+
+### Prefetch before switching
+
+When you cannot register every locale up front, import and register immediately before updating `locale`:
+
+tsx
+
+```
+import { registerI18n } from '@videojs/react/i18n';
+
+const loaders = {
+  es: () => import('@videojs/react/i18n/locales/es'),
+  fr: () => import('@videojs/react/i18n/locales/fr'),
+};
+
+async function switchTo(next: keyof typeof loaders) {
+  const { default: translations } = await loaders[next]();
+  registerI18n(next, translations);
+  setLocale(next);
+}
+
+<I18nProvider locale={locale}>
+  ...
+</I18nProvider>
+```
+
+You still pay the import cost once per locale, but later switches to the same tag stay synchronous.
+
+### Scoped overrides with `translations`
+
+Pass `translations` on [`I18nProvider`](../reference/i18n-provider.md) when overrides should apply to one subtree only, or when you want copy colocated with the switch handler:
+
+tsx
+
+```
+const loaders = {
+  es: () => import('@videojs/react/i18n/locales/es'),
+  fr: () => import('@videojs/react/i18n/locales/fr'),
+};
+
+async function switchTo(next: string) {
+  const load = loaders[next as keyof typeof loaders];
+  if (!load) throw new Error(`Unsupported locale: ${next}`);
+  const { default: translations } = await load();
+  setState({ locale: next, translations });
+}
+
+<I18nProvider locale={state.locale} translations={state.translations}>
+  ...
+</I18nProvider>
+```
+
+Approach
+
+Scope
+
+Best for
+
+Side-effect locale imports
+
+Global, all providers
+
+Language picker with a fixed set of shipped locales
+
+`registerI18n` before switch
+
+Global, all providers
+
+On-demand prefetch before changing `locale`
+
+`I18nProvider translations`
+
+Single provider subtree
+
+Scoped overrides, SSR first paint
+
+Note
+
+`registerI18n` merges into the global registry. Repeated calls add or replace keys for the same tag, they do not wipe other locales. Registry updates notify mounted providers via `onI18nRegistryChange`, so late registrations still refresh wired controls.
+
+Tip
+
+For server-rendered first paint, see [SSR and hydration](./i18n-ssr.md).
+
+## Browser translation fallback
+
+If a switched locale has no registered or shipped pack, Video.js can use Chrome’s [Browser Translation API](https://developer.mozilla.org/en-US/docs/Web/API/Translator) when the browser exposes `globalThis.Translator` and already has the target model installed. This is automatic after lazy loading is attempted.
+
+Do not rely on it for instant switching. Preload or register reviewed packs when the language picker should update without a flash of English.
+
+## What’s next?
+
+*   [SSR with locale](./i18n-ssr.md)
+*   [`useLocale`](../reference/use-locale.md): Read the active locale in React

package/docs/how-to/installation.md

@@ -126,33 +126,6 @@ export const HomePage = () => {
 
 <!-- /cli:replace installation -->
 
-## CSP
-
-If your application uses a Content Security Policy, you may need to allow additional sources for player features to work correctly.
-
-### Common requirements
-
-*   `media-src` must allow your media URLs.
-*   `img-src` must allow any poster or thumbnail image URLs.
-*   `connect-src` must allow HLS manifests, playlists, captions, and segment requests when using HLS playback.
-*   `media-src blob:` is required when using the HLS player variants, which use MSE-backed playback.
-*   `worker-src blob:` is required when using the `hls.js` player variants.
-*   `style-src 'unsafe-inline'` is currently required for some player UI and HTML player styling behavior.
-
-### Example
-
-http
-
-```
-Content-Security-Policy:
-  script-src 'self';
-  style-src 'self' 'unsafe-inline';
-  img-src 'self' https: data: blob:;
-  media-src 'self' https: blob:;
-  connect-src 'self' https:;
-  worker-src 'self' blob:;
-```
-
 ## See also
 
 [
@@ -163,6 +136,14 @@ Some skins expose CSS custom properties
 
 ](../concepts/skins.md)
 
+[
+
+Security
+
+Configure Content Security Policy for your player
+
+](../concepts/security.md)
+
 * * *
 
 That’s it! You now have a fully functional Video.js player. Go forth and play.

package/docs/llms.txt

@@ -15,12 +15,15 @@ Installation, project setup, and introductory guides.
 
 Understanding-oriented pages that explain how and why things work. Read these to build a mental model of the library.
 
-- [Google Cast](./concepts/cast.md): How to add Chromecast support to your Video.js player — lazy SDK loading, session lifecycle, and configuration options
 - [Features](./concepts/features.md): The state and actions each feature adds to the player
 - [Skins](./concepts/skins.md): Packaged player designs that include both UI components and their styles.
 - [Presets](./concepts/presets.md): Pre-packaged player configurations that bundle state management, skins, and media elements for specific use cases.
 - [UI components](./concepts/ui-components.md): How Video.js UI components work — one element per component, data attributes for state, and compound composition.
 - [Accessibility](./concepts/accessibility.md): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player
+- [Google Cast](./concepts/cast.md): Cast playback to Chromecast devices with the Google Cast component, and configure the receiver and load request
+- [Mux Data](./concepts/mux-data.md): Monitor playback quality and viewer experience by adding the Mux Data component to a player
+- [Security](./concepts/security.md): How to configure Content Security Policy for your video player
+- [Internationalization](./concepts/i18n.md): How Video.js chooses a language and translates built-in player text
 
 ## How to
 
@@ -28,6 +31,13 @@ Task-oriented guides with step-by-step instructions to achieve a specific outcom
 
 - [Customize skins](./how-to/customize-skins.md): Learn how to customize Video.js v10 skins by copying and modifying them
 - [Build your own UI component](./how-to/build-your-own-component.md): Create custom player controls that read state, dispatch actions, and stay accessible.
+### Internationalization
+
+- [Translation phrases](./reference/translation-phrases.md): Semantic i18n keys, their English defaults, and the player UI that uses them
+- [Register a custom locale](./how-to/i18n-register-locale.md): Register translation packs for HTML, React, and CDN players
+- [Override translations](./how-to/i18n-override-translations.md): Patch individual i18n strings without replacing an entire locale pack
+- [Switch locale dynamically](./how-to/i18n-switch-locale.md): Change the player language at runtime in HTML and React
+- [SSR and locale](./how-to/i18n-ssr.md): Render translated player UI on the server without a flash of English
 
 ## Components
 
@@ -35,18 +45,23 @@ API Reference for UI components for building media player interfaces.
 
 - [Player.Provider](./reference/player-provider.md): The state boundary — creates a store and broadcasts it to all descendants.
 - [Player.Container](./reference/player-container.md): The player's interaction surface — handles layout, fullscreen, media attachment, and user activity detection.
+- [I18nProvider](./reference/i18n-provider.md): React provider that resolves locale and supplies a typed translator to descendants
 - [AirPlayButton](./reference/airplay-button.md): Accessible AirPlay toggle button that opens the WebKit playback target picker and reflects session state
 - [AudioTrackRadioGroup](./reference/audio-track-radio-group.md): A menu radio group for selecting an audio track
 - [BufferingIndicator](./reference/buffering-indicator.md): Loading indicator that displays when the video player is buffering or waiting for data
 - [CaptionsButton](./reference/captions-button.md): Accessible captions toggle button with availability detection and state reflection
+- [CaptionsRadioGroup](./reference/captions-radio-group.md): A menu radio group for selecting caption and subtitle tracks
 - [CastButton](./reference/cast-button.md): Accessible Cast toggle button with state reflection and keyboard support
 - [Controls](./reference/controls.md): Container component for composing and auto-hiding video player controls on user interaction
 - [FullscreenButton](./reference/fullscreen-button.md): Accessible fullscreen toggle button with keyboard support and state reflection
+- [GoogleCast](./reference/google-cast.md): Options for the Google Cast component that configures the receiver and load request
 - [Menu](./reference/menu.md): A composable menu component for settings, option selection, and actions
 - [MuteButton](./reference/mute-button.md): Accessible mute/unmute button with keyboard support and volume state reflection
+- [MuxData](./reference/mux-data.md): Options for the Mux Data component that monitors playback quality
 - [PiPButton](./reference/pip-button.md): Accessible picture-in-picture toggle button with keyboard support and state reflection
 - [PlayButton](./reference/play-button.md): Accessible play/pause button with keyboard support and customizable rendering
 - [PlaybackRateButton](./reference/playback-rate-button.md): A button that cycles through playback speed rates
+- [PlaybackRateRadioGroup](./reference/playback-rate-radio-group.md): A menu radio group for selecting playback speed
 - [Popover](./reference/popover.md): A popover component for displaying contextual content anchored to a trigger
 - [Poster](./reference/poster.md): Poster image component that displays a thumbnail until video playback starts
 - [QualityRadioGroup](./reference/quality-radio-group.md): A menu radio group for selecting video quality
@@ -73,19 +88,31 @@ API Reference for media elements that handle streaming protocols and media playb
 
 ## Hooks & Utilities
 
-API Reference for React hooks and utilities for player integration.
+API reference for hooks and utilities for player integration.
 
 - [createPlayer](./reference/create-player.md): Factory function that creates a player instance with typed store, Provider component, Container, and hooks
+- [createI18n](./reference/create-i18n.md): Factory that creates framework i18n helpers with custom loading options
+- [useTranslator](./reference/use-translator.md): React hook that returns the typed translator for the nearest I18nProvider
+- [useLocale](./reference/use-locale.md): React hook that returns the active BCP 47 locale from the nearest I18nProvider
 - [Player.usePlayer](./reference/use-player.md): Hook to access the player store from within a Player.Provider
 - [Player.useMedia](./reference/use-media.md): Hook to access the media object from within a Player.Provider
 - [useStore](./reference/use-store.md): Hook to access store state and actions with optional selector-based subscriptions
 ### Advanced
 
+- [registerI18n](./reference/register-i18n.md): Register or merge translation strings for a BCP 47 locale tag in the global i18n registry
+- [getI18nTranslations](./reference/get-i18n-translations.md): Read the merged translation map for a locale using BCP 47 parent-chain fallback
+- [hasRegisteredLocale](./reference/has-registered-locale.md): Check whether an exact locale tag exists in the global i18n registry
+- [onI18nRegistryChange](./reference/on-i18n-registry-change.md): Subscribe to global i18n registry mutations
+- [createTranslator](./reference/create-translator.md): Build a typed translator from a resolved translation map
 - [renderElement](./reference/render-element.md): Utility for rendering UI component elements with state-driven props and render prop support
+- [useAudioTrackOptions](./reference/use-audio-track-options.md): Hook to build audio track menu options from the player audio track state
 - [useButton](./reference/use-button.md): Hook for creating accessible button components with keyboard and pointer interaction
+- [useCaptionsOptions](./reference/use-captions-options.md): Hook to build captions menu options from the player text track state
 - [useContainerAttach](./reference/use-container-attach.md): Hook to register a custom container element with the player context
 - [useMediaAttach](./reference/use-media-attach.md): Hook to register a custom media element with the player context
-- [usePlayerContext](./reference/use-player-context.md): Hook to access the full player context including store, media element, and media setter
+- [usePlaybackRateOptions](./reference/use-playback-rate-options.md): Hook to build playback rate menu options from the player playback rate state
+- [usePlayerContext](./reference/use-player-context.md): Hook to access the full player context value
+- [useQualityOptions](./reference/use-quality-options.md): Hook to build video quality menu options from the player rendition state
 - [useSelector](./reference/use-selector.md): Low-level hook for subscribing to derived state with customizable equality checks
 - [useSnapshot](./reference/use-snapshot.md): Hook to subscribe to a State container's current value