feat(packages): add built-in locale packs with v8 parity

Ship 50+ non-English locale modules in core (default export per pack),
with framework entry points at @videojs/html/i18n and @videojs/react/i18n
(locales/* and all). Includes pt-BR/pt-PT and zh-CN/zh-TW splits, pt/zh
v8 aliases, locale completeness tests, dynamic tsdown entries, and
sandbox locale picker wiring.

Closes #1368

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: sampotts

.gitignore

@@ -22,6 +22,13 @@ dist/
 lib/
 out/
 packages/*/types/
+# tsgo/tsc accidental emit beside i18n sources (declarations belong in dist/)
+packages/core/src/core/i18n/**/*.d.ts
+packages/core/src/core/i18n/**/*.d.ts.map
+packages/html/src/i18n/**/*.d.ts
+packages/html/src/i18n/**/*.d.ts.map
+packages/react/src/i18n/**/*.d.ts
+packages/react/src/i18n/**/*.d.ts.map
 *.tsbuildinfo
 .turbo/
 coverage/

apps/sandbox/README.md

@@ -22,7 +22,7 @@ Three directories participate:
 - **`templates/`** — The source of truth for each sandbox. One subdirectory per entry point, each containing its own `index.html` and `main.ts` / `main.tsx`. Checked into git.
 - **`src/`** — Your working copy where you freely edit, experiment, and break things. Fully gitignored (`src/*`).
 
-On `pnpm dev:sandbox`, `scripts/setup.ts` mirrors every file from `templates/` into `src/` that doesn't already exist there. Existing files in `src/` are never overwritten, so your local changes persist across restarts.
+On `pnpm dev:sandbox`, `scripts/setup.ts` mirrors new files from `templates/` into `src/` and overwrites `src/` files that differ from `templates/`. Edits made only in `src/` are replaced on the next dev start — use `sync` to copy them into `templates/` first.
 
 Vite discovers sandbox entries by scanning `src/*` for subdirectories that contain an `index.html` — no manual registration is needed.
 

apps/sandbox/app/shared/i18n/sandbox-locales.ts

@@ -0,0 +1,51 @@
+import { BUILT_IN_LOCALES, registerI18n } from '@videojs/html/i18n';
+import { all } from '@videojs/html/i18n/all';
+
+/** Locales available in the sandbox language picker (includes v8 aliases). */
+export const SANDBOX_LOCALE_TAGS = ['en', ...BUILT_IN_LOCALES, 'pt', 'zh'] as const;
+
+export type SandboxLocaleTag = (typeof SANDBOX_LOCALE_TAGS)[number];
+
+export const DEFAULT_SANDBOX_LOCALE: SandboxLocaleTag = 'en';
+
+type LoadedLocalePackTag = keyof typeof all;
+
+let activeLocale: SandboxLocaleTag | null = null;
+
+/** Registers built-in copy for non-English tags (English uses the default registry layer). */
+export function ensureSandboxLocale(tag: SandboxLocaleTag): void {
+  if (tag === 'en') {
+    activeLocale = 'en';
+    return;
+  }
+
+  if (activeLocale === tag) {
+    return;
+  }
+
+  const translations = all[tag as LoadedLocalePackTag];
+  if (!translations) {
+    throw new Error(`Unknown sandbox locale: ${tag}`);
+  }
+
+  registerI18n(tag, translations);
+  activeLocale = tag;
+}
+
+const LANGUAGE_NAMES = new Intl.DisplayNames('en', { type: 'language' });
+
+/** v8 `np` is not a valid BCP 47 tag (Nepali is `ne`). */
+const LOCALE_LABEL_OVERRIDES: Partial<Record<SandboxLocaleTag, string>> = {
+  np: 'Nepali',
+};
+
+export function sandboxLocaleLabel(tag: SandboxLocaleTag): string {
+  return LOCALE_LABEL_OVERRIDES[tag] ?? LANGUAGE_NAMES.of(tag) ?? tag;
+}
+
+export const SANDBOX_LOCALE_OPTIONS = [...SANDBOX_LOCALE_TAGS]
+  .map((tag) => ({
+    value: tag,
+    label: sandboxLocaleLabel(tag),
+  }))
+  .sort((a, b) => a.label.localeCompare(b.label, 'en'));

apps/sandbox/app/shared/i18n/sandbox-translations.ts

@@ -0,0 +1,11 @@
+import type { SandboxLocaleTag } from '@app/shared/i18n/sandbox-locales';
+import { getInitialLocale, onLocaleChange } from '@app/shared/sandbox-listener';
+import { useEffect, useState } from 'react';
+
+export function useLocale(): SandboxLocaleTag {
+  const [locale, setLocale] = useState(getInitialLocale);
+
+  useEffect(() => onLocaleChange(setLocale), []);
+
+  return locale;
+}

apps/sandbox/app/shared/react/use-locale.ts

@@ -1,4 +1,5 @@
 import { SKINS } from '@app/constants';
+import { DEFAULT_SANDBOX_LOCALE, SANDBOX_LOCALE_TAGS, type SandboxLocaleTag } from '@app/shared/i18n/sandbox-locales';
 import type { Skin } from '@app/types';
 import { DEFAULT_AUDIO_SOURCE, SOURCES, type SourceId } from './sources';
 
@@ -35,6 +36,12 @@ let currentAutoplay = readBoolean('autoplay');
 let currentMuted = readBoolean('muted');
 let currentLoop = readBoolean('loop');
 let currentPreload = readPreload();
+let currentLocale = readLocale();
+
+function readLocale(): SandboxLocaleTag {
+  const value = params.get('locale');
+  return SANDBOX_LOCALE_TAGS.includes(value as SandboxLocaleTag) ? (value as SandboxLocaleTag) : DEFAULT_SANDBOX_LOCALE;
+}
 
 export function getInitialSkin(): Skin {
   return currentSkin;
@@ -155,3 +162,22 @@ export function onPreloadChange(callback: (preload: PreloadValue) => void): () =
     window.removeEventListener('message', handler);
   };
 }
