@prosopo/locale 3.2.8 → 3.3.0

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

@@ -0,0 +1,241 @@
+// 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

@@ -0,0 +1,302 @@
+// 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";
+
+// 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.
+
+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;
+}
+
+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;
+}
+
+const load = async (
+	isInitialized = false,
+): Promise<{
+	initializeI18n: (callback?: (value: i18n) => void, lng?: string) => i18n;
+	harness: 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();
+			}
+		},
+	};
+
+	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);
+			}
+		},
+	}));
+	vi.doMock("i18next-resources-to-backend", () => ({
+		default: (loader: ResourceLoader): string => {
+			resourceLoaders.push(loader);
+			return "InMemoryBackend";
+		},
+	}));
+	vi.doMock("react-i18next", () => ({ initReactI18next: "initReactI18next" }));
+
+	const imported = await import("../i18nFrontend.js");
+	return { initializeI18n: imported.default, harness };
+};
+
+const backendOf = (
+	options: InitOptions | undefined,
+): { backends?: unknown[]; backendOptions?: { loadPath?: string }[] } =>
+	(options?.backend ?? {}) as {
+		backends?: unknown[];
+		backendOptions?: { loadPath?: string }[];
+	};
+
+afterEach(() => {
+	vi.resetModules();
+	for (const module of [
+		"i18next",
+		"i18next-chained-backend",
+		"i18next-http-backend",
+		"i18next-browser-languagedetector",
+		"i18next-resources-to-backend",
+		"react-i18next",
+	]) {
+		vi.doUnmock(module);
+	}
+});
+
+describe("i18nFrontend, first initialisation", () => {
+	test("initialises i18next exactly once", async () => {
+		const { initializeI18n, harness } = await load();
+		initializeI18n();
+		expect(harness.initOptions).toHaveLength(1);
+	});
+
+	test("registers the chained backend, the detector and the react binding", async () => {
+		const { initializeI18n, harness } = await load();
+		initializeI18n();
+		expect(harness.plugins).toHaveLength(3);
+		expect(harness.plugins[0]).toBe("ChainedBackend");
+		expect(harness.plugins[2]).toBe("initReactI18next");
+	});
+
+	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("returns the i18next instance", async () => {
+		const { initializeI18n, harness } = await load();
+		expect(initializeI18n()).toBe(harness.fake);
+	});
+});
+
+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");
+	});
+
+	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("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("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",
+		});
+	});
+
+	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"],
+		});
+	});
+});
+
+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("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("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("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();
+	});
+});
+
+describe("i18nFrontend callback", () => {
+	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).toHaveBeenCalledWith(harness.fake);
+	});
+
+	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");
+		expect(callback).toHaveBeenCalledTimes(1);
+	});
+
+	test("tolerates being called with no callback", async () => {
+		const { initializeI18n, harness } = await load();
+		initializeI18n();
+		expect(() => harness.emit("loaded")).not.toThrow();
+	});
+
+	// 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);
+
+		const returned = initializeI18n(callback);
+
+		expect(harness.initOptions).toHaveLength(0);
+		expect(callback).toHaveBeenCalledTimes(1);
+		expect(callback).toHaveBeenCalledWith(harness.fake);
+		expect(returned).toBe(harness.fake);
+	});
+
+	test("registers no plugins when already initialised", async () => {
+		const { initializeI18n, harness } = await load(true);
+		initializeI18n();
+		expect(harness.plugins).toHaveLength(0);
+	});
+
+	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);
+	});
+});

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

