mirror of
https://github.com/zoriya/v10.git
synced 2026-08-16 02:45:09 +00:00
docs: update i18n docs
This commit is contained in:
Sam Potts
@@ -7,9 +7,11 @@ import FrameworkCase from '@/components/docs/FrameworkCase.astro';
|
||||
import Aside from '@/components/Aside.astro';
|
||||
import DocsLink from '@/components/docs/DocsLink.astro';
|
||||
|
||||
Video.js translates control labels, ARIA text, tooltips, and error copy through a single **global registry**. Components ask for strings by **opaque key** (`play`, `pause`, `seekForward`) — not by English text — so locale files stay stable when copy changes.
|
||||
Video.js translates control labels, ARIA text, tooltips, and error copy through a single **global registry**. Components ask for strings by **opaque key** (`play`, `pause`, `seekForward`), not by English text, so locale files stay stable when copy changes.
|
||||
|
||||
```html title="html"
|
||||
<FrameworkCase frameworks={["html"]}>
|
||||
|
||||
```html
|
||||
<html lang="es">
|
||||
<video-player>
|
||||
<video-skin>
|
||||
@@ -19,7 +21,11 @@ Video.js translates control labels, ARIA text, tooltips, and error copy through
|
||||
</html>
|
||||
```
|
||||
|
||||
```tsx title="react"
|
||||
</FrameworkCase>
|
||||
|
||||
<FrameworkCase frameworks={["react"]}>
|
||||
|
||||
```tsx
|
||||
import { Provider, VideoSkin, Video } from '@videojs/react/video';
|
||||
|
||||
// Set `<html lang="es">` on the document (layout, _document, or index.html)
|
||||
@@ -34,19 +40,21 @@ export function App() {
|
||||
}
|
||||
```
|
||||
|
||||
</FrameworkCase>
|
||||
|
||||
Register a locale once (or rely on lazy-loaded built-in packs), set `lang`, and skins pick up translated strings automatically.
|
||||
|
||||
## Opaque keys
|
||||
|
||||
Core controls expose keys, not visible labels. `PlayButtonCore.getLabel()` returns `'play'`; the translator turns that into `'Play'`, `'Reproducir'`, or your override.
|
||||
|
||||
Keys are typed in <DocsLink slug="reference/translation-params">`TranslationParams`</DocsLink> — TypeScript catches missing `{param}` placeholders and wrong argument names at compile time.
|
||||
Keys are typed in <DocsLink slug="reference/translation-params">`TranslationParams`</DocsLink>. TypeScript catches missing `{param}` placeholders and wrong argument names at compile time.
|
||||
|
||||
Parametric strings use `{placeholder}` tokens, for example `seekForward: 'Seek forward {seconds} seconds'` and `timeRemainingPhrase: '{duration} remaining'`.
|
||||
|
||||
## Global registry
|
||||
|
||||
`registerI18n(locale, translations)` merges strings into a process-wide map. English (`en`) is pre-registered when `@videojs/core/i18n` loads.
|
||||
`registerI18n(locale, translations)` merges strings into a process-wide map. English (`en`) is pre-registered when the i18n bundle loads.
|
||||
|
||||
| API | Purpose |
|
||||
| --- | --- |
|
||||
@@ -55,11 +63,11 @@ Parametric strings use `{placeholder}` tokens, for example `seekForward: 'Seek f
|
||||
| <DocsLink slug="reference/has-registered-i18n">`hasRegisteredI18n`</DocsLink> | Check whether a tag is in the registry |
|
||||
| <DocsLink slug="reference/on-i18n-registry-change">`onI18nRegistryChange`</DocsLink> | Subscribe to registry updates |
|
||||
|
||||
Import from `@videojs/html/i18n`, `@videojs/react/i18n`, or `@videojs/core/i18n` depending on your bundle.
|
||||
Import from `@videojs/html/i18n` or `@videojs/react/i18n` depending on your framework.
|
||||
|
||||
## When you need a provider
|
||||
|
||||
**You usually don't** — if the active locale is available and packs are registered (or lazy-loaded), built-in players already wire providers:
|
||||
**You usually don't**. If the active locale is available and packs are registered (or lazy-loaded), built-in players already wire providers:
|
||||
|
||||
<FrameworkCase frameworks={["html"]}>
|
||||
|
||||
@@ -85,15 +93,15 @@ Wrap with an explicit <DocsLink slug="reference/i18n-provider">`I18nProvider`</D
|
||||
|
||||
Providers resolve the active locale in order:
|
||||
|
||||
1. **Explicit** — `lang` on <DocsLink slug="reference/media-i18n-provider">`<media-i18n-provider>`</DocsLink> or `locale` on <DocsLink slug="reference/i18n-provider">`I18nProvider`</DocsLink>
|
||||
2. **Ambient** — nearest ancestor `[lang]` (HTML) or `langRootRef` / `<html lang>` (React)
|
||||
3. **Fallback** — English defaults
|
||||
1. **Explicit**: `lang` on <DocsLink slug="reference/media-i18n-provider">`<media-i18n-provider>`</DocsLink> or `locale` on <DocsLink slug="reference/i18n-provider">`I18nProvider`</DocsLink>
|
||||
2. **Ambient**: nearest ancestor `[lang]` (HTML) or `langRootRef` / `<html lang>` (React)
|
||||
3. **Fallback**: English defaults
|
||||
|
||||
Changing `<html lang>` re-renders wired controls without remounting the player. An explicit `locale` / `lang` on a provider overrides ambient `<html lang>` until you remove or update that override.
|
||||
Changing `<html lang>` re-renders wired controls without remounting the player. An explicit `locale` or `lang` on a provider overrides ambient `<html lang>` until you remove or update that override.
|
||||
|
||||
## BCP 47 fallback
|
||||
|
||||
Lookups walk a **parent chain**, not sibling locales. `es-MX` falls back to `es`, then `en` — not to `es-419`.
|
||||
Lookups walk a **parent chain**, not sibling locales. `es-MX` falls back to `es`, then `en`, not to `es-419`.
|
||||
|
||||
```
|
||||
es-MX → es → en
|
||||
@@ -116,7 +124,7 @@ Later layers win over earlier ones:
|
||||
|
||||
## Built-in locale packs
|
||||
|
||||
Video.js ships ~50 locale files under `@videojs/core/i18n/locales/*`, re-exported from `@videojs/html/i18n/locales/*` and `@videojs/react/i18n/locales/*`. Providers call `loadLocale` automatically when a pack is not already registered.
|
||||
Video.js ships locale files under `@videojs/html/i18n/locales/*` and `@videojs/react/i18n/locales/*`. Providers call `loadLocale` automatically when a pack is not already registered.
|
||||
|
||||
CDN consumers load self-registering modules:
|
||||
|
||||
@@ -128,7 +136,7 @@ CDN consumers load self-registering modules:
|
||||
## Common pitfalls
|
||||
|
||||
```tsx
|
||||
// ❌ Don't — key is the English word; keys are opaque tokens
|
||||
// ❌ Don't: key is the English word; keys are opaque tokens
|
||||
registerI18n('es', { Play: 'Reproducir' });
|
||||
|
||||
// ✅ Do
|
||||
@@ -136,7 +144,7 @@ registerI18n('es', { play: 'Reproducir' });
|
||||
```
|
||||
|
||||
```tsx
|
||||
// ❌ Don't — parametric key without the placeholder
|
||||
// ❌ Don't: parametric key without the placeholder
|
||||
registerI18n('es', { seekForward: 'Adelante 10 segundos' }); // TS error: missing {seconds}
|
||||
|
||||
// ✅ Do
|
||||
@@ -149,10 +157,9 @@ For zero flash-of-English on SSR or locale switches, pass `translations` directl
|
||||
|
||||
## See also
|
||||
|
||||
- <DocsLink slug="reference/locale">`Locale`</DocsLink>, <DocsLink slug="reference/translations">`Translations`</DocsLink>, <DocsLink slug="reference/translator">`Translator`</DocsLink> — core types
|
||||
- <DocsLink slug="reference/locale">`Locale`</DocsLink>, <DocsLink slug="reference/translations">`Translations`</DocsLink>, <DocsLink slug="reference/translator">`Translator`</DocsLink>: I18n types
|
||||
- <DocsLink slug="how-to/i18n-register-locale">Register a custom locale</DocsLink>
|
||||
- <DocsLink slug="how-to/i18n-override-translations">Override individual keys</DocsLink>
|
||||
- <DocsLink slug="how-to/i18n-switch-locale">Switch locale dynamically</DocsLink>
|
||||
- <DocsLink slug="how-to/i18n-ssr">SSR and hydration</DocsLink>
|
||||
- <DocsLink slug="how-to/i18n-add-built-in-locale">Add a built-in locale (contributors)</DocsLink>
|
||||
- <DocsLink slug="concepts/accessibility">Accessibility</DocsLink> — translated ARIA labels
|
||||
- <DocsLink slug="concepts/accessibility">Accessibility</DocsLink>: Translated ARIA labels
|
||||
|
||||
@@ -8,7 +8,7 @@ import DocsLink from '@/components/docs/DocsLink.astro';
|
||||
|
||||
Built-in locales live in `packages/core/src/core/i18n/locales/`. The build generates lazy loaders, CDN chunks, and HTML/React re-exports from that directory.
|
||||
|
||||
This guide is for **contributors** adding or updating shipped packs — app authors should use <DocsLink slug="how-to/i18n-register-locale">Register a custom locale</DocsLink> instead.
|
||||
This guide is for **contributors** adding or updating shipped packs. App authors should use <DocsLink slug="how-to/i18n-register-locale">Register a custom locale</DocsLink> instead.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
@@ -25,7 +25,7 @@ import type { Translations } from '../types';
|
||||
export default {
|
||||
play: '…',
|
||||
pause: '…',
|
||||
// all keys from en.ts — each entry optional but completeness is preferred
|
||||
// all keys from en.ts; completeness is preferred
|
||||
} satisfies Partial<Translations>;
|
||||
```
|
||||
|
||||
@@ -33,10 +33,10 @@ Use **opaque keys** from `en.ts`, not English sentences as keys. Parametric stri
|
||||
|
||||
Copy guidelines:
|
||||
|
||||
- `liveBadge` — sentence case (`Live`); skins uppercase via CSS where needed
|
||||
- `seek` — slider aria label (`Seek`), not legacy "Progress" wording
|
||||
- `timeRemainingPhrase` — `'{duration} remaining'` pattern with `{duration}` placeholder
|
||||
- Button and error strings — short aria-label style, aligned with V10 core label usage
|
||||
- `liveBadge`: sentence case (`Live`); skins uppercase via CSS where needed
|
||||
- `seek`: slider aria label (`Seek`), not legacy "Progress" wording
|
||||
- `timeRemainingPhrase`: `'{duration} remaining'` pattern with `{duration}` placeholder
|
||||
- Button and error strings: short aria-label style, aligned with V10 core label usage
|
||||
|
||||
## 2. Register the tag in built-in metadata
|
||||
|
||||
@@ -76,7 +76,7 @@ pnpm -F @videojs/html build:cdn
|
||||
```
|
||||
|
||||
<Aside type="note">
|
||||
Do not copy strings blindly from Video.js v8 `lang/` JSON — v10 uses different keys and aria-label semantics. Translate from `en.ts` keys and core `getLabel` usage.
|
||||
Do not copy strings blindly from Video.js v8 `lang/` JSON. V10 uses different keys and aria-label semantics. Translate from `en.ts` keys and core `getLabel` usage.
|
||||
</Aside>
|
||||
|
||||
## What's next?
|
||||
|
||||
@@ -6,7 +6,7 @@ description: Patch individual i18n strings without replacing an entire locale pa
|
||||
import FrameworkCase from '@/components/docs/FrameworkCase.astro';
|
||||
import DocsLink from '@/components/docs/DocsLink.astro';
|
||||
|
||||
`registerI18n` **merges** — each call adds or replaces keys for that locale tag without wiping prior registrations. Use this to tweak shipped packs or A/B test copy.
|
||||
`registerI18n` **merges**. Each call adds or replaces keys for that locale tag without wiping prior registrations. Use this to tweak shipped packs or A/B test copy.
|
||||
|
||||
Read <DocsLink slug="concepts/i18n">Internationalization</DocsLink> for merge order and key naming.
|
||||
|
||||
@@ -73,11 +73,11 @@ Keep required placeholders when overriding:
|
||||
// ✅
|
||||
registerI18n('es', { seekForward: 'Adelantar {seconds} segundos' });
|
||||
|
||||
// ❌ TypeScript error — missing {seconds}
|
||||
// ❌ TypeScript error: missing {seconds}
|
||||
registerI18n('es', { seekForward: 'Adelantar' });
|
||||
```
|
||||
|
||||
## What's next?
|
||||
|
||||
- <DocsLink slug="how-to/i18n-switch-locale">Switch locale dynamically</DocsLink>
|
||||
- <DocsLink slug="reference/get-i18n-translations">`getI18nTranslations`</DocsLink> — inspect the merged map
|
||||
- <DocsLink slug="reference/get-i18n-translations">`getI18nTranslations`</DocsLink>: Inspect the merged map
|
||||
|
||||
@@ -38,7 +38,7 @@ registerI18n('es', es);
|
||||
</html>
|
||||
```
|
||||
|
||||
If you skip `registerI18n`, the built-in provider still **lazy-loads** `es` when `lang="es"` — explicit registration avoids the async gap on first paint.
|
||||
If you skip `registerI18n`, the built-in provider still **lazy-loads** `es` when `lang="es"`. Explicit registration avoids the async gap on first paint.
|
||||
|
||||
</FrameworkCase>
|
||||
|
||||
@@ -68,8 +68,10 @@ Preset skins use `Container`, which includes <DocsLink slug="reference/i18n-prov
|
||||
|
||||
## Register your own pack
|
||||
|
||||
<FrameworkCase frameworks={["html"]}>
|
||||
|
||||
```ts title="my-es.ts"
|
||||
import type { Translations } from '@videojs/core/i18n';
|
||||
import type { Translations } from '@videojs/html/i18n';
|
||||
|
||||
const es = {
|
||||
play: 'Reproducir',
|
||||
@@ -81,6 +83,25 @@ const es = {
|
||||
export default es;
|
||||
```
|
||||
|
||||
</FrameworkCase>
|
||||
|
||||
<FrameworkCase frameworks={["react"]}>
|
||||
|
||||
```ts title="my-es.ts"
|
||||
import type { Translations } from '@videojs/react/i18n';
|
||||
|
||||
const es = {
|
||||
play: 'Reproducir',
|
||||
pause: 'Pausa',
|
||||
mute: 'Silenciar',
|
||||
unmute: 'Activar sonido',
|
||||
} satisfies Partial<Translations>;
|
||||
|
||||
export default es;
|
||||
```
|
||||
|
||||
</FrameworkCase>
|
||||
|
||||
```ts
|
||||
import { registerI18n } from '@videojs/html/i18n'; // or @videojs/react/i18n
|
||||
import es from './my-es';
|
||||
@@ -88,7 +109,7 @@ import es from './my-es';
|
||||
registerI18n('es', es);
|
||||
```
|
||||
|
||||
All keys are optional — missing keys fall back through the BCP 47 chain to English.
|
||||
All keys are optional. Missing keys fall back through the BCP 47 chain to English.
|
||||
|
||||
## CDN
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ import FrameworkCase from '@/components/docs/FrameworkCase.astro';
|
||||
import Aside from '@/components/Aside.astro';
|
||||
import DocsLink from '@/components/docs/DocsLink.astro';
|
||||
|
||||
Server-rendered pages should output the correct `lang` **and** supply translations on the first client render. Lazy `loadLocale` runs after hydration — without preloaded copy, controls briefly show English.
|
||||
Server-rendered pages should output the correct `lang` **and** supply translations on the first client render. Lazy `loadLocale` runs after hydration. Without preloaded copy, controls briefly show English.
|
||||
|
||||
Read <DocsLink slug="concepts/i18n">Internationalization</DocsLink> for provider resolution and merge order.
|
||||
|
||||
@@ -46,7 +46,7 @@ export async function Player({ locale }: { locale: string }) {
|
||||
}
|
||||
```
|
||||
|
||||
`translations` on the first render skips the async lazy layer — labels match on server and client.
|
||||
`translations` on the first render skips the async lazy layer. Labels match on server and client.
|
||||
|
||||
</FrameworkCase>
|
||||
|
||||
@@ -61,7 +61,7 @@ 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.
|
||||
The registry is module singleton state. Registration in server entry points carries into the client bundle when shared.
|
||||
|
||||
## next-intl and app routers
|
||||
|
||||
@@ -76,7 +76,7 @@ const { default: translations } = await import(`@videojs/react/i18n/locales/${lo
|
||||
</I18nProvider>
|
||||
```
|
||||
|
||||
Match your app's locale negotiation — Video.js does not replace framework i18n; it consumes the tag you pass.
|
||||
Match your app's locale negotiation. Video.js does not replace framework i18n; it consumes the tag you pass.
|
||||
|
||||
## HTML custom elements
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ Video.js re-resolves translations when the active locale changes. How you trigge
|
||||
|
||||
## Ambient `<html lang>`
|
||||
|
||||
The simplest switch — update the document language and let providers pick it up:
|
||||
The simplest switch updates the document language and lets providers pick it up:
|
||||
|
||||
```ts
|
||||
document.documentElement.lang = 'fr';
|
||||
@@ -90,7 +90,7 @@ Or set `document.documentElement.lang` if the player inherits ambient language.
|
||||
|
||||
## Avoid flash while switching
|
||||
|
||||
Async lazy loads can briefly show English. Preload copy before the active locale changes — three common patterns:
|
||||
Async lazy loads can briefly show English. Preload copy before the active locale changes with one of three common patterns:
|
||||
|
||||
### Pre-register at bootstrap (React and HTML)
|
||||
|
||||
@@ -106,7 +106,7 @@ import fr from '@videojs/react/i18n/locales/fr';
|
||||
registerI18n('es', es);
|
||||
registerI18n('fr', fr);
|
||||
|
||||
// Switching locale is instant — no remount, no lazy-load gap
|
||||
// Switching locale is instant: no remount, no lazy-load gap
|
||||
<I18nProvider locale={userLocale}>
|
||||
<VideoSkin>...</VideoSkin>
|
||||
</I18nProvider>
|
||||
@@ -174,12 +174,12 @@ async function switchTo(next: string) {
|
||||
|
||||
| Approach | Scope | Best for |
|
||||
| --- | --- | --- |
|
||||
| `registerI18n` at bootstrap | Global — all providers | Language picker with a fixed set of locales |
|
||||
| `registerI18n` before switch | Global — all providers | On-demand prefetch before changing `locale` |
|
||||
| `registerI18n` at bootstrap | Global, all providers | Language picker with a fixed set of locales |
|
||||
| `registerI18n` before switch | Global, all providers | On-demand prefetch before changing `locale` |
|
||||
| `I18nProvider translations` | Single provider subtree | Scoped overrides, SSR first paint |
|
||||
|
||||
<Aside type="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.
|
||||
`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.
|
||||
</Aside>
|
||||
|
||||
<Aside type="tip">
|
||||
@@ -193,4 +193,4 @@ Reload or navigate with an updated `locale` query parameter, or load a different
|
||||
## What's next?
|
||||
|
||||
- <DocsLink slug="how-to/i18n-ssr">SSR with locale</DocsLink>
|
||||
- <DocsLink slug="reference/use-locale">`useLocale`</DocsLink> — read the active locale in React
|
||||
- <DocsLink slug="reference/use-locale">`useLocale`</DocsLink>: Read the active locale in React
|
||||
|
||||
@@ -5,18 +5,13 @@ description: Union of shipped BCP 47 locale tags with autocomplete in TypeScript
|
||||
|
||||
import DocsLink from '@/components/docs/DocsLink.astro';
|
||||
|
||||
`BuiltInLocale` narrows <DocsLink slug="reference/locale">`Locale`</DocsLink> to tags with shipped translation packs in `@videojs/core/i18n/locales/*`. TypeScript suggests these tags when you call `registerI18n`, `loadLocale`, or import locale modules.
|
||||
`BuiltInLocale` narrows <DocsLink slug="reference/locale">`Locale`</DocsLink> to tags with shipped translation packs. TypeScript suggests these tags when you call `registerI18n`, `loadLocale`, or import locale modules.
|
||||
|
||||
## Import
|
||||
## App imports
|
||||
|
||||
```ts
|
||||
import type { BuiltInLocale } from '@videojs/core/i18n';
|
||||
```
|
||||
|
||||
Runtime lists are also exported:
|
||||
|
||||
```ts
|
||||
import { BUILT_IN_LOCALES, LOCALE_ALIAS_TAGS, SHIPPED_LOCALE_TAGS } from '@videojs/core/i18n';
|
||||
import es from '@videojs/html/i18n/locales/es';
|
||||
// or @videojs/react/i18n/locales/es
|
||||
```
|
||||
|
||||
## Definition
|
||||
@@ -36,6 +31,7 @@ Providers call `loadLocale(tag)` for tags in `SHIPPED_LOCALE_TAGS` when a pack i
|
||||
## Examples
|
||||
|
||||
```ts
|
||||
import { registerI18n } from '@videojs/react/i18n';
|
||||
import es from '@videojs/react/i18n/locales/es';
|
||||
|
||||
registerI18n('es', es); // 'es' autocompletes as BuiltInLocale
|
||||
|
||||
@@ -6,10 +6,11 @@ description: Build a typed translator from a resolved translation map
|
||||
import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
|
||||
import DocsLink from "@/components/docs/DocsLink.astro";
|
||||
|
||||
`createTranslator` wraps a <DocsLink slug="reference/translations">`Translations`</DocsLink> map and returns a <DocsLink slug="reference/translator">`Translator`</DocsLink>. Providers call this internally after merging registry, lazy, and prop layers — use it directly for custom UI outside built-in mixins.
|
||||
`createTranslator` wraps a <DocsLink slug="reference/translations">`Translations`</DocsLink> map and returns a <DocsLink slug="reference/translator">`Translator`</DocsLink>. Providers call this internally after merging registry, lazy, and prop layers. Use it directly for custom UI outside built-in mixins.
|
||||
|
||||
```ts
|
||||
import { createTranslator, getI18nTranslations } from '@videojs/core/i18n';
|
||||
import { createTranslator, getI18nTranslations } from '@videojs/html/i18n';
|
||||
// or @videojs/react/i18n
|
||||
|
||||
const t = createTranslator(getI18nTranslations('fr'), 'fr');
|
||||
t('play');
|
||||
|
||||
@@ -11,7 +11,8 @@ import DocsLink from "@/components/docs/DocsLink.astro";
|
||||
See <DocsLink slug="concepts/i18n">Internationalization</DocsLink> for merge order and fallback rules.
|
||||
|
||||
```ts
|
||||
import { createTranslator, getI18nTranslations } from '@videojs/core/i18n';
|
||||
import { createTranslator, getI18nTranslations } from '@videojs/html/i18n';
|
||||
// or @videojs/react/i18n
|
||||
|
||||
const t = createTranslator(getI18nTranslations('pt-BR'), 'pt-BR');
|
||||
t('play'); // merged Portuguese string
|
||||
|
||||
@@ -6,7 +6,7 @@ description: Check whether an exact locale tag exists in the global i18n registr
|
||||
import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
|
||||
import DocsLink from "@/components/docs/DocsLink.astro";
|
||||
|
||||
`hasRegisteredI18n` returns whether a normalized locale tag has an explicit registry layer from `registerI18n`. It does **not** indicate whether a lazy built-in pack exists — only registry entries count.
|
||||
`hasRegisteredI18n` returns whether a normalized locale tag has an explicit registry layer from `registerI18n`. It does **not** indicate whether a lazy built-in pack exists. Only registry entries count.
|
||||
|
||||
```ts
|
||||
import { hasRegisteredI18n, registerI18n } from '@videojs/html/i18n';
|
||||
|
||||
@@ -10,8 +10,8 @@ import DocsLink from '@/components/docs/DocsLink.astro';
|
||||
## Import
|
||||
|
||||
```ts
|
||||
import type { Locale } from '@videojs/core/i18n';
|
||||
// or @videojs/html/i18n, @videojs/react/i18n
|
||||
import type { Locale } from '@videojs/html/i18n';
|
||||
// or @videojs/react/i18n
|
||||
```
|
||||
|
||||
## Definition
|
||||
|
||||
@@ -5,7 +5,7 @@ description: Subscribe to global i18n registry mutations
|
||||
|
||||
import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
|
||||
|
||||
`onI18nRegistryChange` registers a callback that runs whenever any locale layer changes — for example after `registerI18n` or browser translation prefetch. Returns an unsubscribe function.
|
||||
`onI18nRegistryChange` registers a callback that runs whenever any locale layer changes, for example after `registerI18n` or browser translation prefetch. Returns an unsubscribe function.
|
||||
|
||||
React `I18nProvider` uses this to invalidate translators when the registry updates.
|
||||
|
||||
|
||||
@@ -6,9 +6,9 @@ description: Register or merge translation strings for a BCP 47 locale tag in th
|
||||
import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
|
||||
import DocsLink from "@/components/docs/DocsLink.astro";
|
||||
|
||||
`registerI18n` merges a partial translation map into the process-wide registry for a locale tag. English defaults are registered when `@videojs/core/i18n` loads; call `registerI18n` for custom locales or to patch shipped packs before the player renders.
|
||||
`registerI18n` merges a partial translation map into the process-wide registry for a locale tag. English defaults are registered by the i18n bundle. Call `registerI18n` for custom locales or to patch shipped packs before the player renders.
|
||||
|
||||
Import from `@videojs/core/i18n`, `@videojs/html/i18n`, or `@videojs/react/i18n`. Keys are opaque camelCase tokens (`play`, `pause`) — see <DocsLink slug="concepts/i18n">Internationalization</DocsLink> and <DocsLink slug="reference/translations">`Translations`</DocsLink>.
|
||||
Import from `@videojs/html/i18n` or `@videojs/react/i18n`. Keys are opaque camelCase tokens (`play`, `pause`). See <DocsLink slug="concepts/i18n">Internationalization</DocsLink> and <DocsLink slug="reference/translations">`Translations`</DocsLink>.
|
||||
|
||||
```ts
|
||||
import { registerI18n } from '@videojs/react/i18n';
|
||||
|
||||
@@ -10,7 +10,8 @@ import DocsLink from '@/components/docs/DocsLink.astro';
|
||||
## Import
|
||||
|
||||
```ts
|
||||
import type { TranslationParams } from '@videojs/core/i18n';
|
||||
import type { TranslationParams } from '@videojs/html/i18n';
|
||||
// or @videojs/react/i18n
|
||||
```
|
||||
|
||||
## Definition
|
||||
@@ -63,4 +64,4 @@ registerI18n('es', {
|
||||
|
||||
- <DocsLink slug="reference/translations">`Translations`</DocsLink>
|
||||
- <DocsLink slug="reference/translator">`Translator`</DocsLink>
|
||||
- <DocsLink slug="concepts/i18n">Internationalization</DocsLink> — opaque keys overview
|
||||
- <DocsLink slug="concepts/i18n">Internationalization</DocsLink>: Opaque keys overview
|
||||
|
||||
@@ -5,12 +5,13 @@ description: Partial map of opaque translation keys to localized strings
|
||||
|
||||
import DocsLink from '@/components/docs/DocsLink.astro';
|
||||
|
||||
`Translations` is the shape for locale packs passed to <DocsLink slug="reference/register-i18n">`registerI18n`</DocsLink>, the React `translations` prop on <DocsLink slug="reference/i18n-provider">`I18nProvider`</DocsLink>, and <DocsLink slug="reference/create-translator">`createTranslator`</DocsLink>. Every entry is optional — missing keys fall back through the BCP 47 chain to English.
|
||||
`Translations` is the shape for locale packs passed to <DocsLink slug="reference/register-i18n">`registerI18n`</DocsLink>, the React `translations` prop on <DocsLink slug="reference/i18n-provider">`I18nProvider`</DocsLink>, and <DocsLink slug="reference/create-translator">`createTranslator`</DocsLink>. Every entry is optional. Missing keys fall back through the BCP 47 chain to English.
|
||||
|
||||
## Import
|
||||
|
||||
```ts
|
||||
import type { Translations } from '@videojs/core/i18n';
|
||||
import type { Translations } from '@videojs/html/i18n';
|
||||
// or @videojs/react/i18n
|
||||
```
|
||||
|
||||
## Definition
|
||||
@@ -29,7 +30,8 @@ Parametric values must include the same `{placeholder}` substrings as English (`
|
||||
## Examples
|
||||
|
||||
```ts
|
||||
import type { Translations } from '@videojs/core/i18n';
|
||||
import type { Translations } from '@videojs/html/i18n';
|
||||
// or @videojs/react/i18n
|
||||
|
||||
const es = {
|
||||
play: 'Reproducir',
|
||||
|
||||
@@ -10,7 +10,8 @@ import DocsLink from '@/components/docs/DocsLink.astro';
|
||||
## Import
|
||||
|
||||
```ts
|
||||
import type { Translator } from '@videojs/core/i18n';
|
||||
import type { Translator } from '@videojs/html/i18n';
|
||||
// or @videojs/react/i18n
|
||||
```
|
||||
|
||||
## Definition
|
||||
@@ -30,7 +31,8 @@ Missing keys in the active map resolve to the key string (`'play'`) so partial l
|
||||
## Create manually
|
||||
|
||||
```ts
|
||||
import { createTranslator, getI18nTranslations } from '@videojs/core/i18n';
|
||||
import { createTranslator, getI18nTranslations } from '@videojs/html/i18n';
|
||||
// or @videojs/react/i18n
|
||||
|
||||
const t = createTranslator(getI18nTranslations('pt-BR'), 'pt-BR');
|
||||
t('pause'); // localized or key fallback
|
||||
@@ -47,7 +49,7 @@ function Label() {
|
||||
}
|
||||
```
|
||||
|
||||
Control components resolve keys from core `getLabel()` through `resolveControlLabel` / `resolveControlAttrs` — you rarely call `t()` directly unless building custom UI.
|
||||
Control components resolve keys from core `getLabel()` through `resolveControlLabel` / `resolveControlAttrs`. You rarely call `t()` directly unless building custom UI.
|
||||
|
||||
## Related
|
||||
|
||||
|
||||
+36
-21
@@ -17,6 +17,11 @@ export const sidebar: Sidebar = [
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
sidebarLabel: 'Contributing',
|
||||
devOnly: true,
|
||||
contents: [{ slug: 'how-to/i18n-add-built-in-locale', sidebarLabel: 'Add a built-in locale' }],
|
||||
},
|
||||
{
|
||||
sidebarLabel: 'Getting started',
|
||||
// May change when we revisit this section's boundary with Concepts (#1105)
|
||||
@@ -53,11 +58,15 @@ export const sidebar: Sidebar = [
|
||||
{ slug: 'how-to/customize-skins' },
|
||||
{ slug: 'how-to/build-your-own-component' },
|
||||
{ slug: 'how-to/self-host-the-player', frameworks: ['html'] },
|
||||
{ slug: 'how-to/i18n-register-locale', sidebarLabel: 'Register a locale' },
|
||||
{ slug: 'how-to/i18n-override-translations', sidebarLabel: 'Override translations' },
|
||||
{ slug: 'how-to/i18n-switch-locale', sidebarLabel: 'Switch locale' },
|
||||
{ slug: 'how-to/i18n-ssr', sidebarLabel: 'SSR with locale' },
|
||||
{ slug: 'how-to/i18n-add-built-in-locale', sidebarLabel: 'Add a built-in locale' },
|
||||
{
|
||||
sidebarLabel: 'Internationalization',
|
||||
contents: [
|
||||
{ slug: 'how-to/i18n-register-locale', sidebarLabel: 'Register a locale' },
|
||||
{ slug: 'how-to/i18n-override-translations', sidebarLabel: 'Override translations' },
|
||||
{ slug: 'how-to/i18n-switch-locale', sidebarLabel: 'Switch locale' },
|
||||
{ slug: 'how-to/i18n-ssr', sidebarLabel: 'SSR with locale' },
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
@@ -161,22 +170,6 @@ export const sidebar: Sidebar = [
|
||||
llmsDescription: 'API reference for feature modules that provide player capabilities and state.',
|
||||
contents: [
|
||||
{ slug: 'reference/create-selector' },
|
||||
{ slug: 'reference/register-i18n', sidebarLabel: 'registerI18n' },
|
||||
{ slug: 'reference/get-i18n-translations', sidebarLabel: 'getI18nTranslations' },
|
||||
{ slug: 'reference/has-registered-i18n', sidebarLabel: 'hasRegisteredI18n' },
|
||||
{ slug: 'reference/on-i18n-registry-change', sidebarLabel: 'onI18nRegistryChange' },
|
||||
{ slug: 'reference/create-translator', sidebarLabel: 'createTranslator' },
|
||||
{
|
||||
sidebarLabel: 'Types',
|
||||
defaultOpen: false,
|
||||
contents: [
|
||||
{ slug: 'reference/built-in-locale', sidebarLabel: 'BuiltInLocale' },
|
||||
{ slug: 'reference/locale', sidebarLabel: 'Locale' },
|
||||
{ slug: 'reference/translation-params', sidebarLabel: 'TranslationParams' },
|
||||
{ slug: 'reference/translations', sidebarLabel: 'Translations' },
|
||||
{ slug: 'reference/translator', sidebarLabel: 'Translator' },
|
||||
],
|
||||
},
|
||||
{ slug: 'reference/feature-buffer' },
|
||||
{ slug: 'reference/feature-controls' },
|
||||
{ slug: 'reference/feature-error' },
|
||||
@@ -196,4 +189,26 @@ export const sidebar: Sidebar = [
|
||||
{ slug: 'reference/feature-volume' },
|
||||
],
|
||||
},
|
||||
{
|
||||
sidebarLabel: 'Internationalization',
|
||||
llmsDescription: 'API reference for locale registration, translation helpers, and i18n types.',
|
||||
contents: [
|
||||
{ slug: 'reference/register-i18n', sidebarLabel: 'registerI18n' },
|
||||
{ slug: 'reference/get-i18n-translations', sidebarLabel: 'getI18nTranslations' },
|
||||
{ slug: 'reference/has-registered-i18n', sidebarLabel: 'hasRegisteredI18n' },
|
||||
{ slug: 'reference/on-i18n-registry-change', sidebarLabel: 'onI18nRegistryChange' },
|
||||
{ slug: 'reference/create-translator', sidebarLabel: 'createTranslator' },
|
||||
{
|
||||
sidebarLabel: 'Types',
|
||||
defaultOpen: false,
|
||||
contents: [
|
||||
{ slug: 'reference/built-in-locale', sidebarLabel: 'BuiltInLocale' },
|
||||
{ slug: 'reference/locale', sidebarLabel: 'Locale' },
|
||||
{ slug: 'reference/translation-params', sidebarLabel: 'TranslationParams' },
|
||||
{ slug: 'reference/translations', sidebarLabel: 'Translations' },
|
||||
{ slug: 'reference/translator', sidebarLabel: 'Translator' },
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
Reference in New Issue
Block a user