@prosopo/locale 3.5.0 → 3.6.0

package/src/tests/i18nFrontend.unit.test.ts

@@ -12,288 +12,382 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import type { InitOptions, i18n } from "i18next";
-import { afterEach, describe, expect, test, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import type { Ti18n } from "../types.js";
 
-// Every plugin is mocked: they reach for localStorage, cookies and the network,
-// none of which exists here and none of which this module's own logic needs.
+// The module keeps a singleton, so every test re-imports it under a fresh
+// registry. `fetch`, `localStorage`, `navigator.languages` and `document.cookie`
+// are the module's four inputs and are all stubbed per test.
 
-type Listener = (...args: unknown[]) => void;
-type ResourceLoader = (language: string, namespace: string) => Promise<unknown>;
-
-interface FakeI18n {
-	isInitialized: boolean;
-	use: (plugin: unknown) => FakeI18n;
-	init: (options: InitOptions) => FakeI18n;
-	on: (event: string, listener: Listener) => void;
-}
+type Catalogues = Record<string, Record<string, unknown>>;
 
 interface Harness {
-	fake: FakeI18n;
-	plugins: unknown[];
-	initOptions: InitOptions[];
-	/** The loader handed to resourcesToBackend — the in-memory fallback. */
-	resourceLoaders: ResourceLoader[];
-	detectorOptions: unknown[];
-	emit: (event: string) => void;
+	initializeI18n: (callback?: (value: Ti18n) => void, lng?: string) => Ti18n;
+	/** Every URL passed to fetch, in call order. */
+	requested: string[];
+	cookie: () => string;
+	stored: () => Record<string, string>;
 }
 
-const load = async (
-	isInitialized = false,
-): Promise<{
-	initializeI18n: (callback?: (value: i18n) => void, lng?: string) => i18n;
-	harness: Harness;
-}> => {
+const load = async (options: {
+	catalogues?: Catalogues;
+	languages?: string[];
+	cookie?: string;
+	stored?: string;
+	fetchFails?: boolean;
+	never?: boolean;
+}): Promise<Harness> => {
 	vi.resetModules();
 
-	const plugins: unknown[] = [];
-	const initOptions: InitOptions[] = [];
-	const resourceLoaders: ResourceLoader[] = [];
-	const detectorOptions: unknown[] = [];
-	const listeners = new Map<string, Listener[]>();
-
-	const fake: FakeI18n = {
-		isInitialized,
-		use: (plugin: unknown): FakeI18n => {
-			plugins.push(plugin);
-			return fake;
-		},
-		init: (options: InitOptions): FakeI18n => {
-			initOptions.push(options);
-			return fake;
-		},
-		on: (event: string, listener: Listener): void => {
-			listeners.set(event, [...(listeners.get(event) ?? []), listener]);
-		},
-	};
-
-	const harness: Harness = {
-		fake,
-		plugins,
-		initOptions,
-		resourceLoaders,
-		detectorOptions,
-		emit: (event: string): void => {
-			for (const listener of listeners.get(event) ?? []) {
-				listener();
+	const requested: string[] = [];
+	const store: Record<string, string> = options.stored
+		? { i18nextLng: options.stored }
+		: {};
+	let cookie = options.cookie ? `i18next=${options.cookie}` : "";
+
+	vi.stubGlobal(
+		"fetch",
+		vi.fn(async (url: string): Promise<Response> => {
+			requested.push(url);
+			if (options.never) {
+				return new Promise<Response>(() => undefined);
 			}
-		},
-	};
-
-	vi.doMock("i18next", () => ({ default: fake }));
-	vi.doMock("i18next-chained-backend", () => ({ default: "ChainedBackend" }));
-	vi.doMock("i18next-http-backend", () => ({ default: "HttpBackend" }));
-	vi.doMock("i18next-browser-languagedetector", () => ({
-		default: class {
-			constructor(_services: unknown, opts: unknown) {
-				detectorOptions.push(opts);
+			if (options.fetchFails) {
+				throw new Error("network down");
 			}
+			const language = url.split("/").at(-2) ?? "";
+			const body = options.catalogues?.[language];
+			return {
+				ok: body !== undefined,
+				json: async (): Promise<unknown> => body,
+			} as Response;
+		}),
+	);
+	vi.stubGlobal("localStorage", {
+		getItem: (key: string): string | null => store[key] ?? null,
+		setItem: (key: string, value: string): void => {
+			store[key] = value;
+		},
+	});
+	vi.stubGlobal("navigator", { languages: options.languages ?? ["en"] });
+	vi.stubGlobal("document", {
+		get cookie(): string {
+			return cookie;
 		},
-	}));
-	vi.doMock("i18next-resources-to-backend", () => ({
-		default: (loader: ResourceLoader): string => {
-			resourceLoaders.push(loader);
-			return "InMemoryBackend";
+		set cookie(value: string) {
+			cookie = value;
 		},
-	}));
+	});
 
 	const imported = await import("../i18nFrontend.js");
-	return { initializeI18n: imported.default, harness };
+	return {
+		initializeI18n: imported.default,
+		requested,
+		cookie: (): string => cookie,
+		stored: (): Record<string, string> => store,
+	};
 };
 
-const backendOf = (
-	options: InitOptions | undefined,
-): { backends?: unknown[]; backendOptions?: { loadPath?: string }[] } =>
-	(options?.backend ?? {}) as {
-		backends?: unknown[];
-		backendOptions?: { loadPath?: string }[];
-	};
+/** Resolves with the instance the init callback hands back. */
+const initialised = async (harness: Harness, lng?: string): Promise<Ti18n> =>
+	new Promise<Ti18n>((resolve) => {
+		harness.initializeI18n(resolve, lng);
+	});
 
 afterEach(() => {
+	vi.unstubAllGlobals();
 	vi.resetModules();
-	for (const module of [
-		"i18next",
-		"i18next-chained-backend",
-		"i18next-http-backend",
-		"i18next-browser-languagedetector",
-		"i18next-resources-to-backend",
-	]) {
-		vi.doUnmock(module);
-	}
 });
 
-describe("i18nFrontend, first initialisation", () => {
-	test("initialises i18next exactly once", async () => {
-		const { initializeI18n, harness } = await load();
-		initializeI18n();
-		expect(harness.initOptions).toHaveLength(1);
+describe("choosing a language", () => {
+	test("uses the language the caller asked for", async () => {
+		// The site owner's `data-language` is the single source of truth: reading
+		// the browser first would render a flash of the wrong language.
+		const harness = await load({
+			catalogues: { fr: {}, en: {} },
+			languages: ["de"],
+		});
+
+		const i18n = await initialised(harness, "fr");
+
+		expect(i18n.language).toBe("fr");
 	});
 
-	test("registers the chained backend and the language detector", async () => {
-		const { initializeI18n, harness } = await load();
-		initializeI18n();
-		expect(harness.plugins).toHaveLength(2);
-		expect(harness.plugins[0]).toBe("ChainedBackend");
+	test("prefers a cookie over the browser", async () => {
+		const harness = await load({
+			catalogues: { es: {}, en: {} },
+			cookie: "es",
+			stored: "de",
+			languages: ["it"],
+		});
+
+		expect((await initialised(harness)).language).toBe("es");
 	});
 
-	test("carries the shared options through to init", async () => {
-		const { initializeI18n, harness } = await load();
-		initializeI18n();
-		const options = harness.initOptions[0];
-		expect(options?.fallbackLng).toBe("en");
-		expect(options?.nonExplicitSupportedLngs).toBe(false);
-		expect(options?.supportedLngs).toContain("en");
+	test("prefers stored over the browser", async () => {
+		const harness = await load({
+			catalogues: { de: {}, en: {} },
+			stored: "de",
+			languages: ["it"],
+		});
+
+		expect((await initialised(harness)).language).toBe("de");
 	});
 
-	test("returns the i18next instance", async () => {
-		const { initializeI18n, harness } = await load();
-		expect(initializeI18n()).toBe(harness.fake);
+	test("falls back to the browser when nothing is remembered", async () => {
+		const harness = await load({
+			catalogues: { it: {}, en: {} },
+			languages: ["it"],
+		});
+
+		expect((await initialised(harness)).language).toBe("it");
+	});
+
+	test("resolves a regional tag to its base language", async () => {
+		// Browsers report en-GB, pt-PT and so on; only the base languages (plus
+		// the handful of regional catalogues) are shipped.
+		const harness = await load({
+			catalogues: { en: {} },
+			languages: ["de-AT"],
+		});
+
+		expect((await initialised(harness)).language).toBe("de");
+	});
+
+	test("ignores a language with no catalogue", async () => {
+		const harness = await load({ catalogues: { en: {} }, languages: ["xx"] });
+
+		expect((await initialised(harness)).language).toBe("en");
+	});
+
+	test("remembers the language in both cookie and storage", async () => {
+		// Kept from the i18next language detector: a visitor who has picked a
+		// language keeps it across pages that embed the widget.
+		const harness = await load({ catalogues: { fr: {}, en: {} } });
+
+		await initialised(harness, "fr");
+
+		expect(harness.stored().i18nextLng).toBe("fr");
+		expect(harness.cookie()).toContain("i18next=fr");
 	});
 });
 
-describe("i18nFrontend language selection", () => {
-	// The whole point of threading lng through init: with it set, i18next never
-	// consults the browser, so no child component can render against a
-	// detected language before an effect corrects it.
-	test("pins lng when the site owner supplied one", async () => {
-		const { initializeI18n, harness } = await load();
-		initializeI18n(undefined, "fr");
-		expect(harness.initOptions[0]?.lng).toBe("fr");
+describe("fetching catalogues", () => {
+	test("loads the active language from the directory the module came from", async () => {
+		const harness = await load({ catalogues: { fr: {}, en: {} } });
+
+		await initialised(harness, "fr");
+
+		expect(
+			harness.requested.some((url) =>
+				url.endsWith("/locales/fr/translation.json"),
+			),
+		).toBe(true);
 	});
 
-	test("omits lng entirely when none was supplied, leaving detection on", async () => {
-		const { initializeI18n, harness } = await load();
-		initializeI18n();
-		expect(harness.initOptions[0]).not.toHaveProperty("lng");
+	test("loads English alongside it, for keys a translation is missing", async () => {
+		const harness = await load({ catalogues: { fr: {}, en: {} } });
+
+		await initialised(harness, "fr");
+
+		expect(harness.requested).toHaveLength(2);
+		expect(
+			harness.requested.some((url) =>
+				url.endsWith("/locales/en/translation.json"),
+			),
+		).toBe(true);
 	});
 
-	test("treats the empty string as no language rather than pinning it", async () => {
-		// An empty `lng` would make i18next resolve nothing at all; falling back
-		// to detection is the only sane reading of a blank config value.
-		const { initializeI18n, harness } = await load();
-		initializeI18n(undefined, "");
-		expect(harness.initOptions[0]).not.toHaveProperty("lng");
+	test("fetches once when the active language is already English", async () => {
+		const harness = await load({ catalogues: { en: {} } });
+
+		await initialised(harness, "en");
+
+		expect(harness.requested).toHaveLength(1);
 	});
+});
 
-	test("configures the detector to prefer a stored choice over the browser", async () => {
-		const { initializeI18n, harness } = await load();
-		initializeI18n();
-		expect(harness.detectorOptions[0]).toMatchObject({
-			order: ["cookie", "localStorage", "navigator"],
-			lookupQuerystring: "lng",
+describe("translating", () => {
+	test("reads a nested key by its dotted path", async () => {
+		const harness = await load({
+			catalogues: { en: { WIDGET: { I_AM_HUMAN: "I am human" } } },
 		});
+
+		expect((await initialised(harness)).t("WIDGET.I_AM_HUMAN")).toBe(
+			"I am human",
+		);
 	});
 
-	test("persists the detected language to localStorage and a cookie", async () => {
-		const { initializeI18n, harness } = await load();
-		initializeI18n();
-		expect(harness.detectorOptions[0]).toMatchObject({
-			caches: ["localStorage", "cookie"],
+	test("substitutes interpolation values", async () => {
+		const harness = await load({
+			catalogues: { en: { POSITION: "{{x}} across, {{y}} down" } },
 		});
+
+		expect((await initialised(harness)).t("POSITION", { x: 10, y: 20 })).toBe(
+			"10 across, 20 down",
+		);
 	});
-});
 
-describe("i18nFrontend resource loading", () => {
-	test("chains an in-memory fallback behind the http backend", async () => {
-		// If the http load fails — a CDN blip, an offline widget — the bundled
-		// resources still answer, so the widget renders text rather than keys.
-		const { initializeI18n, harness } = await load();
-		initializeI18n();
-		const backend = backendOf(harness.initOptions[0]);
-		expect(backend.backends).toEqual(["HttpBackend", "InMemoryBackend"]);
+	test("falls back to English when the translation lacks the key", async () => {
+		const harness = await load({
+			catalogues: { fr: { KEPT: "gardé" }, en: { KEPT: "kept", ONLY: "only" } },
+		});
+		const i18n = await initialised(harness, "fr");
+
+		expect(i18n.t("KEPT")).toBe("gardé");
+		expect(i18n.t("ONLY")).toBe("only");
 	});
 
-	test("gives the http backend a templated load path", async () => {
-		const { initializeI18n, harness } = await load();
-		initializeI18n();
-		const backend = backendOf(harness.initOptions[0]);
-		const loadPath = backend.backendOptions?.[0]?.loadPath;
-		expect(loadPath).toContain("/locales/{{lng}}/{{ns}}.json");
+	test("falls back to the caller's default when no catalogue has the key", async () => {
+		const harness = await load({ catalogues: { en: {} } });
+
+		expect(
+			(await initialised(harness)).t("WIDGET.CHECKING", {
+				defaultValue: "Checking that you are human",
+			}),
+		).toBe("Checking that you are human");
 	});
 
-	test("derives the load path from the module URL, not the page URL", async () => {
-		// The widget is embedded on arbitrary sites, so a page-relative path
-		// would resolve against the host site and 404.
-		const { initializeI18n, harness } = await load();
-		initializeI18n();
-		const loadPath = backendOf(harness.initOptions[0]).backendOptions?.[0]
-			?.loadPath;
-		// Absolute, with a scheme — file:// here, https:// once bundled and
-		// served. What matters is that it is not relative.
-		expect(loadPath).toMatch(/^[a-z]+:\/\//);
-		// The module's own filename must have been stripped before the locales
-		// segment is appended, or the path would nest under the script itself.
-		expect(loadPath).not.toContain("i18nFrontend");
+	test("interpolates the default too", async () => {
+		const harness = await load({ catalogues: { en: {} } });
+
+		expect(
+			(await initialised(harness)).t("POSITION", {
+				defaultValue: "{{x}} across",
+				x: 7,
+			}),
+		).toBe("7 across");
 	});
 
-	test("hands resourcesToBackend a loader that resolves a language and namespace", async () => {
-		const { initializeI18n, harness } = await load();
-		initializeI18n();
-		const loader = harness.resourceLoaders[0];
-		expect(loader).toBeTypeOf("function");
-		// Invoked for its import, whose success depends on the bundler rather
-		// than on this module; only the call shape is this module's contract.
-		await expect(
-			Promise.resolve(loader?.("en", "translation")).catch(() => undefined),
-		).resolves.not.toThrow();
+	test("falls back to the key when there is no default either", async () => {
+		const harness = await load({ catalogues: { en: {} } });
+
+		expect((await initialised(harness)).t("WIDGET.MISSING")).toBe(
+			"WIDGET.MISSING",
+		);
+	});
+
+	test("leaves a placeholder alone when no value was supplied for it", async () => {
+		const harness = await load({
+			catalogues: { en: { GREET: "hello {{name}}" } },
+		});
+
+		expect((await initialised(harness)).t("GREET", { other: 1 })).toBe(
+			"hello {{name}}",
+		);
 	});
 });
 
-describe("i18nFrontend callback", () => {
-	test("defers the callback until resources have loaded", async () => {
-		const callback = vi.fn();
-		const { initializeI18n, harness } = await load();
+describe("when the catalogue cannot be fetched", () => {
+	test("still initialises, so the widget renders untranslated", async () => {
+		// Untranslated beats absent: a widget whose label never arrives is a
+		// widget the visitor cannot use.
+		const harness = await load({ catalogues: {}, fetchFails: true });
 
-		initializeI18n(callback);
-		expect(callback).not.toHaveBeenCalled();
+		const i18n = await initialised(harness);
 
-		harness.emit("loaded");
-		expect(callback).toHaveBeenCalledWith(harness.fake);
+		expect(i18n.isInitialized).toBe(true);
+		expect(i18n.t("WIDGET.CHECKING", { defaultValue: "Checking" })).toBe(
+			"Checking",
+		);
 	});
 
-	test("fires the callback once, however often `loaded` is emitted", async () => {
-		// i18next emits `loaded` per namespace and again after changeLanguage,
-		// so an unguarded listener would repeat whatever side effect the caller
-		// attached to it.
-		const callback = vi.fn();
-		const { initializeI18n, harness } = await load();
+	test("reports the namespace as loaded so callers stop waiting", async () => {
+		const harness = await load({ catalogues: {}, fetchFails: true });
 
-		initializeI18n(callback);
-		harness.emit("loaded");
-		harness.emit("loaded");
-		expect(callback).toHaveBeenCalledTimes(1);
+		expect((await initialised(harness)).hasLoadedNamespace("translation")).toBe(
+			true,
+		);
 	});
+});
 
-	test("tolerates being called with no callback", async () => {
-		const { initializeI18n, harness } = await load();
-		initializeI18n();
-		expect(() => harness.emit("loaded")).not.toThrow();
+describe("switching language", () => {
+	test("loads the new catalogue and translates against it", async () => {
+		const harness = await load({
+			catalogues: { en: { YES: "yes" }, de: { YES: "ja" } },
+		});
+		const i18n = await initialised(harness, "en");
+
+		await i18n.changeLanguage("de");
+
+		expect(i18n.language).toBe("de");
+		expect(i18n.t("YES")).toBe("ja");
 	});
 
-	// The `loaded` listener is only registered on the init path, so a second
-	// widget mounting after the first would otherwise wait on an event that has
-	// already fired and will not fire again.
-	test("fires the callback immediately when i18next is already initialised", async () => {
-		const callback = vi.fn();
-		const { initializeI18n, harness } = await load(true);
+	test("notifies subscribers", async () => {
+		const harness = await load({ catalogues: { en: {}, de: {} } });
+		const i18n = await initialised(harness, "en");
+		const listener = vi.fn();
+		i18n.on("languageChanged", listener);
+
+		await i18n.changeLanguage("de");
 
-		const returned = initializeI18n(callback);
+		expect(listener).toHaveBeenCalled();
+	});
+
+	test("does nothing when the language is already active", async () => {
+		const harness = await load({ catalogues: { en: {} } });
+		const i18n = await initialised(harness, "en");
+		const before = harness.requested.length;
+
+		await i18n.changeLanguage("en");
+
+		expect(harness.requested).toHaveLength(before);
+	});
+
+	test("unsubscribed listeners stop being called", async () => {
+		const harness = await load({ catalogues: { en: {}, de: {} } });
+		const i18n = await initialised(harness, "en");
+		const listener = vi.fn();
+		i18n.on("languageChanged", listener);
+		i18n.off("languageChanged", listener);
+
+		await i18n.changeLanguage("de");
+
+		expect(listener).not.toHaveBeenCalled();
+	});
+});
+
+describe("the singleton", () => {
+	test("a second call reuses the instance rather than refetching", async () => {
+		// Every widget on the page shares one catalogue fetch.
+		const harness = await load({ catalogues: { en: {} } });
+		const first = await initialised(harness);
+		const before = harness.requested.length;
+
+		const second = harness.initializeI18n();
+
+		expect(second).toBe(first);
+		expect(harness.requested).toHaveLength(before);
+	});
+
+	test("a second call still fires its callback", async () => {
+		// The one-shot callback is only armed on first init, so without this
+		// loadI18next() would never settle for the second widget.
+		const harness = await load({ catalogues: { en: {} } });
+		await initialised(harness);
+
+		const callback = vi.fn();
+		harness.initializeI18n(callback);
 
-		expect(harness.initOptions).toHaveLength(0);
 		expect(callback).toHaveBeenCalledTimes(1);
-		expect(callback).toHaveBeenCalledWith(harness.fake);
-		expect(returned).toBe(harness.fake);
+	});
+});
+
+describe("before the catalogue arrives", () => {
+	let harness: Harness;
+
+	beforeEach(async () => {
+		harness = await load({ never: true });
 	});
 
-	test("registers no plugins when already initialised", async () => {
-		const { initializeI18n, harness } = await load(true);
-		initializeI18n();
-		expect(harness.plugins).toHaveLength(0);
+	test("reports itself uninitialised", () => {
+		expect(harness.initializeI18n().isInitialized).toBe(false);
 	});
 
-	test("ignores lng when already initialised — the caller reconciles instead", async () => {
-		const { initializeI18n, harness } = await load(true);
-		initializeI18n(undefined, "fr");
-		expect(harness.initOptions).toHaveLength(0);
+	test("reports the namespace as not loaded", () => {
+		expect(harness.initializeI18n().hasLoadedNamespace("translation")).toBe(
+			false,
+		);
 	});
 });