Skip to content

Take control over your live stream video by running it yourself. Streaming + chat out of the box.

Make the web UI load and fill in faster (#4999)

Gabe Kangas28ddca53086f
diff --git a/web/components/chat/ChatUserMessage/emojiMatcher.ts b/web/components/chat/ChatUserMessage/emojiMatcher.ts
index 1a66ddbd42..0e71704dae 100644
--- a/web/components/chat/ChatUserMessage/emojiMatcher.ts
+++ b/web/components/chat/ChatUserMessage/emojiMatcher.ts
@@ -1,6 +1,5 @@
/* eslint-disable class-methods-use-this */
import { ChildrenNode, Matcher, MatchResponse, Node } from 'interweave';
-import rewritePattern from 'regexpu-core';
import React from 'react';
export interface ChatMessageEmojiProps {
@@ -32,16 +31,34 @@ const regexSupportsUnicodeSets = (() => {
return regexp !== null;
})();
-const emojiRegex = (() => {
- const rewriteFlags = {
- unicodeSetsFlag: regexSupportsUnicodeSets ? 'parse' : 'transform',
- };
- const regexFlag = regexSupportsUnicodeSets ? 'v' : 'u';
+// Exported for tests, which need to exercise the fallback branches on a
+// runtime whose native RegExp already supports the `v` flag.
+export const buildEmojiRegex = (supportsUnicodeSets: boolean): RegExp => {
+ if (supportsUnicodeSets) {
+ // Modern browsers (2023+) compile the RGI_Emoji property-of-strings
+ // pattern natively, so we don't need to ship regexpu-core's ~500KB of
+ // unicode tables just to rewrite this one pattern at runtime.
+ const regexpFlags = 'v';
+ return new RegExp(emojiPattern, regexpFlags);
+ }
- const regexPattern = rewritePattern(emojiPattern, 'v', rewriteFlags);
+ try {
+ // Browsers without the RegExp `v` flag: approximate RGI_Emoji with
+ // pictographic ZWJ sequences. Slightly narrower (misses keycaps and
+ // flag sequences) but this matcher is only cosmetic styling.
+ // A regex literal would be a parse-time syntax error on browsers without
+ // unicode property escapes, so the runtime constructor is load-bearing:
+ // it is what lets the catch branch below run at all.
+ // eslint-disable-next-line prefer-regex-literals
+ return new RegExp('\\p{Extended_Pictographic}(?:\\u200D\\p{Extended_Pictographic})*', 'u');
+ } catch {
+ // Ancient browsers without unicode property escapes: never match, so
+ // emoji simply render as plain text.
+ return /$^/;
+ }
+};
- return new RegExp(regexPattern, regexFlag);
-})();
+const emojiRegex = buildEmojiRegex(regexSupportsUnicodeSets);
export class ChatMessageEmojiMatcher extends Matcher {
match(str: string): MatchResponse<{}> | null {
diff --git a/web/components/stores/ClientConfigStore.tsx b/web/components/stores/ClientConfigStore.tsx
index 3f0502df1f..fcb96584f4 100644
--- a/web/components/stores/ClientConfigStore.tsx
+++ b/web/components/stores/ClientConfigStore.tsx
@@ -12,6 +12,8 @@ import appStateModel, {
AppStateEvent,
AppStateOptions,
makeEmptyAppState,
+ ONLINE_STATE,
+ OFFLINE_STATE,
} from './application-state';
import { setLocalStorage, getLocalStorage } from '../../utils/localStorage';
import {
@@ -134,9 +136,17 @@ export const websocketServiceAtom = atom<WebsocketService>({
dangerouslyAllowMutability: true,
});
+// When server-rendered hydration data is available the online/offline state is
+// already known at first render, so skip the "loading" app state entirely and
+// render the player or offline banner immediately instead of a spinner.
+const initialAppState =
+ hasHydratedConfig && hasHydratedStatus
+ ? { ...(initialStatus.online ? ONLINE_STATE : OFFLINE_STATE) }
+ : makeEmptyAppState();
+
export const appStateAtom = atom<AppStateOptions>({
key: 'appState',
- default: makeEmptyAppState(),
+ default: initialAppState,
});
export const isMobileAtom = atom<boolean | undefined>({
diff --git a/web/components/stores/application-state.ts b/web/components/stores/application-state.ts
index d43f143399..a512ffd7f7 100644
--- a/web/components/stores/application-state.ts
+++ b/web/components/stores/application-state.ts
@@ -28,14 +28,14 @@ export function makeEmptyAppState(): AppStateOptions {
};
}
-const OFFLINE_STATE: AppStateOptions = {
+export const OFFLINE_STATE: AppStateOptions = {
chatAvailable: false,
chatLoading: false,
videoAvailable: false,
appLoading: false,
};
-const ONLINE_STATE: AppStateOptions = {
+export const ONLINE_STATE: AppStateOptions = {
chatAvailable: true,
chatLoading: false,
videoAvailable: true,
diff --git a/web/components/ui/Content/Content.tsx b/web/components/ui/Content/Content.tsx
index 8b11d1c3ee..5e95b17eb0 100644
--- a/web/components/ui/Content/Content.tsx
+++ b/web/components/ui/Content/Content.tsx
@@ -37,7 +37,6 @@ import { ExternalAction } from '../../../interfaces/external-action';
import { Modal } from '../Modal/Modal';
import { DesktopContent } from './DesktopContent';
import { MobileContent } from './MobileContent';
-import { ChatModal } from '../../modals/ChatModal/ChatModal';
import { Footer } from '../Footer/Footer';
import { useFederatedServers } from '../../../hooks/useFederatedServers';
@@ -76,6 +75,13 @@ const OwncastPlayer = dynamic(
},
);
+const ChatModal = dynamic(
+ () => import('../../modals/ChatModal/ChatModal').then(mod => mod.ChatModal),
+ {
+ ssr: false,
+ },
+);
+
const ExternalModal = ({ externalActionToDisplay, setExternalActionToDisplay }) => {
const { title, description, url, html } = externalActionToDisplay;
return (
diff --git a/web/i18n/index.js b/web/i18n/index.js
index 0b20d911cf..9691a67846 100644
--- a/web/i18n/index.js
+++ b/web/i18n/index.js
@@ -1,59 +1,20 @@
-const ar = require('./ar/translation.json');
-const bn = require('./bn/translation.json');
-const de = require('./de/translation.json');
-const el = require('./el/translation.json');
+// Only English ships in the main javascript bundle. Every other locale is
+// fetched on demand by utils/localeLoader, which webpack splits into one
+// small chunk per language, patched into `translations` at runtime. This
+// keeps ~500KB of catalogs out of the code that has to download and parse
+// before the page becomes interactive.
const en = require('./en/translation.json');
-const es = require('./es/translation.json');
-const fr = require('./fr/translation.json');
-const ga = require('./ga/translation.json');
-const hi = require('./hi/translation.json');
-const hr = require('./hr/translation.json');
-const it = require('./it/translation.json');
-const ja = require('./ja/translation.json');
-const ko = require('./ko/translation.json');
-const ms = require('./ms/translation.json');
-const nl = require('./nl/translation.json');
-const no = require('./no/translation.json');
-const pa = require('./pa/translation.json');
-const pl = require('./pl/translation.json');
-const pt = require('./pt/translation.json');
-const ru = require('./ru/translation.json');
-const sv = require('./sv/translation.json');
-const th = require('./th/translation.json');
-const vi = require('./vi/translation.json');
-const zh = require('./zh/translation.json');
const i18n = {
translations: {
- ar,
- bn,
- de,
- el,
en,
- es,
- fr,
- ga,
- hi,
- hr,
- it,
- ja,
- ko,
- ms,
- nl,
- no,
- pa,
- pl,
- pt,
- ru,
- sv,
- th,
- vi,
- zh,
},
defaultLang: 'en',
+ // Browser-language detection is handled by utils/localeLoader so the
+ // catalog can be fetched first. The library's own detection only ever
+ // sees English until that catalog arrives.
useBrowserDefault: true,
- // optional property, will default to "query" if not set
- languageDataStore: 'query' || 'localStorage',
+ languageDataStore: 'query',
};
module.exports = i18n;
diff --git a/web/package-lock.json b/web/package-lock.json
index f545dbd7c8..87d7e15405 100644
--- a/web/package-lock.json
+++ b/web/package-lock.json
@@ -53,7 +53,6 @@
"react-markdown": "10.1.0",
"react-virtuoso": "4.18.10",
"recoil": "0.7.7",
- "regexpu-core": "^5.3.2",
"sanitize-html": "^2.11.0",
"semver": "^7.6.3",
"sharp": "0.34.5",
@@ -2367,12 +2366,6 @@
"source-map": "^0.6.0"
}
},
- "node_modules/@babel/regjsgen": {
- "version": "0.8.0",
- "resolved": "https://registry.npmjs.org/@babel/regjsgen/-/regjsgen-0.8.0.tgz",
- "integrity": "sha512-x/rqGMdzj+fWZvCOYForTghzbtqPDZ5gPwaoNGHdgDfF2QA/XZbCBp4Moo5scrkAMPhB7z26XM/AaHuIJdgauA==",
- "license": "MIT"
- },
"node_modules/@babel/runtime": {
"version": "7.29.7",
"resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.7.tgz",
@@ -7042,6 +7035,7 @@
"version": "2.5.6",
"resolved": "https://registry.npmjs.org/@parcel/watcher/-/watcher-2.5.6.tgz",
"integrity": "sha512-tmmZ3lQxAe/k/+rNnXQRawJ4NjxO2hqiOLTHvWchtGZULp4RyFeh6aU4XdOYBFe2KE1oShQTv4AblOs2iOrNnQ==",
+ "dev": true,
"hasInstallScript": true,
"license": "MIT",
"optional": true,
@@ -7081,6 +7075,7 @@
"cpu": [
"arm64"
],
+ "dev": true,
"license": "MIT",
"optional": true,
"os": [
@@ -7101,6 +7096,7 @@
"cpu": [
"arm64"
],
+ "dev": true,
"license": "MIT",
"optional": true,
"os": [
@@ -7121,6 +7117,7 @@
"cpu": [
"x64"
],
+ "dev": true,
"license": "MIT",
"optional": true,
"os": [
@@ -7141,6 +7138,7 @@
"cpu": [
"x64"
],
+ "dev": true,
"license": "MIT",
"optional": true,
"os": [
@@ -7161,6 +7159,7 @@
"cpu": [
"arm"
],
+ "dev": true,
"license": "MIT",
"optional": true,
"os": [
@@ -7181,6 +7180,7 @@
"cpu": [
"arm"
],
+ "dev": true,
"license": "MIT",
"optional": true,
"os": [
@@ -7201,6 +7201,7 @@
"cpu": [
"arm64"
],
+ "dev": true,
"license": "MIT",
"optional": true,
"os": [
@@ -7221,6 +7222,7 @@
"cpu": [
"arm64"
],
+ "dev": true,
"license": "MIT",
"optional": true,
"os": [
@@ -7241,6 +7243,7 @@
"cpu": [
"x64"
],
+ "dev": true,
"license": "MIT",
"optional": true,
"os": [
@@ -7261,6 +7264,7 @@
"cpu": [
"x64"
],
+ "dev": true,
"license": "MIT",
"optional": true,
"os": [
@@ -7281,6 +7285,7 @@
"cpu": [
"arm64"
],
+ "dev": true,
"license": "MIT",
"optional": true,
"os": [
@@ -7301,6 +7306,7 @@
"cpu": [
"ia32"
],
+ "dev": true,
"license": "MIT",
"optional": true,
"os": [
@@ -7321,6 +7327,7 @@
"cpu": [
"x64"
],
+ "dev": true,
"license": "MIT",
"optional": true,
"os": [
@@ -7338,6 +7345,7 @@
"version": "4.0.4",
"resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
"integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
+ "dev": true,
"license": "MIT",
"optional": true,
"engines": {
@@ -24522,6 +24530,7 @@
"version": "7.1.1",
"resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz",
"integrity": "sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==",
+ "dev": true,
"license": "MIT",
"optional": true
},
@@ -29337,49 +29346,12 @@
"url": "https://github.com/sponsors/ljharb"
}
},
- "node_modules/regexpu-core": {
- "version": "5.3.2",
- "resolved": "https://registry.npmjs.org/regexpu-core/-/regexpu-core-5.3.2.tgz",
- "integrity": "sha512-RAM5FlZz+Lhmo7db9L298p2vHP5ZywrVXmVXpmAD9GuL5MPH6t9ROw1iA/wfHkQ76Qe7AaPF0nGuim96/IrQMQ==",
- "license": "MIT",
- "dependencies": {
- "@babel/regjsgen": "^0.8.0",
- "regenerate": "^1.4.2",
- "regenerate-unicode-properties": "^10.1.0",
- "regjsparser": "^0.9.1",
- "unicode-match-property-ecmascript": "^2.0.0",
- "unicode-match-property-value-ecmascript": "^2.1.0"
- },
- "engines": {
- "node": ">=4"
- }
- },
"node_modules/regjsgen": {
"version": "0.8.0",
"resolved": "https://registry.npmjs.org/regjsgen/-/regjsgen-0.8.0.tgz",
"integrity": "sha512-RvwtGe3d7LvWiDQXeQw8p5asZUmfU1G/l6WbUXeHta7Y2PEIvBTwH6E2EfmYUK8pxcxEdEmaomqyp0vZZ7C+3Q==",
"license": "MIT"
},
- "node_modules/regjsparser": {
- "version": "0.9.1",
- "resolved": "https://registry.npmjs.org/regjsparser/-/regjsparser-0.9.1.tgz",
- "integrity": "sha512-dQUtn90WanSNl+7mQKcXAgZxvUe7Z0SqXlgzv0za4LwiUhyzBC58yQO3liFoUgu8GiJVInAhJjkj1N0EtQ5nkQ==",
- "license": "BSD-2-Clause",
- "dependencies": {
- "jsesc": "~0.5.0"
- },
- "bin": {
- "regjsparser": "bin/parser"
- }
- },
- "node_modules/regjsparser/node_modules/jsesc": {
- "version": "0.5.0",
- "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-0.5.0.tgz",
- "integrity": "sha512-uZz5UnB7u4T9LvwmFqXii7pZSouaRPorGs5who1Ip7VO0wxanFvBL7GkM6dTHlgX+jhBApRetaWpnDabOeTcnA==",
- "bin": {
- "jsesc": "bin/jsesc"
- }
- },
"node_modules/relateurl": {
"version": "0.2.7",
"resolved": "https://registry.npmjs.org/relateurl/-/relateurl-0.2.7.tgz",
diff --git a/web/package.json b/web/package.json
index 784276b111..d86b765f8a 100644
--- a/web/package.json
+++ b/web/package.json
@@ -71,7 +71,6 @@
"react-markdown": "10.1.0",
"react-virtuoso": "4.18.10",
"recoil": "0.7.7",
- "regexpu-core": "^5.3.2",
"sanitize-html": "^2.11.0",
"semver": "^7.6.3",
"sharp": "0.34.5",
@@ -155,4 +154,4 @@
"public/"
]
}
-}
\ No newline at end of file
+}
diff --git a/web/pages/_app.tsx b/web/pages/_app.tsx
index f53e030d35..83edee4ad4 100644
--- a/web/pages/_app.tsx
+++ b/web/pages/_app.tsx
@@ -11,9 +11,12 @@ import '../styles/ant-overrides.scss';
import '../components/video/VideoJS/VideoJS.scss';
import { AppProps } from 'next/app';
-import { ReactElement, ReactNode } from 'react';
+import { ReactElement, ReactNode, useEffect } from 'react';
import { NextPage } from 'next';
import { RecoilRoot } from 'recoil';
+import { useRouter } from 'next/router';
+import { useSelectedLanguage } from 'next-export-i18n';
+import { loadViewerLocale, shouldCleanUrlAfterFlip } from '../utils/localeLoader';
export type NextPageWithLayout<P = {}, IP = P> = NextPage<P, IP> & {
getLayout?: (page: ReactElement) => ReactNode;
@@ -23,12 +26,44 @@ type AppPropsWithLayout = AppProps & {
Component: NextPageWithLayout;
};
+// Removes the ?lang= parameter the locale loader adds to trigger a language
+// switch, once that switch has verifiably landed (this component's own
+// selected language changed to it). Copied URLs stay clean instead of
+// pinning the viewer's language onto whoever opens them. Explicit viewer-set
+// ?lang= values are never registered for cleanup, so they stay put.
+function LocaleSync() {
+ const router = useRouter();
+ const { lang } = useSelectedLanguage();
+ useEffect(() => {
+ if (shouldCleanUrlAfterFlip(lang)) {
+ const rest = { ...router.query };
+ delete rest.lang;
+ router.replace({ query: rest }, undefined, { shallow: true, scroll: false });
+ }
+ }, [lang]);
+ return null;
+}
+
export default function App({ Component, pageProps }: AppPropsWithLayout) {
const layout = Component.getLayout ?? (page => page);
- return layout(
- <RecoilRoot>
- <Component {...pageProps} />
- </RecoilRoot>,
+ // Fetch the viewer's locale catalog (one small chunk) once the router can
+ // report ?lang=. Everything renders in English until it lands.
+ const router = useRouter();
+ useEffect(() => {
+ if (router.isReady) {
+ loadViewerLocale(router);
+ }
+ }, [router.isReady]);
+
+ return (
+ <>
+ <LocaleSync />
+ {layout(
+ <RecoilRoot>
+ <Component {...pageProps} />
+ </RecoilRoot>,
+ )}
+ </>
);
}
diff --git a/web/tests/emojiMatcher.test.ts b/web/tests/emojiMatcher.test.ts
new file mode 100644
index 0000000000..8e75f586df
--- /dev/null
+++ b/web/tests/emojiMatcher.test.ts
@@ -0,0 +1,90 @@
+import {
+ buildEmojiRegex,
+ ChatMessageEmojiMatcher,
+} from '../components/chat/ChatUserMessage/emojiMatcher';
+
+// Built from explicit escapes so the ZWJ / variation selectors are visible in
+// the source instead of hiding inside a literal.
+const ZWJ_FAMILY = '\u{1F469}\u200D\u{1F469}\u200D\u{1F466}'; // πŸ‘©β€πŸ‘©β€πŸ‘¦
+const KEYCAP_ONE = '1\uFE0F\u20E3'; // 1️⃣
+const PARTY = '\u{1F389}'; // πŸŽ‰
+
+describe('buildEmojiRegex', () => {
+ test('returns a usable RegExp for both tiers', () => {
+ expect(buildEmojiRegex(true)).toBeInstanceOf(RegExp);
+ expect(buildEmojiRegex(false)).toBeInstanceOf(RegExp);
+ });
+
+ describe('native RGI_Emoji tier (supportsUnicodeSets: true)', () => {
+ const regex = buildEmojiRegex(true);
+
+ test('matches a single emoji', () => {
+ expect(PARTY.match(regex)?.[0]).toBe(PARTY);
+ });
+
+ test('matches a ZWJ sequence as one match', () => {
+ expect(ZWJ_FAMILY.match(regex)?.[0]).toBe(ZWJ_FAMILY);
+ });
+
+ test('matches a keycap sequence as one match', () => {
+ // RGI_Emoji is a property of strings, so the digit + VS16 + combining
+ // keycap sequence matches as a single unit.
+ expect(KEYCAP_ONE.match(regex)?.[0]).toBe(KEYCAP_ONE);
+ });
+
+ test('does not match plain text or bare digits', () => {
+ expect('hello'.match(regex)).toBeNull();
+ expect('1'.match(regex)).toBeNull();
+ });
+ });
+
+ describe('pictographic fallback tier (supportsUnicodeSets: false)', () => {
+ const regex = buildEmojiRegex(false);
+
+ test('matches pictographic emoji', () => {
+ expect(PARTY.match(regex)?.[0]).toBe(PARTY);
+ });
+
+ test('matches a ZWJ sequence as one contiguous match', () => {
+ expect(ZWJ_FAMILY.match(regex)?.[0]).toBe(ZWJ_FAMILY);
+ });
+
+ test('does not match plain text', () => {
+ expect('hello'.match(regex)).toBeNull();
+ });
+
+ test('accepted degradation: keycap sequences are not matched', () => {
+ // Neither the digit, VS16, nor U+20E3 has Extended_Pictographic, so the
+ // fallback tier skips keycaps entirely. They render as plain text, which
+ // is the documented tradeoff of this tier.
+ expect(KEYCAP_ONE.match(regex)).toBeNull();
+ });
+ });
+
+ describe('never-match tier semantics', () => {
+ test('/$^/ never matches non-empty input, so the matcher no-ops', () => {
+ // Regression guard: the last-resort regex must be a real RegExp that
+ // matches nothing, not null (str.match(null) matches the string "null").
+ const never = /$^/;
+ expect('null'.match(never)).toBeNull();
+ expect(`party ${PARTY} time`.match(never)).toBeNull();
+ });
+ });
+});
+
+describe('ChatMessageEmojiMatcher.match', () => {
+ const matcher = new ChatMessageEmojiMatcher('emoji', { className: 'emoji' });
+
+ test('returns null when the message has no emoji', () => {
+ expect(matcher.match('no emoji here')).toBeNull();
+ });
+
+ test('returns the first emoji occurrence with its position and length', () => {
+ expect(matcher.match(`party ${PARTY} time`)).toEqual({
+ index: 6,
+ length: PARTY.length,
+ match: PARTY,
+ valid: true,
+ });
+ });
+});
diff --git a/web/tests/localeFlip.test.tsx b/web/tests/localeFlip.test.tsx
new file mode 100644
index 0000000000..94aba29090
--- /dev/null
+++ b/web/tests/localeFlip.test.tsx
@@ -0,0 +1,161 @@
+import React from 'react';
+import { act, render, screen } from '@testing-library/react';
+
+// These tests pin the next-export-i18n semantics that utils/localeLoader
+// depends on: the library only flips language when its query effect re-runs
+// AND the catalog for router.query.lang is already present in the shared
+// translations object. A library upgrade that changes any of this would
+// silently leave non-English viewers on English, so it must fail here first.
+
+// The library reads the shared catalog singleton (web/i18n) at module scope
+// and the tests below mutate it, so both modules come fresh out of
+// jest.isolateModules per test.
+//
+// react must NOT get a fresh copy inside that sandbox: react-dom (loaded out
+// here by testing-library) wires the hook dispatcher into THIS react
+// instance, and an isolated second copy would throw "Invalid hook call" the
+// moment the library calls useState. Pinning react to the single actual
+// instance keeps every registry, outer and isolated, on the same copy.
+jest.mock('react', () => jest.requireActual('react'));
+
+// The library's query effect lists router.query.lang in its deps, so
+// useRouter must hand back a FRESH object per render carrying the holder's
+// current query. A memoized router object would freeze the dep forever.
+const mockRouterState: { query: Record<string, string> } = { query: {} };
+
+jest.mock('next/router', () => ({
+ useRouter: () => ({ query: { ...mockRouterState.query } }),
+}));
+
+/* eslint-disable global-require, @typescript-eslint/no-var-requires */
+const enCatalog = require('../i18n/en/translation.json');
+const deCatalog = require('../i18n/de/translation.json');
+/* eslint-enable global-require, @typescript-eslint/no-var-requires */
+
+// Assert against the real catalog files, not hardcoded strings, so a
+// reworded translation cannot silently strand these tests.
+const KEY = 'Admin.AccessTokens.selectAll';
+const EN_VALUE: string = enCatalog.Admin.AccessTokens.selectAll;
+const DE_VALUE: string = deCatalog.Admin.AccessTokens.selectAll;
+
+interface I18nShape {
+ translations: Record<string, Record<string, unknown>>;
+}
+
+// Fresh library + fresh catalog singleton + a probe component built against
+// exactly that isolated copy of useTranslation.
+const freshHarness = (): { i18n: I18nShape; Probe: () => React.ReactElement } => {
+ let i18n!: I18nShape;
+ let Probe!: () => React.ReactElement;
+ jest.isolateModules(() => {
+ /* eslint-disable global-require, @typescript-eslint/no-var-requires */
+ i18n = require('../i18n');
+ const { useTranslation } = require('next-export-i18n');
+ /* eslint-enable global-require, @typescript-eslint/no-var-requires */
+ Probe = function LocaleProbe() {
+ const { t } = useTranslation();
+ return <span data-testid="probe">{t(KEY)}</span>;
+ };
+ });
+ return { i18n, Probe };
+};
+
+const probeText = () => screen.getByTestId('probe').textContent;
+
+const setQueryLang = (lang?: string) => {
+ mockRouterState.query = lang === undefined ? {} : { lang };
+};
+
+beforeEach(() => {
+ setQueryLang(undefined);
+});
+
+describe('next-export-i18n semantics the lazy locale loader depends on', () => {
+ beforeAll(() => {
+ // If a catalog edit ever made these two values equal, every assertion
+ // below would go vacuous. Fail loudly instead.
+ expect(typeof EN_VALUE).toBe('string');
+ expect(typeof DE_VALUE).toBe('string');
+ expect(EN_VALUE).not.toBe(DE_VALUE);
+ });
+
+ test('stays English when ?lang=de names a catalog that is not loaded', () => {
+ const { Probe } = freshHarness();
+ setQueryLang('de');
+ render(<Probe />);
+
+ // The query effect ran on mount, saw translations.de missing, and its
+ // guard refused the flip. This is what makes the loader's
+ // fetch-catalog-BEFORE-touching-the-query ordering mandatory.
+ expect(probeText()).toBe(EN_VALUE);
+ });
+
+ test('flips to German once the catalog is patched in and ?lang=de arrives', () => {
+ const { Probe, i18n } = freshHarness();
+ const { rerender } = render(<Probe />);
+ expect(probeText()).toBe(EN_VALUE);
+
+ // Exactly what loadViewerLocale does: mutate the shared translations
+ // object, then activate through the query channel.
+ i18n.translations.de = deCatalog;
+ setQueryLang('de');
+ act(() => {
+ rerender(<Probe />);
+ });
+
+ // A plain rerender sufficed here because router.query.lang changed
+ // (undefined -> 'de'), which re-runs the effect.
+ expect(probeText()).toBe(DE_VALUE);
+ });
+
+ test('keeps German after ?lang is removed again, which makes URL cleanup safe', () => {
+ const { Probe, i18n } = freshHarness();
+ const { rerender } = render(<Probe />);
+
+ i18n.translations.de = deCatalog;
+ setQueryLang('de');
+ act(() => {
+ rerender(<Probe />);
+ });
+ expect(probeText()).toBe(DE_VALUE);
+
+ // LocaleSync strips ?lang= after observing the flip. The library keeps
+ // its selected language: the effect re-runs (dep 'de' -> undefined) but
+ // its guard requires a truthy query value to change anything.
+ setQueryLang(undefined);
+ act(() => {
+ rerender(<Probe />);
+ });
+ expect(probeText()).toBe(DE_VALUE);
+ });
+
+ test('a plain rerender cannot flip when ?lang=de predates the catalog, so the loader must bounce the param', () => {
+ const { Probe, i18n } = freshHarness();
+ setQueryLang('de');
+ const { rerender } = render(<Probe />);
+ expect(probeText()).toBe(EN_VALUE);
+
+ // FINDING, pinned on purpose: patching the catalog alone changes no
+ // effect dep (lang, router.query.lang, and the translations object
+ // REFERENCE are all unchanged), so the effect never re-runs and the
+ // language stays stuck on English.
+ i18n.translations.de = deCatalog;
+ act(() => {
+ rerender(<Probe />);
+ });
+ expect(probeText()).toBe(EN_VALUE);
+
+ // The loader recovers by bouncing the query param off and back on,
+ // which is why loadViewerLocale does the replace-without-lang /
+ // replace-with-lang dance when ?lang= was already set.
+ setQueryLang(undefined);
+ act(() => {
+ rerender(<Probe />);
+ });
+ setQueryLang('de');
+ act(() => {
+ rerender(<Probe />);
+ });
+ expect(probeText()).toBe(DE_VALUE);
+ });
+});
diff --git a/web/tests/localeLoader.test.ts b/web/tests/localeLoader.test.ts
new file mode 100644
index 0000000000..022e296233
--- /dev/null
+++ b/web/tests/localeLoader.test.ts
@@ -0,0 +1,233 @@
+import fs from 'fs';
+import path from 'path';
+import type { NextRouter } from 'next/router';
+import type { loadViewerLocale, shouldCleanUrlAfterFlip } from '../utils/localeLoader';
+import { AVAILABLE_LOCALES, pickLocale } from '../utils/localeLoader';
+
+type LoadViewerLocale = typeof loadViewerLocale;
+type ShouldCleanUrlAfterFlip = typeof shouldCleanUrlAfterFlip;
+
+interface I18nShape {
+ translations: Record<string, Record<string, unknown>>;
+}
+
+// loadViewerLocale has a module-level once-guard, so every test that calls it
+// needs a fresh copy of the module. The loader mutates the i18n singleton it
+// imported, so both modules must come out of the same isolated registry or
+// the test would inspect a different object than the one being mutated.
+const freshModules = (): {
+ load: LoadViewerLocale;
+ shouldClean: ShouldCleanUrlAfterFlip;
+ i18n: I18nShape;
+} => {
+ let load!: LoadViewerLocale;
+ let shouldClean!: ShouldCleanUrlAfterFlip;
+ let i18n!: I18nShape;
+ jest.isolateModules(() => {
+ /* eslint-disable global-require, @typescript-eslint/no-var-requires */
+ load = require('../utils/localeLoader').loadViewerLocale;
+ shouldClean = require('../utils/localeLoader').shouldCleanUrlAfterFlip;
+ i18n = require('../i18n');
+ /* eslint-enable global-require, @typescript-eslint/no-var-requires */
+ });
+ return { load, shouldClean, i18n };
+};
+
+const setBrowserLanguage = (language: string) => {
+ Object.defineProperty(window.navigator, 'languages', {
+ value: [language],
+ configurable: true,
+ });
+};
+
+afterEach(() => {
+ // Remove the instance override so the next test (or file) sees jsdom's own
+ // navigator.languages again.
+ Reflect.deleteProperty(window.navigator, 'languages');
+});
+
+const makeRouter = (query: Record<string, string>) => {
+ const replace = jest.fn(async () => true);
+ const router = { query, replace } as unknown as NextRouter;
+ return { router, replace };
+};
+
+describe('pickLocale', () => {
+ test.each([
+ ['valid query wins over browser language', 'de', 'fr-FR', 'de'],
+ ['unknown query falls back to browser language', 'xx', 'de-DE', 'de'],
+ ['absent query uses browser language', undefined, 'de-DE', 'de'],
+ ['regional browser tag maps to its base locale', undefined, 'de-AT', 'de'],
+ ['browser tag is case-insensitive', undefined, 'DE-at', 'de'],
+ ['query is exact-match only, no case folding', 'DE', 'zz-ZZ', null],
+ ['english from the query needs no catalog', 'en', 'de-DE', null],
+ ['english from the browser needs no catalog', undefined, 'en-US', null],
+ ['unknown query and unknown browser yield nothing', 'xx', 'zz-ZZ', null],
+ ['both inputs missing yields nothing', undefined, undefined, null],
+ ])('%s', (_name, queryLang, browserLanguage, expected) => {
+ expect(pickLocale(queryLang, browserLanguage)).toBe(expected);
+ });
+});
+
+describe('AVAILABLE_LOCALES', () => {
+ test('offers en and de but deliberately not eu', () => {
+ expect(AVAILABLE_LOCALES).toContain('en');
+ expect(AVAILABLE_LOCALES).toContain('de');
+ expect(AVAILABLE_LOCALES).not.toContain('eu');
+ });
+
+ test('has no duplicate entries', () => {
+ expect(new Set(AVAILABLE_LOCALES).size).toBe(AVAILABLE_LOCALES.length);
+ });
+
+ test('every offered locale has a catalog file on disk', () => {
+ const missing = AVAILABLE_LOCALES.filter(
+ locale => !fs.existsSync(path.join(__dirname, '..', 'i18n', locale, 'translation.json')),
+ );
+ expect(missing).toEqual([]);
+ });
+});
+
+describe('loadViewerLocale', () => {
+ test('German browser without ?lang loads the catalog and sets lang once', async () => {
+ setBrowserLanguage('de-DE');
+ const { load, i18n } = freshModules();
+ const { router, replace } = makeRouter({ existing: 'param' });
+
+ await load(router);
+
+ // The real catalog was fetched and patched into the shared i18n object.
+ const de = i18n.translations.de as {
+ Admin: { AccessTokens: { createNewAccessToken: string } };
+ };
+ expect(typeof de.Admin.AccessTokens.createNewAccessToken).toBe('string');
+
+ // One replace that adds lang while keeping existing query params.
+ expect(replace).toHaveBeenCalledTimes(1);
+ expect(replace).toHaveBeenCalledWith({ query: { existing: 'param', lang: 'de' } }, undefined, {
+ shallow: true,
+ scroll: false,
+ });
+ });
+
+ test('explicit ?lang=de bounces the query param off and back on', async () => {
+ setBrowserLanguage('en-US');
+ const { load, i18n } = freshModules();
+ const { router, replace } = makeRouter({ lang: 'de', foo: 'bar' });
+
+ await load(router);
+
+ expect(i18n.translations.de).toBeDefined();
+ expect(replace).toHaveBeenCalledTimes(2);
+ expect(replace).toHaveBeenNthCalledWith(1, { query: { foo: 'bar' } }, undefined, {
+ shallow: true,
+ scroll: false,
+ });
+ expect(replace).toHaveBeenNthCalledWith(2, { query: { foo: 'bar', lang: 'de' } }, undefined, {
+ shallow: true,
+ scroll: false,
+ });
+ });
+
+ test('English browser without ?lang changes nothing', async () => {
+ setBrowserLanguage('en-US');
+ const { load, i18n } = freshModules();
+ const { router, replace } = makeRouter({});
+
+ await load(router);
+
+ expect(replace).not.toHaveBeenCalled();
+ expect(Object.keys(i18n.translations)).toEqual(['en']);
+ });
+
+ test('second call is a no-op even with different inputs', async () => {
+ setBrowserLanguage('de-DE');
+ const { load, i18n } = freshModules();
+ const first = makeRouter({});
+ await load(first.router);
+ expect(first.replace).toHaveBeenCalledTimes(1);
+
+ // Different browser language and an explicit ?lang: the once-guard must
+ // still win, so no French catalog and no navigation.
+ setBrowserLanguage('fr-FR');
+ const second = makeRouter({ lang: 'fr' });
+ await load(second.router);
+
+ expect(second.replace).not.toHaveBeenCalled();
+ expect(i18n.translations.fr).toBeUndefined();
+ });
+
+ test('a no-op first call does not consume the once-guard', async () => {
+ // Regression guard for the PR review comment: the guard flips only when
+ // a load actually starts, so an English first evaluation must leave the
+ // loader available for a later call on the same module instance.
+ setBrowserLanguage('en-US');
+ const { load, shouldClean, i18n } = freshModules();
+ const first = makeRouter({});
+ await load(first.router);
+
+ expect(first.replace).not.toHaveBeenCalled();
+ expect(Object.keys(i18n.translations)).toEqual(['en']);
+
+ // Same module instance, now with a loadable browser locale.
+ setBrowserLanguage('de-DE');
+ const second = makeRouter({});
+ await load(second.router);
+
+ expect(i18n.translations.de).toBeDefined();
+ expect(second.replace).toHaveBeenCalledTimes(1);
+ expect(second.replace).toHaveBeenCalledWith({ query: { lang: 'de' } }, undefined, {
+ shallow: true,
+ scroll: false,
+ });
+ expect(shouldClean('de')).toBe(true);
+ expect(shouldClean('de')).toBe(false);
+ });
+});
+
+describe('shouldCleanUrlAfterFlip', () => {
+ test('browser-default load registers a consume-once cleanup for its locale', async () => {
+ setBrowserLanguage('de-DE');
+ const { load, shouldClean } = freshModules();
+ const { router, replace } = makeRouter({});
+
+ await load(router);
+
+ // The loader itself never performs the cleanup: still exactly one
+ // replace, the one that adds ?lang=de.
+ expect(replace).toHaveBeenCalledTimes(1);
+
+ // A non-matching locale neither matches nor consumes the pending cleanup.
+ expect(shouldClean('fr')).toBe(false);
+
+ // The matching locale consumes it exactly once.
+ expect(shouldClean('de')).toBe(true);
+ expect(shouldClean('de')).toBe(false);
+ expect(shouldClean('fr')).toBe(false);
+ });
+
+ test('explicit ?lang load never registers a cleanup', async () => {
+ setBrowserLanguage('en-US');
+ const { load, shouldClean } = freshModules();
+ const { router, replace } = makeRouter({ lang: 'de' });
+
+ await load(router);
+
+ expect(replace).toHaveBeenCalledTimes(2);
+ expect(shouldClean('de')).toBe(false);
+ });
+
+ test('returns false before any load and after a no-op English load', async () => {
+ setBrowserLanguage('en-US');
+ const { load, shouldClean } = freshModules();
+
+ expect(shouldClean('de')).toBe(false);
+
+ const { router, replace } = makeRouter({});
+ await load(router);
+
+ expect(replace).not.toHaveBeenCalled();
+ expect(shouldClean('de')).toBe(false);
+ expect(shouldClean('en')).toBe(false);
+ });
+});
diff --git a/web/utils/localeLoader.ts b/web/utils/localeLoader.ts
new file mode 100644
index 0000000000..af4e0e7e7b
--- /dev/null
+++ b/web/utils/localeLoader.ts
@@ -0,0 +1,129 @@
+import type { NextRouter } from 'next/router';
+import i18n from '../i18n';
+
+/**
+ * Locales with a catalog under web/i18n/ that we offer to browsers. This
+ * mirrors the set that used to be bundled statically in i18n/index.js.
+ * ('eu' has a catalog on disk but was never wired up, so it stays out.)
+ */
+export const AVAILABLE_LOCALES = [
+ 'ar',
+ 'bn',
+ 'de',
+ 'el',
+ 'en',
+ 'es',
+ 'fr',
+ 'ga',
+ 'hi',
+ 'hr',
+ 'it',
+ 'ja',
+ 'ko',
+ 'ms',
+ 'nl',
+ 'no',
+ 'pa',
+ 'pl',
+ 'pt',
+ 'ru',
+ 'sv',
+ 'th',
+ 'vi',
+ 'zh',
+];
+
+/**
+ * Decides which locale catalog to fetch. An explicit, known ?lang= value
+ * wins, then the browser's primary language. English needs no fetch, and
+ * unknown values fall back to the browser language the same way the
+ * library's own detection did when every catalog was bundled.
+ */
+export const pickLocale = (
+ queryLang: string | undefined,
+ browserLanguage: string | undefined,
+): string | null => {
+ const fromQuery = queryLang && AVAILABLE_LOCALES.includes(queryLang) ? queryLang : null;
+ const short = (browserLanguage || '').split('-')[0].toLowerCase();
+ const fromBrowser = AVAILABLE_LOCALES.includes(short) ? short : null;
+ const locale = fromQuery || fromBrowser;
+ return locale && locale !== 'en' ? locale : null;
+};
+
+let loadStarted = false;
+
+let pendingUrlCleanup: string | null = null;
+
+/**
+ * LocaleSync (in _app) calls this on every selected-language change. It
+ * returns true exactly once: when the automatic flip for `lang` has landed
+ * and the temporary ?lang= parameter we added to trigger it should be
+ * removed again, so copied URLs don't pin this viewer's language. Explicit
+ * viewer-set ?lang= values never register a cleanup.
+ */
+export const shouldCleanUrlAfterFlip = (lang: string): boolean => {
+ if (!pendingUrlCleanup || pendingUrlCleanup !== lang) {
+ return false;
+ }
+ pendingUrlCleanup = null;
+ return true;
+};
+
+/**
+ * Fetches the viewer's locale catalog and activates it.
+ *
+ * next-export-i18n only re-evaluates the selected language when the ?lang
+ * query value changes: its translations dependency is the same object we
+ * mutate here (identity never changes), and its localStorage listener is
+ * inert under languageDataStore 'query'. So after patching the catalog in,
+ * we change the query parameter to re-run that effect, which now finds the
+ * catalog present and switches every t() over. If ?lang was already set we
+ * bounce it off and back on; the final effect run always sees the catalog,
+ * so the switch cannot be lost to effect timing.
+ */
+export const loadViewerLocale = async (router: NextRouter): Promise<void> => {
+ if (loadStarted || typeof window === 'undefined') {
+ return;
+ }
+
+ const queryLang = typeof router.query.lang === 'string' ? router.query.lang : undefined;
+ const browserLanguage = window.navigator.languages?.[0] || window.navigator.language;
+ const locale = pickLocale(queryLang, browserLanguage);
+ if (!locale || i18n.translations[locale]) {
+ return;
+ }
+ // Marked only once real work begins: a no-op evaluation (English browser,
+ // unknown locale, catalog already present) leaves the loader available for
+ // a later call that does name a loadable locale. Everything before this
+ // line is synchronous, so a double invocation (React strict mode) can't
+ // start the load twice.
+ loadStarted = true;
+
+ try {
+ // The locale is only known at runtime (browser language or ?lang=), so a
+ // static import cannot work here. webpack turns this into one chunk per
+ // catalog and loads just the one the viewer needs.
+ const catalog = await import(`../i18n/${locale}/translation.json`);
+ i18n.translations[locale] = catalog.default ?? catalog;
+
+ const { lang, ...rest } = router.query;
+ if (lang) {
+ // Explicit ?lang= stays in the URL. Bounce it off and back on so the
+ // library re-evaluates it now that the catalog exists.
+ await router.replace({ query: rest }, undefined, { shallow: true, scroll: false });
+ } else {
+ // The parameter is only being added to trigger the switch, so have
+ // LocaleSync remove it once the flip is confirmed to have landed.
+ pendingUrlCleanup = locale;
+ }
+ await router.replace({ query: { ...rest, lang: locale } }, undefined, {
+ shallow: true,
+ scroll: false,
+ });
+ } catch (e) {
+ // A failed catalog fetch (flaky network, content blocker) just leaves
+ // the page in English rather than surfacing an error.
+ pendingUrlCleanup = null;
+ console.error(`unable to load the '${locale}' translation catalog`, e);
+ }
+};