+
+export function getInitialLocale(): SandboxLocaleTag {
+  return currentLocale;
+}
+
+export function onLocaleChange(callback: (locale: SandboxLocaleTag) => void): () => void {
+  const handler = (event: MessageEvent) => {
+    if (event.data?.type !== 'locale-change' || !SANDBOX_LOCALE_TAGS.includes(event.data.locale)) return;
+
+    currentLocale = event.data.locale;
+    callback(currentLocale);
+  };
+
+  window.addEventListener('message', handler);
+
+  return () => {
+    window.removeEventListener('message', handler);
+  };
+}

apps/sandbox/app/shared/sandbox-listener.ts

@@ -1,4 +1,5 @@
 import { PLATFORMS, PRESETS, STYLINGS } from '@app/constants';
+import { DEFAULT_SANDBOX_LOCALE, SANDBOX_LOCALE_TAGS, type SandboxLocaleTag } from '@app/shared/i18n/sandbox-locales';
 import { DEFAULT_PRELOAD, PRELOAD_VALUES, type PreloadValue } from '@app/shared/sandbox-listener';
 import type { SourceId } from '@app/shared/sources';
 import {
@@ -34,6 +35,12 @@ function readParams() {
     muted: params.get('muted') === '1',
     loop: params.get('loop') === '1',
     preload: PRELOAD_VALUES.includes(preload as PreloadValue) ? (preload as PreloadValue) : DEFAULT_PRELOAD,
+    locale: (() => {
+      const value = params.get('locale');
+      return SANDBOX_LOCALE_TAGS.includes(value as SandboxLocaleTag)
+        ? (value as SandboxLocaleTag)
+        : DEFAULT_SANDBOX_LOCALE;
+    })(),
   };
 }
 
