From cfb20fb1345caca536fa2fd2b8bb1b6e7240218f Mon Sep 17 00:00:00 2001
From: Sam Potts <sam.potts@mux.com>
Date: Wed, 8 Jul 2026 11:56:26 +1000
Subject: [PATCH] fix(i18n): align stack after phrase key rollout

---
 .../src/dom/locale/merge-locale-overlays.ts   |  6 +--
 site/src/content/docs/concepts/i18n.mdx       | 26 +++++------
 .../docs/how-to/i18n-add-built-in-locale.mdx  | 18 ++++----
 .../how-to/i18n-override-translations.mdx     | 26 +++++------
 .../docs/how-to/i18n-register-locale.mdx      | 24 +++++-----
 .../docs/reference/built-in-locale.mdx        |  8 ++--
 .../docs/reference/create-translator.mdx      |  4 +-
 .../docs/reference/get-i18n-translations.mdx  |  2 +-
 .../docs/reference/has-registered-i18n.mdx    | 19 --------
 .../docs/reference/has-registered-locale.mdx  | 19 ++++++++
 .../content/docs/reference/i18n-provider.mdx  |  2 +-
 site/src/content/docs/reference/locale.mdx    |  2 +-
 .../docs/reference/media-i18n-provider.mdx    |  4 +-
 .../src/content/docs/reference/media-text.mdx | 10 ++--
 .../content/docs/reference/register-i18n.mdx  |  6 +--
 .../docs/reference/translation-params.mdx     | 46 +++++++++----------
 .../content/docs/reference/translations.mdx   | 10 ++--
 .../src/content/docs/reference/translator.mdx | 16 +++----
 .../content/docs/reference/use-translator.mdx |  2 +-
 site/src/docs.config.ts                       |  2 +-
 site/src/utils/utilReferenceSlug.ts           |  2 +-
 21 files changed, 126 insertions(+), 128 deletions(-)
 delete mode 100644 site/src/content/docs/reference/has-registered-i18n.mdx
 create mode 100644 site/src/content/docs/reference/has-registered-locale.mdx

