@prosopo/locale 3.6.1 → 3.7.0

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

@@ -1,241 +0,0 @@
-// Copyright 2021-2026 Prosopo (UK) Ltd.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// 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";
-
-// i18next is a mutable singleton and the module under test configures it as a
-// side effect of the first call. Both are mocked so each test starts from a
-// known `isInitialized` state without a real filesystem backend.
-
-type Listener = (...args: unknown[]) => void;
-
-interface FakeI18n {
-	isInitialized: boolean;
-	use: (plugin: unknown) => FakeI18n;
-	init: (options: InitOptions) => FakeI18n;
-	on: (event: string, listener: Listener) => void;
-}
-
-interface Harness {
-	fake: FakeI18n;
-	plugins: unknown[];
-	initOptions: InitOptions[];
-	listeners: Map<string, Listener[]>;
-	emit: (event: string) => void;
-}
-
-const makeHarness = (isInitialized: boolean): Harness => {
-	const plugins: unknown[] = [];
-	const initOptions: InitOptions[] = [];
-	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]);
-		},
-	};
-
-	return {
-		fake,
-		plugins,
-		initOptions,
-		listeners,
-		emit: (event: string): void => {
-			for (const listener of listeners.get(event) ?? []) {
-				listener();
-			}
-		},
-	};
-};
-
-/**
- * Load the module under a fresh registry with i18next, the filesystem backend
- * and the side detection all mocked.
- */
-const load = async (options: {
-	isInitialized?: boolean;
-	serverSide?: boolean;
-}): Promise<{
-	initializeI18n: (callback?: (value: i18n) => void) => i18n;
-	harness: Harness;
-}> => {
-	vi.resetModules();
-	const harness = makeHarness(options.isInitialized ?? false);
-
-	vi.doMock("i18next", () => ({ default: harness.fake }));
-	vi.doMock("i18next-fs-backend/cjs", () => ({ default: "FSBackend" }));
-	vi.doMock("i18next-http-middleware", () => ({
-		LanguageDetector: class {
-			options: unknown;
-			constructor(_services: unknown, opts: unknown) {
-				this.options = opts;
-			}
-		},
-	}));
-	vi.doMock("../util.js", () => ({
-		isServerSide: (): boolean => options.serverSide ?? true,
-		isClientSide: (): boolean => !(options.serverSide ?? true),
-	}));
-
-	const imported = await import("../i18nBackend.js");
-	return { initializeI18n: imported.default, harness };
-};
-
-afterEach(() => {
-	vi.resetModules();
-	vi.doUnmock("i18next");
-	vi.doUnmock("i18next-fs-backend/cjs");
-	vi.doUnmock("i18next-http-middleware");
-	vi.doUnmock("../util.js");
-});
-
-describe("i18nBackend on a server, not yet initialised", () => {
-	test("initialises i18next exactly once", async () => {
-		const { initializeI18n, harness } = await load({});
-		initializeI18n();
-		expect(harness.initOptions).toHaveLength(1);
-	});
-
-	test("registers the filesystem backend and the header language detector", async () => {
-		// The detector is what makes Accept-Language work; losing it would
-		// silently serve every request in the fallback language.
-		const { initializeI18n, harness } = await load({});
-		initializeI18n();
-		expect(harness.plugins).toHaveLength(2);
-		expect(harness.plugins[0]).toBe("FSBackend");
-	});
-
-	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?.supportedLngs).toContain("en");
-		expect(options?.nonExplicitSupportedLngs).toBe(false);
-	});
-
-	test("declares the translation namespace", async () => {
-		const { initializeI18n, harness } = await load({});
-		initializeI18n();
-		expect(harness.initOptions[0]?.ns).toEqual(["translation"]);
-	});
-
-	test("points the backend at a filesystem path, not a file:// URL", async () => {
-		// i18next-fs-backend reads with node:fs, which cannot open a file://
-		// URL — the module strips the scheme for exactly this reason.
-		const { initializeI18n, harness } = await load({});
-		initializeI18n();
-		const backend = harness.initOptions[0]?.backend as
-			| { loadPath?: string }
-			| undefined;
-		expect(backend?.loadPath).toBeDefined();
-		expect(backend?.loadPath).not.toContain("file://");
-		expect(backend?.loadPath).toContain("/locales/{{lng}}/{{ns}}.json");
-	});
-
-	test("defers the callback until resources have loaded", async () => {
-		const callback = vi.fn();
-		const { initializeI18n, harness } = await load({});
-
-		initializeI18n(callback);
-		expect(callback).not.toHaveBeenCalled();
-
-		harness.emit("loaded");
-		expect(callback).toHaveBeenCalledTimes(1);
-	});
-
-	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({});
-
-		initializeI18n(callback);
-		harness.emit("loaded");
-		harness.emit("loaded");
-		harness.emit("loaded");
-		expect(callback).toHaveBeenCalledTimes(1);
-	});
-
-	test("hands the i18next instance to the callback", async () => {
-		const callback = vi.fn();
-		const { initializeI18n, harness } = await load({});
-		initializeI18n(callback);
-		harness.emit("loaded");
-		expect(callback).toHaveBeenCalledWith(harness.fake);
-	});
-
-	test("returns the i18next instance", async () => {
-		const { initializeI18n, harness } = await load({});
-		expect(initializeI18n()).toBe(harness.fake);
-	});
-
-	test("tolerates being called with no callback at all", async () => {
-		const { initializeI18n, harness } = await load({});
-		initializeI18n();
-		expect(() => harness.emit("loaded")).not.toThrow();
-	});
-});
-
-// Both of these skip initialisation. The `loaded` listener is only registered
-// on the init path, so without an explicit callback here the caller
-// (loadI18next) would wait forever for an event that is never coming.
-describe("i18nBackend when there is nothing to initialise", () => {
-	test("fires the callback immediately when i18next is already up", async () => {
-		const callback = vi.fn();
-		const { initializeI18n, harness } = await load({ isInitialized: true });
-
-		const returned = initializeI18n(callback);
-
-		expect(harness.initOptions).toHaveLength(0);
-		expect(callback).toHaveBeenCalledTimes(1);
-		expect(callback).toHaveBeenCalledWith(harness.fake);
-		expect(returned).toBe(harness.fake);
-	});
-
-	test("fires the callback immediately when running client side", async () => {
-		// The filesystem backend cannot work in a browser, so initialisation is
-		// correctly skipped — but the caller still has to be released.
-		const callback = vi.fn();
-		const { initializeI18n, harness } = await load({ serverSide: false });
-
-		const returned = initializeI18n(callback);
-
-		expect(harness.initOptions).toHaveLength(0);
-		expect(callback).toHaveBeenCalledTimes(1);
-		expect(returned).toBe(harness.fake);
-	});
-
-	test("registers no plugins when initialisation is skipped", async () => {
-		const { initializeI18n, harness } = await load({ isInitialized: true });
-		initializeI18n();
-		expect(harness.plugins).toHaveLength(0);
-	});
-
-	test("tolerates no callback when initialisation is skipped", async () => {
-		const { initializeI18n } = await load({ isInitialized: true });
-		expect(() => initializeI18n()).not.toThrow();
-	});
-});

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