@@ -48,7 +55,9 @@ export function App() {
   const [muted, setMuted] = useState(initial.muted);
   const [loop, setLoop] = useState(initial.loop);
   const [preload, setPreload] = useState<PreloadValue>(initial.preload);
+  const [locale, setLocale] = useState<SandboxLocaleTag>(initial.locale);
   const iframeRef = useRef<HTMLIFrameElement>(null);
+  const showLocalePicker = preset === 'video' && platform !== 'cdn';
 
   const pagePath = getPagePath(platform, preset);
 
@@ -64,9 +73,10 @@ export function App() {
       muted: muted ? '1' : '0',
       loop: loop ? '1' : '0',
       preload,
+      locale,
     });
     history.replaceState(null, '', `/?${params}`);
-  }, [platform, styling, preset, skin, source, autoplay, muted, loop, preload]);
+  }, [platform, styling, preset, skin, source, autoplay, muted, loop, preload, locale]);
 
   useEffect(() => {
     iframeRef.current?.contentWindow?.postMessage({ type: 'skin-change', skin }, '*');
@@ -92,6 +102,11 @@ export function App() {
     iframeRef.current?.contentWindow?.postMessage({ type: 'preload-change', preload }, '*');
   }, [preload]);
 
+  useEffect(() => {
+    if (!showLocalePicker) return;
+    iframeRef.current?.contentWindow?.postMessage({ type: 'locale-change', locale }, '*');
+  }, [locale, showLocalePicker]);
+
   // Constrain source to MP4 when switching to audio
   useEffect(() => {
     if (preset === 'audio' && SOURCES[source].type !== 'mp4') {
@@ -146,6 +161,9 @@ export function App() {
         onLoopChange={setLoop}
         preload={preload}
         onPreloadChange={setPreload}
+        locale={locale}
+        onLocaleChange={setLocale}
+        showLocalePicker={showLocalePicker}
         availableSources={availableSources}
         isBackgroundVideo={preset === 'background-video'}
         isSimpleHlsVideo={preset === 'simple-hls-video'}
@@ -168,6 +186,7 @@ export function App() {
         muted={muted}
         loop={loop}
         preload={preload}
+        locale={locale}
       />
     </div>
   );

apps/sandbox/app/shell/app.tsx

@@ -1,4 +1,5 @@
 import type { SKINS } from '@app/constants';
+import { SANDBOX_LOCALE_OPTIONS, type SandboxLocaleTag } from '@app/shared/i18n/sandbox-locales';
 import { PRELOAD_VALUES, type PreloadValue } from '@app/shared/sandbox-listener';
 import type { SourceId } from '@app/shared/sources';
 import type { Platform, Preset, Skin, Styling } from '@app/types';
@@ -23,6 +24,9 @@ type NavbarProps = {
   onLoopChange: (value: boolean) => void;
   preload: PreloadValue;
   onPreloadChange: (value: PreloadValue) => void;
+  locale: SandboxLocaleTag;
+  onLocaleChange: (value: SandboxLocaleTag) => void;
+  showLocalePicker: boolean;
   availableSources: readonly SourceId[];
   isBackgroundVideo: boolean;
   isSimpleHlsVideo: boolean;
@@ -73,6 +77,9 @@ export function Navbar({
   onLoopChange,
   preload,
   onPreloadChange,
+  locale,
+  onLocaleChange,
+  showLocalePicker,
   availableSources,
   isBackgroundVideo,
   isSimpleHlsVideo,
@@ -150,6 +157,9 @@ export function Navbar({
           onLoopChange={onLoopChange}
           preload={preload}
           onPreloadChange={onPreloadChange}
+          locale={locale}
+          onLocaleChange={onLocaleChange}
+          showLocalePicker={showLocalePicker}
         />
         <a
           href="https://github.com/videojs/v10"
@@ -186,6 +196,9 @@ type SettingsMenuProps = {
   onLoopChange: (value: boolean) => void;
   preload: PreloadValue;
   onPreloadChange: (value: PreloadValue) => void;
+  locale: SandboxLocaleTag;
+  onLocaleChange: (value: SandboxLocaleTag) => void;
+  showLocalePicker: boolean;
 };
 
 function SettingsMenu({
@@ -197,6 +210,9 @@ function SettingsMenu({
   onLoopChange,
   preload,
   onPreloadChange,
+  locale,
+  onLocaleChange,
+  showLocalePicker,
 }: SettingsMenuProps) {
   const [open, setOpen] = useState(false);
   const containerRef = useRef<HTMLDivElement>(null);
@@ -205,6 +221,7 @@ function SettingsMenu({
   const mutedId = useId();
   const loopId = useId();
   const preloadId = useId();
+  const localeId = useId();
 
   useEffect(() => {
     if (!open) return;
@@ -261,8 +278,17 @@ function SettingsMenu({
         <div
           id={menuId}
           role="menu"
-          className="absolute right-0 top-full mt-2 z-20 grid grid-cols-[1fr_auto] auto-rows-[1.75rem] items-center gap-x-6 gap-y-1 rounded-md border border-zinc-200 dark:border-zinc-800 bg-white dark:bg-zinc-950 p-3 shadow-md shadow-black/5"
+          className="absolute right-0 top-full mt-2 z-20 grid grid-cols-[1fr_auto] auto-rows-[1.75rem] items-center gap-x-6 gap-y-1 rounded-md border border-zinc-200 dark:border-zinc-800 bg-white dark:bg-zinc-950 p-3 shadow-md shadow-black/5 max-h-[min(24rem,70vh)] overflow-y-auto"
         >
+          {showLocalePicker && (
+            <SelectItem
+              id={localeId}
+              label="Language"
+              value={locale}
+              onChange={(value) => onLocaleChange(value as SandboxLocaleTag)}
+              options={SANDBOX_LOCALE_OPTIONS}
+            />
+          )}
           <CheckboxItem id={autoplayId} label="Autoplay" checked={autoplay} onChange={onAutoplayChange} />
           <CheckboxItem id={mutedId} label="Muted" checked={muted} onChange={onMutedChange} />
           <CheckboxItem id={loopId} label="Loop" checked={loop} onChange={onLoopChange} />

apps/sandbox/app/shell/navbar.tsx

@@ -1,3 +1,4 @@
+import type { SandboxLocaleTag } from '@app/shared/i18n/sandbox-locales';
 import type { PreloadValue } from '@app/shared/sandbox-listener';
 import type { SourceId } from '@app/shared/sources';
 import type { Preset, Skin, Styling } from '@app/types';
@@ -13,10 +14,11 @@ type PreviewProps = {
   muted: boolean;
   loop: boolean;
   preload: PreloadValue;
+  locale: SandboxLocaleTag;
 };
 
 export const Preview = forwardRef<HTMLIFrameElement, PreviewProps>(function Preview(
-  { pagePath, preset, skin, styling, source, autoplay, muted, loop, preload },
+  { pagePath, preset, skin, styling, source, autoplay, muted, loop, preload, locale },
   ref
 ) {
   const buildUrl = (base: string) => {
@@ -29,6 +31,7 @@ export const Preview = forwardRef<HTMLIFrameElement, PreviewProps>(function Prev
       muted: muted ? '1' : '0',
       loop: loop ? '1' : '0',
       preload,
+      locale,
     });
     return `${base}?${params}`;
   };

apps/sandbox/app/shell/preview.tsx

@@ -1,8 +1,13 @@
-import { mirrorTemplatesToSrc, removeGeneratedSrcFiles } from './shared.js';
+import { mirrorTemplatesToSrc, removeGeneratedSrcFiles, syncTemplatesToSrc } from './shared.js';
 
+const synced = await syncTemplatesToSrc();
 const created = await mirrorTemplatesToSrc();
 const removed = await removeGeneratedSrcFiles();
 
+for (const file of synced) {
+  console.log(`Synced ${file}`);
+}
+
 for (const file of created) {
   console.log(`Created ${file}`);
 }