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

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 { VideoPlayer, VideoSkin, Video } from '@videojs/react/video';
+
+<VideoPlayer>
+  <I18nProvider locale="es" translations={{ buttons: { play: 'Comenzar' } }}>
+    <VideoSkin>
+      <Video src="..." playsInline />
+    </VideoSkin>
+  </I18nProvider>
+</VideoPlayer>
+```
+
+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 { VideoPlayer, VideoSkin, Video } from '@videojs/react/video';
+
+export function App() {
+  return (
+    <VideoPlayer>
+      <I18nProvider locale="es">
+        <VideoSkin>
+          <Video src="..." playsInline />
+        </VideoSkin>
+      </I18nProvider>
+    </VideoPlayer>
+  );
+}
+```
+
+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 { VideoPlayer, 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 (
+    <VideoPlayer>
+      <I18nProvider locale={locale} translations={translations}>
+        <VideoSkin>
+          <Video src="..." playsInline />
+        </VideoSkin>
+      </I18nProvider>
+    </VideoPlayer>
+  );
+}
+```
+
+`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 { VideoPlayer, 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>
+      <VideoPlayer>
+        <I18nProvider locale={locale}>
+          <VideoSkin>
+            <Video src="..." playsInline />
+          </VideoSkin>
+        </I18nProvider>
+      </VideoPlayer>
+    </>
+  );
+}
+```
+
+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

@@ -77,13 +77,8 @@ Add it to your components folder in a new file.
 ./components/player/index.tsx
 
 ```
-'use client';
-
 import '@videojs/react/video/skin.css';
-import { createPlayer, videoFeatures } from '@videojs/react';
-import { VideoSkin, Video } from '@videojs/react/video';
-
-const Player = createPlayer({ features: videoFeatures });
+import { VideoPlayer, VideoSkin, Video } from '@videojs/react/video';
 
 interface MyPlayerProps {
   src: string;
@@ -91,11 +86,11 @@ interface MyPlayerProps {
 
 export const MyPlayer = ({ src }: MyPlayerProps) => {
   return (
-    <Player.Provider>
+    <VideoPlayer>
       <VideoSkin>
         <Video src={src} playsInline />
       </VideoSkin>
-    </Player.Provider>
+    </VideoPlayer>
   );
 };
 ```
@@ -126,33 +121,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 +131,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.