diff --git a/packages/utils/src/dom/locale/merge-locale-overlays.ts b/packages/utils/src/dom/locale/merge-locale-overlays.ts
index 9c0bd116..af189389 100644
--- a/packages/utils/src/dom/locale/merge-locale-overlays.ts
+++ b/packages/utils/src/dom/locale/merge-locale-overlays.ts
@@ -1,13 +1,13 @@
 /**
- * Loads overlay layers for each tag in {@link localeLookupChain}, least-specific first, then merges
+ * Loads overlay layers for each resolved locale key, least-specific first, then merges
  * most-specific-last (same semantics as the core i18n registry).
  */
 export async function mergeLocaleOverlays<Overlay extends object>(
   locale: string,
   load: (tag: string) => Promise<Partial<Overlay> | undefined>,
-  localeLookupChain: (locale: string) => string[]
+  findKeys: (locale: string) => string[]
 ): Promise<{ merged: Partial<Overlay>; loadedTags: string[] }> {
-  const chain = localeLookupChain(locale);
+  const chain = findKeys(locale);
   const layers = await Promise.all(chain.map((tag) => load(tag)));
   const loadedTags: string[] = [];
   const merged: Partial<Overlay> = {};
diff --git a/site/src/content/docs/concepts/i18n.mdx b/site/src/content/docs/concepts/i18n.mdx
index b36f3358..ae6dc408 100644
--- a/site/src/content/docs/concepts/i18n.mdx
+++ b/site/src/content/docs/concepts/i18n.mdx
@@ -1,13 +1,13 @@
 ---
 title: Internationalization
-description: How Video.js translates player UI copy with opaque keys, a global registry, and locale providers
+description: How Video.js translates player UI copy with English phrase keys, a global registry, and locale providers
 ---
 
 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 current English phrase (`Play`, `Pause`, `Seek forward {seconds} seconds`), so missing translations stay readable.
 
 <FrameworkCase frameworks={["html"]}>
 
@@ -44,13 +44,13 @@ export function App() {
 
 Register a locale once (or rely on lazy-loaded built-in packs), set `lang`, and skins pick up translated strings automatically.
 
-## Opaque keys
+## Phrase keys
 
-Core controls expose keys, not visible labels. `PlayButtonCore.getLabel()` returns `'play'`; the translator turns that into `'Play'`, `'Reproducir'`, or your override.
+Core controls expose current English phrases. `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.
+Phrase params 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'`.
+Parametric strings use `{placeholder}` tokens, for example `'Seek forward {seconds} seconds'` and `'{duration} remaining'`.
 
 ## Global registry
 
@@ -60,7 +60,7 @@ Parametric strings use `{placeholder}` tokens, for example `seekForward: 'Seek f
 | --- | --- |
 | <DocsLink slug="reference/register-i18n">`registerI18n`</DocsLink> | Add or merge a locale layer |
 | <DocsLink slug="reference/get-i18n-translations">`getI18nTranslations`</DocsLink> | Read the merged map for a locale |
-| <DocsLink slug="reference/has-registered-i18n">`hasRegisteredI18n`</DocsLink> | Check whether a tag is in the registry |
+| <DocsLink slug="reference/has-registered-locale">`hasRegisteredLocale`</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` or `@videojs/react/i18n` depending on your framework.
@@ -108,7 +108,7 @@ es-MX  →  es  →  en
 zh-Hant-HK  →  zh-hant  →  zh  →  en
 ```
 
-`getI18nTranslations`, lazy `loadLocale`, and providers all use the same chain via `localeLookupChain`.
+`getI18nTranslations`, lazy `loadLocale`, and providers all use the same chain via `findLocaleKeys`.
 
 ## Merge priority
 
@@ -136,19 +136,19 @@ CDN consumers load self-registering modules:
 ## Common pitfalls
 
 ```tsx
-// ❌ Don't: key is the English word; keys are opaque tokens
-registerI18n('es', { Play: 'Reproducir' });
+// ❌ Don't: old camelCase keys are ignored
+registerI18n('es', { play: 'Reproducir' });
 
 // ✅ Do
-registerI18n('es', { play: 'Reproducir' });
+registerI18n('es', { Play: 'Reproducir' });
 ```
 
 ```tsx
 // ❌ Don't: parametric key without the placeholder
-registerI18n('es', { seekForward: 'Adelante 10 segundos' }); // TS error: missing {seconds}
+registerI18n('es', { 'Seek forward {seconds} seconds': 'Adelante 10 segundos' }); // TS error: missing {seconds}
 
 // ✅ Do
-registerI18n('es', { seekForward: 'Adelantar {seconds} segundos' });
+registerI18n('es', { 'Seek forward {seconds} seconds': 'Adelantar {seconds} segundos' });
 ```
 
 <Aside type="tip">
diff --git a/site/src/content/docs/how-to/i18n-add-built-in-locale.mdx b/site/src/content/docs/how-to/i18n-add-built-in-locale.mdx
index 983b531c..a75d394c 100644
--- a/site/src/content/docs/how-to/i18n-add-built-in-locale.mdx
+++ b/site/src/content/docs/how-to/i18n-add-built-in-locale.mdx
@@ -13,7 +13,7 @@ This guide is for **contributors** adding or updating shipped packs. App authors
 ### Prerequisites
 
 - Familiarity with <DocsLink slug="concepts/i18n">Internationalization</DocsLink> and <DocsLink slug="reference/translation-params">`TranslationParams`</DocsLink>
-- English defaults in `packages/core/src/core/i18n/locales/en.ts` as the source of keys
+- English defaults in `packages/core/src/core/i18n/locales/en.ts` as the source of phrases
 
 ## 1. Add the locale file
 
@@ -23,24 +23,24 @@ Create `packages/core/src/core/i18n/locales/{tag}.ts` using the BCP 47 tag as th
 import type { Translations } from '../types';
 
 export default {
-  play: '…',
-  pause: '…',
-  // all keys from en.ts; completeness is preferred
+  Play: '…',
+  Pause: '…',
+  // all phrases from en.ts; completeness is preferred
 } satisfies Partial<Translations>;
 ```
 
-Use **opaque keys** from `en.ts`, not English sentences as keys. Parametric strings must include the same `{placeholder}` tokens (TypeScript enforces this via `satisfies Partial<Translations>`).
+Use the current English phrases from `en.ts`. Parametric strings must include the same `{placeholder}` tokens (TypeScript enforces this via `satisfies Partial<Translations>`).
 
 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
+- `Live`: sentence case; skins uppercase via CSS where needed
+- `Seek`: slider aria label, not legacy "Progress" wording
+- `'{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
 
-Add the tag to `BUILT_IN_LOCALES` in `packages/core/src/core/i18n/built-in-locales.ts`. Add alias tags (`pt`, `zh`) to `LOCALE_ALIAS_TAGS` only when intentional.
+Add the tag to `LOCALES` in `packages/core/src/core/i18n/locales.ts`.
 
 ## 3. Regenerate loaders
 
diff --git a/site/src/content/docs/how-to/i18n-override-translations.mdx b/site/src/content/docs/how-to/i18n-override-translations.mdx
index a24c6091..f9fe999d 100644
--- a/site/src/content/docs/how-to/i18n-override-translations.mdx
+++ b/site/src/content/docs/how-to/i18n-override-translations.mdx
@@ -1,14 +1,14 @@
 ---
-title: Override translation keys
+title: Override translations
 description: Patch individual i18n strings without replacing an entire locale pack
 ---
 
 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 phrases 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.
+Read <DocsLink slug="concepts/i18n">Internationalization</DocsLink> for merge order and phrase naming.
 
 ## Override after a built-in pack
 
@@ -17,10 +17,10 @@ import { registerI18n } from '@videojs/html/i18n';
 import es from '@videojs/html/i18n/locales/es';
 
 registerI18n('es', es);
-registerI18n('es', { play: 'Comenzar' }); // only `play` changes
+registerI18n('es', { Play: 'Comenzar' }); // only `Play` changes
 ```
 
-Later registrations win for the same key. The rest of the `es` pack stays intact.
+Later registrations win for the same phrase. The rest of the `es` pack stays intact.
 
 ## React provider overrides
 
@@ -33,7 +33,7 @@ import { I18nProvider } from '@videojs/react/i18n';
 import { Provider, VideoSkin, Video } from '@videojs/react/video';
 
 <Provider>
-  <I18nProvider locale="es" translations={{ play: 'Comenzar' }}>
+  <I18nProvider locale="es" translations={{ Play: 'Comenzar' }}>
     <VideoSkin>
       <Video src="..." playsInline />
     </VideoSkin>
@@ -45,8 +45,8 @@ Nested providers inherit the parent locale when you only pass `translations`:
 
 ```tsx
 <I18nProvider locale="de">
-  <I18nProvider translations={{ play: 'Override' }}>
-    {/* locale stays `de`; only `play` differs */}
+  <I18nProvider translations={{ Play: 'Override' }}>
+    {/* locale stays `de`; only `Play` differs */}
   </I18nProvider>
 </I18nProvider>
 ```
@@ -59,22 +59,22 @@ Use <DocsLink slug="reference/media-text">`<media-text>`</DocsLink> for static c
 
 ```html
 <media-i18n-provider lang="es">
-  <media-text key="play"></media-text>
+  <media-text key="Play"></media-text>
 </media-i18n-provider>
 ```
 
-Override the key in the registry or set `lang` on the provider to a locale where you patched `play`.
+Override the phrase in the registry or set `lang` on the provider to a locale where you patched `Play`.
 
-## Parametric keys
+## Parametric phrases
 
 Keep required placeholders when overriding:
 
 ```ts
 // ✅
-registerI18n('es', { seekForward: 'Adelantar {seconds} segundos' });
+registerI18n('es', { 'Seek forward {seconds} seconds': 'Adelantar {seconds} segundos' });
 
 // ❌ TypeScript error: missing {seconds}
-registerI18n('es', { seekForward: 'Adelantar' });
+registerI18n('es', { 'Seek forward {seconds} seconds': 'Adelantar' });
 ```
 
 ## What's next?
diff --git a/site/src/content/docs/how-to/i18n-register-locale.mdx b/site/src/content/docs/how-to/i18n-register-locale.mdx
index 52bc2834..386274af 100644
--- a/site/src/content/docs/how-to/i18n-register-locale.mdx
+++ b/site/src/content/docs/how-to/i18n-register-locale.mdx
@@ -7,12 +7,12 @@ import FrameworkCase from '@/components/docs/FrameworkCase.astro';
 import Aside from '@/components/Aside.astro';
 import DocsLink from '@/components/docs/DocsLink.astro';
 
-Register strings once with <DocsLink slug="reference/register-i18n">`registerI18n`</DocsLink>, then set `lang` on the page or pass `locale` to a provider. Read <DocsLink slug="concepts/i18n">Internationalization</DocsLink> first if you are new to opaque keys and the registry.
+Register strings once with <DocsLink slug="reference/register-i18n">`registerI18n`</DocsLink>, then set `lang` on the page or pass `locale` to a provider. Read <DocsLink slug="concepts/i18n">Internationalization</DocsLink> first if you are new to phrase keys and the registry.
 
 ### Prerequisites
 
 - A locale tag ([BCP 47](https://www.rfc-editor.org/rfc/rfc5646), e.g. `es`, `pt-BR`)
-- A partial translation map keyed by camelCase tokens (`play`, `pause`, …)
+- A partial translation map keyed by current English phrases (`Play`, `Pause`, …)
 
 ## Use a shipped pack
 
@@ -74,10 +74,10 @@ Preset skins use `Container`, which includes <DocsLink slug="reference/i18n-prov
 import type { Translations } from '@videojs/html/i18n';
 
 const es = {
-  play: 'Reproducir',
-  pause: 'Pausa',
-  mute: 'Silenciar',
-  unmute: 'Activar sonido',
+  Play: 'Reproducir',
+  Pause: 'Pausa',
+  Mute: 'Silenciar',
+  Unmute: 'Activar sonido',
 } satisfies Partial<Translations>;
 
 export default es;
@@ -91,10 +91,10 @@ export default es;
 import type { Translations } from '@videojs/react/i18n';
 
 const es = {
-  play: 'Reproducir',
-  pause: 'Pausa',
-  mute: 'Silenciar',
-  unmute: 'Activar sonido',
+  Play: 'Reproducir',
+  Pause: 'Pausa',
+  Mute: 'Silenciar',
+  Unmute: 'Activar sonido',
 } satisfies Partial<Translations>;
 
 export default es;
@@ -138,8 +138,8 @@ CDN locale files import `registerI18n` from the shared `cdn/i18n.js` bundle so e
 import { registerI18n } from 'https://cdn.jsdelivr.net/npm/@videojs/html/cdn/i18n.js';
 
 registerI18n('es', {
-  play: 'Reproducir',
-  pause: 'Pausa',
+  Play: 'Reproducir',
+  Pause: 'Pausa',
 });
 ```
 
diff --git a/site/src/content/docs/reference/built-in-locale.mdx b/site/src/content/docs/reference/built-in-locale.mdx
index 5386af9c..428e5aa7 100644
--- a/site/src/content/docs/reference/built-in-locale.mdx
+++ b/site/src/content/docs/reference/built-in-locale.mdx
@@ -17,16 +17,14 @@ import es from '@videojs/html/i18n/locales/es';
 ## Definition
 
 ```ts
-type BuiltInLocale =
-  | (typeof BUILT_IN_LOCALES)[number]
-  | (typeof LOCALE_ALIAS_TAGS)[number];
+type BuiltInLocale = (typeof LOCALES)[number];
 ```
 
-`BUILT_IN_LOCALES` lists regional packs (`es`, `pt-BR`, `zh-CN`, …). `LOCALE_ALIAS_TAGS` adds shorthand tags (`pt`, `zh`) that resolve to regional packs through the lookup chain.
+`LOCALES` lists shipped packs (`es`, `pt-BR`, `zh-CN`, …). Bare language tags such as `pt` and `zh` are handled by the normal locale lookup chain when there is a matching registered or loaded layer.
 
 ## Lazy loading
 
-Providers call `loadLocale(tag)` for tags in `SHIPPED_LOCALE_TAGS` when a pack is not already registered. Explicit `registerI18n` or CDN locale modules skip the async gap on first paint.
+Providers call `loadLocale(tag)` for tags in the resolved locale chain when a pack is not already registered. Explicit `registerI18n` or CDN locale modules skip the async gap on first paint.
 
 ## Examples
 
diff --git a/site/src/content/docs/reference/create-translator.mdx b/site/src/content/docs/reference/create-translator.mdx
index 0d529e3b..f073a95d 100644
--- a/site/src/content/docs/reference/create-translator.mdx
+++ b/site/src/content/docs/reference/create-translator.mdx
@@ -13,8 +13,8 @@ import { createTranslator, getI18nTranslations } from '@videojs/html/i18n';
 // or @videojs/react/i18n
 
 const t = createTranslator(getI18nTranslations('fr'), 'fr');
-t('play');
-t('seekForward', { seconds: 5 });
+t('Play');
+t('Seek forward {seconds} seconds', { seconds: 5 });
 ```
 
 <UtilReference util="createTranslator" />
diff --git a/site/src/content/docs/reference/get-i18n-translations.mdx b/site/src/content/docs/reference/get-i18n-translations.mdx
index d4a78feb..28e3f553 100644
--- a/site/src/content/docs/reference/get-i18n-translations.mdx
+++ b/site/src/content/docs/reference/get-i18n-translations.mdx
@@ -15,7 +15,7 @@ import { createTranslator, getI18nTranslations } from '@videojs/html/i18n';
 // or @videojs/react/i18n
 
 const t = createTranslator(getI18nTranslations('pt-BR'), 'pt-BR');
-t('play'); // merged Portuguese string
+t('Play'); // merged Portuguese string
 ```
 
 <UtilReference util="getI18nTranslations" />
diff --git a/site/src/content/docs/reference/has-registered-i18n.mdx b/site/src/content/docs/reference/has-registered-i18n.mdx
deleted file mode 100644
index 28bfbe14..00000000
--- a/site/src/content/docs/reference/has-registered-i18n.mdx
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: hasRegisteredI18n
-description: Check whether an exact locale tag exists in the global i18n registry
----
-
-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.
-
-```ts
-import { hasRegisteredI18n, registerI18n } from '@videojs/html/i18n';
-
-hasRegisteredI18n('fr'); // false until registered
-registerI18n('fr', { play: 'Lecture' });
-hasRegisteredI18n('fr'); // true
-```
-
-<UtilReference util="hasRegisteredI18n" />
diff --git a/site/src/content/docs/reference/has-registered-locale.mdx b/site/src/content/docs/reference/has-registered-locale.mdx
new file mode 100644
index 00000000..ee18fe9d
--- /dev/null
+++ b/site/src/content/docs/reference/has-registered-locale.mdx
@@ -0,0 +1,19 @@
+---
+title: hasRegisteredLocale
+description: Check whether an exact locale tag exists in the global i18n registry
+---
+
+import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
+import DocsLink from "@/components/docs/DocsLink.astro";
+
+`hasRegisteredLocale` 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 { hasRegisteredLocale, registerI18n } from '@videojs/html/i18n';
+
+hasRegisteredLocale('fr'); // false until registered
+registerI18n('fr', { Play: 'Lecture' });
+hasRegisteredLocale('fr'); // true
+```
+
+<UtilReference util="hasRegisteredLocale" />
diff --git a/site/src/content/docs/reference/i18n-provider.mdx b/site/src/content/docs/reference/i18n-provider.mdx
index a6b84242..566e749e 100644
--- a/site/src/content/docs/reference/i18n-provider.mdx
+++ b/site/src/content/docs/reference/i18n-provider.mdx
@@ -16,7 +16,7 @@ Wrap custom controls or force a locale explicitly:
 ```tsx
 import { I18nProvider } from '@videojs/react/i18n';
 
-<I18nProvider locale="de" translations={{ play: 'Abspielen' }}>
+<I18nProvider locale="de" translations={{ Play: 'Abspielen' }}>
   <MyControls />
 </I18nProvider>
 ```
diff --git a/site/src/content/docs/reference/locale.mdx b/site/src/content/docs/reference/locale.mdx
index 0dafda08..96351b86 100644
--- a/site/src/content/docs/reference/locale.mdx
+++ b/site/src/content/docs/reference/locale.mdx
@@ -24,7 +24,7 @@ The `(string & {})` pattern keeps custom tags (`'xx'`, `'en-US'`) type-safe with
 
 ## Resolution
 
-Providers and `getI18nTranslations` normalize tags and walk the parent chain (`es-MX` → `es` → `en`) via `localeLookupChain`. See <DocsLink slug="concepts/i18n">Internationalization</DocsLink> for explicit vs ambient resolution.
+Providers and `getI18nTranslations` normalize tags and walk the parent chain (`es-MX` → `es` → `en`) via `findLocaleKeys`. See <DocsLink slug="concepts/i18n">Internationalization</DocsLink> for explicit vs ambient resolution.
 
 ## Examples
 
diff --git a/site/src/content/docs/reference/media-i18n-provider.mdx b/site/src/content/docs/reference/media-i18n-provider.mdx
index a8699c08..0231adb0 100644
--- a/site/src/content/docs/reference/media-i18n-provider.mdx
+++ b/site/src/content/docs/reference/media-i18n-provider.mdx
@@ -10,7 +10,7 @@ import FrameworkCase from "@/components/docs/FrameworkCase.astro";
 
 `<media-i18n-provider>` applies the i18n provider mixin to a standalone subtree. Built-in `<video-player>` and skins already include this mixin — use the element when rendering **controls outside a player** or when sibling players need different locales.
 
-Register locale strings with <DocsLink slug="reference/register-i18n">`registerI18n`</DocsLink>, then set `lang` on the provider or an ancestor. See <DocsLink slug="concepts/i18n">Internationalization</DocsLink> for opaque keys and fallback behavior.
+Register locale strings with <DocsLink slug="reference/register-i18n">`registerI18n`</DocsLink>, then set `lang` on the provider or an ancestor. See <DocsLink slug="concepts/i18n">Internationalization</DocsLink> for phrase keys and fallback behavior.
 
 ```html
 <script type="module">
@@ -22,7 +22,7 @@ Register locale strings with <DocsLink slug="reference/register-i18n">`registerI
 </script>
 
 <media-i18n-provider lang="es">
-  <media-text key="play"></media-text>
+  <media-text key="Play"></media-text>
 </media-i18n-provider>
 ```
 
diff --git a/site/src/content/docs/reference/media-text.mdx b/site/src/content/docs/reference/media-text.mdx
index 4aa357b9..dd7f64ff 100644
--- a/site/src/content/docs/reference/media-text.mdx
+++ b/site/src/content/docs/reference/media-text.mdx
@@ -1,6 +1,6 @@
 ---
 title: media-text
-description: HTML custom element that renders a translated string by opaque key
+description: HTML custom element that renders a translated string by phrase
 ---
 
 import DocsLink from "@/components/docs/DocsLink.astro";
@@ -8,11 +8,11 @@ import FrameworkCase from "@/components/docs/FrameworkCase.astro";
 
 <FrameworkCase frameworks={["html"]}>
 
-`<media-text>` renders the translated value for a registry key inside a <DocsLink slug="reference/media-i18n-provider">`<media-i18n-provider>`</DocsLink> (or any ancestor with the i18n provider mixin). Use it for standalone labels, tooltips, or demos — skin controls resolve keys internally.
+`<media-text>` renders the translated value for a registry phrase inside a <DocsLink slug="reference/media-i18n-provider">`<media-i18n-provider>`</DocsLink> (or any ancestor with the i18n provider mixin). Use it for standalone labels, tooltips, or demos — skin controls resolve phrases internally.
 
 ```html
 <media-i18n-provider lang="ja">
-  <media-text key="play"></media-text>
+  <media-text key="Play"></media-text>
 </media-i18n-provider>
 ```
 
@@ -20,8 +20,8 @@ import FrameworkCase from "@/components/docs/FrameworkCase.astro";
 
 | Attribute | Description |
 | --- | --- |
-| `key` | Opaque translation key (`play`, `pause`, `timeRemainingPhrase`, …). |
+| `key` | English translation phrase (`Play`, `Pause`, `{duration} remaining`, …). |
 
-Parametric keys are not yet supported on `<media-text>` — use `createTranslator` in script for interpolated strings.
+Parametric phrases are not yet supported on `<media-text>` — use `createTranslator` in script for interpolated strings.
 
 </FrameworkCase>
diff --git a/site/src/content/docs/reference/register-i18n.mdx b/site/src/content/docs/reference/register-i18n.mdx
index fc0e6c9a..acd0a71a 100644
--- a/site/src/content/docs/reference/register-i18n.mdx
+++ b/site/src/content/docs/reference/register-i18n.mdx
@@ -8,14 +8,14 @@ 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 by the i18n bundle. Call `registerI18n` for custom locales or to patch shipped packs before the player renders.
 
-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>.
+Import from `@videojs/html/i18n` or `@videojs/react/i18n`. Keys are the current English phrases (`Play`, `Pause`). See <DocsLink slug="concepts/i18n">Internationalization</DocsLink> and <DocsLink slug="reference/translations">`Translations`</DocsLink>.
 
 ```ts
 import { registerI18n } from '@videojs/react/i18n';
 
 registerI18n('es', {
-  play: 'Reproducir',
-  pause: 'Pausar',
+  Play: 'Reproducir',
+  Pause: 'Pausar',
 });
 ```
 
diff --git a/site/src/content/docs/reference/translation-params.mdx b/site/src/content/docs/reference/translation-params.mdx
index 10029745..a4847b33 100644
--- a/site/src/content/docs/reference/translation-params.mdx
+++ b/site/src/content/docs/reference/translation-params.mdx
@@ -1,11 +1,11 @@
 ---
 title: TranslationParams
-description: Typed contract for translation keys and their placeholder arguments
+description: Typed contract for translation phrases and their placeholder arguments
 ---
 
 import DocsLink from '@/components/docs/DocsLink.astro';
 
-`TranslationParams` maps every opaque translation key to its argument shape. Keys with `never` accept only `t('key')`. Keys with an object accept `t('key', { … })` with typed placeholder names.
+`TranslationParams` maps every current English translation phrase to its argument shape. Phrases with `never` accept only `t('Phrase')`. Phrases with an object accept `t('Phrase {value}', { … })` with typed placeholder names.
 
 ## Import
 
@@ -18,45 +18,45 @@ import type { TranslationParams } from '@videojs/html/i18n';
 
 ```ts
 type TranslationParams = {
-  play: never;
-  pause: never;
-  seekForward: { seconds: number | string };
-  timeRemainingPhrase: { duration: string };
+  Play: never;
+  Pause: never;
+  'Seek forward {seconds} seconds': { seconds: number | string };
+  '{duration} remaining': { duration: string };
   // …
 };
 ```
 
-English defaults and the full key list live in `packages/core/src/core/i18n/locales/en.ts`. The authoritative TypeScript map is `packages/core/src/core/i18n/types.ts`.
+English defaults and the full phrase list live in `packages/core/src/core/i18n/locales/en.ts`. The authoritative TypeScript map is `packages/core/src/core/i18n/types.ts`.
 
-## Parametric keys
+## Parametric phrases
 
-| Key | Placeholders | Example English value |
-| --- | --- | --- |
-| `seekForward` | `{seconds}` | `Seek forward {seconds} seconds` |
-| `seekBackward` | `{seconds}` | `Seek backward {seconds} seconds` |
-| `playbackRateAria` | `{rate}` | `Playback rate {rate}` |
-| `timeSliderValueTextRange` | `{current}`, `{duration}` | `{current} of {duration}` |
-| `timeRemainingPhrase` | `{duration}` | `{duration} remaining` |
-| `volumeSliderValueTextMuted` | `{percent}` | `{percent}, muted` |
-| `indicatorVolumeWithValue` | `{value}` | `Volume {value}` |
+| Phrase | Placeholders |
+| --- | --- |
+| `Seek forward {seconds} seconds` | `{seconds}` |
+| `Seek backward {seconds} seconds` | `{seconds}` |
+| `Playback rate {rate}` | `{rate}` |
+| `{current} of {duration}` | `{current}`, `{duration}` |
+| `{duration} remaining` | `{duration}` |
+| `{percent}, muted` | `{percent}` |
+| `Volume {value}` | `{value}` |
 
-All other keys are plain strings with no parameters.
+All other phrases are plain strings with no parameters.
 
 ## Usage with Translator
 
 ```ts
 const t: Translator = createTranslator(translations, 'es');
 
-t('play');
-t('seekForward', { seconds: 10 });
-t('timeRemainingPhrase', { duration: '1 minute' });
+t('Play');
+t('Seek forward {seconds} seconds', { seconds: 10 });
+t('{duration} remaining', { duration: '1 minute' });
 ```
 
 TypeScript rejects missing placeholders when defining <DocsLink slug="reference/translations">`Translations`</DocsLink> overlays:
 
 ```ts
 registerI18n('es', {
-  seekForward: 'Adelantar', // error: missing {seconds}
+  'Seek forward {seconds} seconds': 'Adelantar', // error: missing {seconds}
 });
 ```
 
@@ -64,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>: Phrase keys overview
diff --git a/site/src/content/docs/reference/translations.mdx b/site/src/content/docs/reference/translations.mdx
index 4285bfea..cb175d1b 100644
--- a/site/src/content/docs/reference/translations.mdx
+++ b/site/src/content/docs/reference/translations.mdx
@@ -1,6 +1,6 @@
 ---
 title: Translations
-description: Partial map of opaque translation keys to localized strings
+description: Partial map of English translation phrases to localized strings
 ---
 
 import DocsLink from '@/components/docs/DocsLink.astro';
@@ -34,16 +34,16 @@ import type { Translations } from '@videojs/html/i18n';
 // or @videojs/react/i18n
 
 const es = {
-  play: 'Reproducir',
-  pause: 'Pausa',
-  seekForward: 'Adelantar {seconds} segundos',
+  Play: 'Reproducir',
+  Pause: 'Pausa',
+  'Seek forward {seconds} seconds': 'Adelantar {seconds} segundos',
 } satisfies Partial<Translations>;
 
 registerI18n('es', es);
 ```
 
 ```tsx
-<I18nProvider locale="de" translations={{ play: 'Abspielen' }} />
+<I18nProvider locale="de" translations={{ Play: 'Abspielen' }} />
 ```
 
 Only supplied keys override lower layers. See <DocsLink slug="concepts/i18n">Internationalization</DocsLink> for merge priority.
diff --git a/site/src/content/docs/reference/translator.mdx b/site/src/content/docs/reference/translator.mdx
index d3be32f4..ec76dff1 100644
--- a/site/src/content/docs/reference/translator.mdx
+++ b/site/src/content/docs/reference/translator.mdx
@@ -1,11 +1,11 @@
 ---
 title: Translator
-description: Typed function that resolves opaque translation keys to localized strings
+description: Typed function that resolves English translation phrases to localized strings
 ---
 
 import DocsLink from '@/components/docs/DocsLink.astro';
 
-`Translator` is the callable returned by <DocsLink slug="reference/create-translator">`createTranslator`</DocsLink> and <DocsLink slug="reference/use-translator">`useTranslator`</DocsLink>. It turns opaque keys from core controls into localized copy and interpolates `{placeholder}` tokens when params are required.
+`Translator` is the callable returned by <DocsLink slug="reference/create-translator">`createTranslator`</DocsLink> and <DocsLink slug="reference/use-translator">`useTranslator`</DocsLink>. It turns current English phrases from core controls into localized copy and interpolates `{placeholder}` tokens when params are required.
 
 ## Import
 
@@ -23,10 +23,10 @@ type Translator = <K extends keyof TranslationParams>(
 ) => string;
 ```
 
-- Plain keys: `t('play')`
-- Parametric keys: `t('seekForward', { seconds: 10 })`
+- Plain phrases: `t('Play')`
+- Parametric phrases: `t('Seek forward {seconds} seconds', { seconds: 10 })`
 
-Missing keys in the active map resolve to the key string (`'play'`) so partial locale packs degrade visibly during development.
+Missing phrases in the active map resolve to the source English (`'Play'`) so partial locale packs stay readable.
 
 ## Create manually
 
@@ -35,7 +35,7 @@ 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
+t('Pause'); // localized or English fallback
 ```
 
 ## React hook
@@ -45,11 +45,11 @@ import { useTranslator } from '@videojs/react/i18n';
 
 function Label() {
   const t = useTranslator();
-  return <span>{t('play')}</span>;
+  return <span>{t('Play')}</span>;
 }
 ```
 
-Control components resolve keys from core `getLabel()` through `resolveControlLabel` / `resolveControlAttrs`. You rarely call `t()` directly unless building custom UI.
+Control components resolve phrases from core `getLabel()` through their framework adapters. You rarely call `t()` directly unless building custom UI.
 
 ## Related
 
diff --git a/site/src/content/docs/reference/use-translator.mdx b/site/src/content/docs/reference/use-translator.mdx
index 6fa9e402..793a225b 100644
--- a/site/src/content/docs/reference/use-translator.mdx
+++ b/site/src/content/docs/reference/use-translator.mdx
@@ -9,7 +9,7 @@ import FrameworkCase from "@/components/docs/FrameworkCase.astro";
 
 <FrameworkCase frameworks={["react"]}>
 
-`useTranslator` returns the translator from the nearest <DocsLink slug="reference/i18n-provider">`I18nProvider`</DocsLink>. Control components pass opaque keys from core `getLabel()` — for example `t('play')` and `t('seekForward', { seconds: 10 })`.
+`useTranslator` returns the translator from the nearest <DocsLink slug="reference/i18n-provider">`I18nProvider`</DocsLink>. Control components pass current English phrases from core `getLabel()` — for example `t('Play')` and `t('Seek forward {seconds} seconds', { seconds: 10 })`.
 
 When no provider is mounted, the hook falls back to English registry strings so standalone demos do not throw.
 
diff --git a/site/src/docs.config.ts b/site/src/docs.config.ts
index 2c819266..7343d296 100644
--- a/site/src/docs.config.ts
+++ b/site/src/docs.config.ts
@@ -195,7 +195,7 @@ export const sidebar: Sidebar = [
     contents: [
       { slug: 'reference/register-i18n', sidebarLabel: 'registerI18n' },
       { slug: 'reference/get-i18n-translations', sidebarLabel: 'getI18nTranslations' },
-      { slug: 'reference/has-registered-i18n', sidebarLabel: 'hasRegisteredI18n' },
+      { slug: 'reference/has-registered-locale', sidebarLabel: 'hasRegisteredLocale' },
       { slug: 'reference/on-i18n-registry-change', sidebarLabel: 'onI18nRegistryChange' },
       { slug: 'reference/create-translator', sidebarLabel: 'createTranslator' },
       {
diff --git a/site/src/utils/utilReferenceSlug.ts b/site/src/utils/utilReferenceSlug.ts
index 7619d472..7054fcaf 100644
--- a/site/src/utils/utilReferenceSlug.ts
+++ b/site/src/utils/utilReferenceSlug.ts
@@ -3,7 +3,7 @@ import { kebabCase } from 'es-toolkit/string';
 const UTIL_SLUG_OVERRIDES: Record<string, string> = {
   registerI18n: 'register-i18n',
   getI18nTranslations: 'get-i18n-translations',
-  hasRegisteredI18n: 'has-registered-i18n',
+  hasRegisteredLocale: 'has-registered-locale',
   onI18nRegistryChange: 'on-i18n-registry-change',
   createI18n: 'create-i18n',
   createTranslator: 'create-translator',