@@ -0,0 +1,140 @@
+// 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 { i18n } from "i18next";
+import type { handle } from "i18next-http-middleware";
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+type HandleOptions = NonNullable<Parameters<typeof handle>[1]>;
+type Handler = ReturnType<typeof handle>;
+
+const asI18n = (value: object): i18n => value as unknown as i18n;
+
+interface Harness {
+	instance: i18n;
+	handleCalls: [i18n, HandleOptions | undefined][];
+	handler: Handler;
+}
+
+const load = async (options: {
+	loadRejects?: boolean;
+}): Promise<{
+	i18nMiddleware: (opts: HandleOptions) => Promise<Handler>;
+	harness: Harness;
+}> => {
+	vi.resetModules();
+
+	const instance = asI18n({ name: "the singleton" });
+	const handleCalls: [i18n, HandleOptions | undefined][] = [];
+	const handler = ((): void => {}) as unknown as Handler;
+
+	vi.doMock("i18next-http-middleware", () => ({
+		handle: (i18next: i18n, opts?: HandleOptions): Handler => {
+			handleCalls.push([i18next, opts]);
+			return handler;
+		},
+	}));
+	vi.doMock("../loadI18next.js", () => ({
+		default: async (): Promise<i18n> => {
+			if (options.loadRejects) {
+				throw new Error("i18n failed to load");
+			}
+			return instance;
+		},
+	}));
+
+	const imported = await import("../i18nMiddleware.js");
+	return {
+		i18nMiddleware: imported.default,
+		harness: { instance, handleCalls, handler },
+	};
+};
+
+afterEach(() => {
+	vi.resetModules();
+	vi.doUnmock("i18next-http-middleware");
+	vi.doUnmock("../loadI18next.js");
+});
+
+describe("i18nMiddleware", () => {
+	test("builds the handler from the loaded i18next instance", async () => {
+		const { i18nMiddleware, harness } = await load({});
+
+		const handler = await i18nMiddleware({});
+
+		expect(harness.handleCalls).toHaveLength(1);
+		expect(harness.handleCalls[0]?.[0]).toBe(harness.instance);
+		expect(handler).toBe(harness.handler);
+	});
+
+	test("forwards the caller's options", async () => {
+		const { i18nMiddleware, harness } = await load({});
+		const options: HandleOptions = { ignoreRoutes: ["/healthz"] };
+
+		await i18nMiddleware(options);
+
+		expect(harness.handleCalls[0]?.[1]).toEqual({ ignoreRoutes: ["/healthz"] });
+	});
+
+	test("copies the options rather than passing the caller's object through", async () => {
+		// handle() keeps the object for the lifetime of the process, so sharing
+		// it would let a later mutation by the caller silently change routing.
+		const { i18nMiddleware, harness } = await load({});
+		const options: HandleOptions = { ignoreRoutes: ["/healthz"] };
+
+		await i18nMiddleware(options);
+
+		expect(harness.handleCalls[0]?.[1]).not.toBe(options);
+	});
+
+	test("accepts an empty options object", async () => {
+		const { i18nMiddleware, harness } = await load({});
+		await i18nMiddleware({});
+		expect(harness.handleCalls[0]?.[1]).toEqual({});
+	});
+
+	test("always requests the backend instance", async () => {
+		// Middleware only ever runs on the server; asking for the frontend
+		// instance would pull in the browser detector and http backend.
+		const loadSpy = vi.fn(async (): Promise<i18n> => asI18n({}));
+		vi.resetModules();
+		vi.doMock("i18next-http-middleware", () => ({
+			handle: (): Handler => ((): void => {}) as unknown as Handler,
+		}));
+		vi.doMock("../loadI18next.js", () => ({ default: loadSpy }));
+
+		const imported = await import("../i18nMiddleware.js");
+		await imported.default({});
+
+		expect(loadSpy).toHaveBeenCalledWith(true);
+	});
+
+	test("propagates a failure to load i18next instead of returning a broken handler", async () => {
+		// The caller mounts whatever this resolves to. Swallowing the error
+		// would mount a handler over an uninitialised i18next and fail on the
+		// first request instead of at boot.
+		const { i18nMiddleware } = await load({ loadRejects: true });
+
+		await expect(i18nMiddleware({})).rejects.toThrow("i18n failed to load");
+	});
+
+	test("returns a fresh handler per call", async () => {
+		const { i18nMiddleware, harness } = await load({});
+
+		await i18nMiddleware({});
+		await i18nMiddleware({ ignoreRoutes: ["/x"] });
+
+		expect(harness.handleCalls).toHaveLength(2);
+	});
+});