@@ -1,393 +0,0 @@
-// Copyright 2021-2026 Prosopo (UK) Ltd.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
-import type { Ti18n } from "../types.js";
-
-// 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 Catalogues = Record<string, Record<string, unknown>>;
-
-interface Harness {
-	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 (options: {
-	catalogues?: Catalogues;
-	languages?: string[];
-	cookie?: string;
-	stored?: string;
-	fetchFails?: boolean;
-	never?: boolean;
-}): Promise<Harness> => {
-	vi.resetModules();
-
-	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);
-			}
-			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;
-		},
-		set cookie(value: string) {
-			cookie = value;
-		},
-	});
-
-	const imported = await import("../i18nFrontend.js");
-	return {
-		initializeI18n: imported.default,
-		requested,
-		cookie: (): string => cookie,
-		stored: (): Record<string, string> => store,
-	};
-};
-
-/** 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();
-});
-
-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("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("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("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("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("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("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);
-	});
-});
-
-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("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",
-		);
-	});
-
-	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("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("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("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("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 });
-
-		const i18n = await initialised(harness);
-
-		expect(i18n.isInitialized).toBe(true);
-		expect(i18n.t("WIDGET.CHECKING", { defaultValue: "Checking" })).toBe(
-			"Checking",
-		);
-	});
-
-	test("reports the namespace as loaded so callers stop waiting", async () => {
-		const harness = await load({ catalogues: {}, fetchFails: true });
-
-		expect((await initialised(harness)).hasLoadedNamespace("translation")).toBe(
-			true,
-		);
-	});
-});
-
-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");
-	});
-
-	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");
-
-		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(callback).toHaveBeenCalledTimes(1);
-	});
-});
-
-describe("before the catalogue arrives", () => {
-	let harness: Harness;
-
-	beforeEach(async () => {
-		harness = await load({ never: true });
-	});
-
-	test("reports itself uninitialised", () => {
-		expect(harness.initializeI18n().isInitialized).toBe(false);
-	});
-
-	test("reports the namespace as not loaded", () => {
-		expect(harness.initializeI18n().hasLoadedNamespace("translation")).toBe(
-			false,
-		);
-	});
-});