@prosopo/locale 3.2.9 → 3.3.0

package/dist/tests/useTranslation.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=useTranslation.unit.test.d.ts.map

package/dist/tests/useTranslation.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTranslation.unit.test.d.ts","sourceRoot":"","sources":["../../src/tests/useTranslation.unit.test.ts"],"names":[],"mappings":""}

package/dist/tests/useTranslation.unit.test.js

@@ -0,0 +1,81 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+const asI18n = (value) => value;
+const load = async () => {
+    vi.resetModules();
+    const instance = asI18n({ name: "package instance" });
+    const calls = [];
+    let initCalls = 0;
+    vi.doMock("../i18nFrontend.js", () => ({
+        default: () => {
+            initCalls += 1;
+            return instance;
+        },
+    }));
+    vi.doMock("react-i18next", () => ({
+        useTranslation: (namespace, options) => {
+            calls.push([namespace, options]);
+            return { t: (key) => key, i18n: options.i18n };
+        },
+    }));
+    const imported = await import("../useTranslation.js");
+    return {
+        useTranslation: imported.default,
+        instance,
+        calls,
+        initCount: () => initCalls,
+    };
+};
+afterEach(() => {
+    vi.resetModules();
+    vi.doUnmock("../i18nFrontend.js");
+    vi.doUnmock("react-i18next");
+});
+describe("useTranslation", () => {
+    test("always asks for the translation namespace", async () => {
+        const { useTranslation, calls } = await load();
+        useTranslation();
+        expect(calls[0]?.[0]).toBe("translation");
+    });
+    test("injects the package's own i18next instance", async () => {
+        const { useTranslation, calls, instance } = await load();
+        useTranslation();
+        expect(calls[0]?.[1].i18n).toBe(instance);
+    });
+    test("initialises the frontend instance on use", async () => {
+        const { useTranslation, initCount } = await load();
+        useTranslation();
+        expect(initCount()).toBe(1);
+    });
+    test("works with no options at all", async () => {
+        const { useTranslation, calls } = await load();
+        useTranslation();
+        expect(calls[0]?.[1]).toEqual({ i18n: expect.anything() });
+    });
+    test("passes caller options through", async () => {
+        const { useTranslation, calls } = await load();
+        useTranslation({ nsMode: "fallback", useSuspense: false });
+        expect(calls[0]?.[1]).toMatchObject({
+            nsMode: "fallback",
+            useSuspense: false,
+        });
+    });
+    test("lets the caller override the instance, since options spread last", async () => {
+        const { useTranslation, calls, instance } = await load();
+        const other = asI18n({ name: "caller instance" });
+        useTranslation({ i18n: other });
+        expect(calls[0]?.[1].i18n).toBe(other);
+        expect(calls[0]?.[1].i18n).not.toBe(instance);
+    });
+    test("returns whatever react-i18next returns", async () => {
+        const { useTranslation } = await load();
+        const result = useTranslation();
+        expect(result.t("WIDGET.SUBMIT")).toBe("WIDGET.SUBMIT");
+    });
+    test("re-initialises on every call, matching hook semantics", async () => {
+        const { useTranslation, initCount } = await load();
+        useTranslation();
+        useTranslation();
+        expect(initCount()).toBe(2);
+    });
+});
+//# sourceMappingURL=useTranslation.unit.test.js.map

package/dist/tests/useTranslation.unit.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTranslation.unit.test.js","sourceRoot":"","sources":["../../src/tests/useTranslation.unit.test.ts"],"names":[],"mappings":"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"}

package/dist/tests/util.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=util.unit.test.d.ts.map

package/dist/tests/util.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.unit.test.d.ts","sourceRoot":"","sources":["../../src/tests/util.unit.test.ts"],"names":[],"mappings":""}

package/dist/tests/util.unit.test.js

@@ -0,0 +1,66 @@
+import { afterEach, describe, expect, test } from "vitest";
+import { isClientSide, isServerSide } from "../util.js";
+const setWindow = (value) => {
+    if (value === undefined) {
+        Reflect.deleteProperty(globalThis, "window");
+        return;
+    }
+    Object.defineProperty(globalThis, "window", {
+        value,
+        configurable: true,
+        writable: true,
+    });
+};
+afterEach(() => {
+    setWindow(undefined);
+});
+describe("isClientSide", () => {
+    test("is false under plain node, where there is no window at all", () => {
+        expect(isClientSide()).toBe(false);
+    });
+    test("is true when window exposes document.createElement", () => {
+        setWindow({ document: { createElement: () => { } } });
+        expect(isClientSide()).toBe(true);
+    });
+    test("is false when window exists but has no document", () => {
+        setWindow({});
+        expect(isClientSide()).toBe(false);
+    });
+    test("is false when document exists but has no createElement", () => {
+        setWindow({ document: {} });
+        expect(isClientSide()).toBe(false);
+    });
+    test("is false when createElement is present but undefined", () => {
+        setWindow({ document: { createElement: undefined } });
+        expect(isClientSide()).toBe(false);
+    });
+    test("returns a real boolean, not the truthy function itself", () => {
+        const createElement = () => { };
+        setWindow({ document: { createElement } });
+        const result = isClientSide();
+        expect(result).toBe(true);
+        expect(typeof result).toBe("boolean");
+    });
+});
+describe("isServerSide", () => {
+    test("is true under plain node", () => {
+        expect(isServerSide()).toBe(true);
+    });
+    test("is false in a browser-like environment", () => {
+        setWindow({ document: { createElement: () => { } } });
+        expect(isServerSide()).toBe(false);
+    });
+    test("is always the exact negation of isClientSide", () => {
+        const environments = [
+            undefined,
+            {},
+            { document: {} },
+            { document: { createElement: () => { } } },
+        ];
+        for (const environment of environments) {
+            setWindow(environment);
+            expect(isServerSide()).toBe(!isClientSide());
+        }
+    });
+});
+//# sourceMappingURL=util.unit.test.js.map

package/dist/tests/util.unit.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.unit.test.js","sourceRoot":"","sources":["../../src/tests/util.unit.test.ts"],"names":[],"mappings":"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"}

package/dist/translationKey.d.ts

@@ -1,4 +1,8 @@
 import { z } from "zod";
+export type TranslationNode = {
+    [key: string]: TranslationNode | string;
+} | string;
+export declare function getLeafFieldPath(obj: TranslationNode): string[];
 export declare const TranslationKeysSchema: z.ZodEnum<[string, ...string[]]>;
 export type TranslationKey = z.infer<typeof TranslationKeysSchema>;
 //# sourceMappingURL=translationKey.d.ts.map

package/dist/translationKey.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"translationKey.d.ts","sourceRoot":"","sources":["../src/translationKey.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA6BxB,eAAO,MAAM,qBAAqB,kCAEjC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}
+{"version":3,"file":"translationKey.d.ts","sourceRoot":"","sources":["../src/translationKey.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,MAAM,eAAe,GACxB;IACA,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,MAAM,CAAC;CACvC,GACD,MAAM,CAAC;AAKV,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,EAAE,CA8B/D;AAED,eAAO,MAAM,qBAAqB,kCAEjC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/translationKey.js

@@ -6,6 +6,7 @@ function getLeafFieldPath(obj) {
 	return Object.keys(obj).reduce((arr, key) => {
 		const value = obj[key];
 		if (value === void 0) throw new Error(`Undefined value for key ${key}`);
+		if (typeof value === "string") return arr.concat(key);
 		const children = getLeafFieldPath(value);
 		return arr.concat(children.map((child) => {
 			return `${key}.${child}`;
@@ -14,4 +15,4 @@ function getLeafFieldPath(obj) {
 }
 var TranslationKeysSchema = z$1.enum(getLeafFieldPath(translation_default));
 //#endregion
-export { TranslationKeysSchema };
+export { TranslationKeysSchema, getLeafFieldPath };

package/dist/translationKey.js.map

@@ -1 +1 @@
-{"version":3,"file":"translationKey.js","sourceRoot":"","sources":["../src/translationKey.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,aAAa,MAAM,+BAA+B,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAQhF,SAAS,gBAAgB,CAAC,GAAS;IAClC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,EAAE,CAAC;IACX,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAC3C,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,2BAA2B,GAAG,EAAE,CAAC,CAAC;QACnD,CAAC;QACD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QAEzC,OAAO,GAAG,CAAC,MAAM,CAChB,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACtB,OAAO,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC;QAC1B,CAAC,CAAC,CACF,CAAC;IACH,CAAC,EAAE,EAAc,CAAC,CAAC;AACpB,CAAC;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,IAAI,CAC1C,gBAAgB,CAAC,aAAa,CAA0B,CACxD,CAAC"}
+{"version":3,"file":"translationKey.js","sourceRoot":"","sources":["../src/translationKey.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,aAAa,MAAM,+BAA+B,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAWhF,MAAM,UAAU,gBAAgB,CAAC,GAAoB;IACpD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,EAAE,CAAC;IACX,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAC3C,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,2BAA2B,GAAG,EAAE,CAAC,CAAC;QACnD,CAAC;QASD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC/B,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;QAED,MAAM,QAAQ,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QAEzC,OAAO,GAAG,CAAC,MAAM,CAChB,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACtB,OAAO,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC;QAC1B,CAAC,CAAC,CACF,CAAC;IACH,CAAC,EAAE,EAAc,CAAC,CAAC;AACpB,CAAC;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,IAAI,CAC1C,gBAAgB,CAAC,aAAa,CAA0B,CACxD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@prosopo/locale",
-	"version": "3.2.9",
+	"version": "3.3.0",
 	"description": "Prosopo locale library",
 	"type": "module",
 	"engines": {

package/src/i18SharedOptions.ts

@@ -11,14 +11,14 @@
 // 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 { getProcess } from "./process.js";
 import { LanguageSchema, Languages } from "./translations.js";
 
-// Guard the `process.env` read so the module is loadable in a plain browser
-// runtime where `process` is undefined. Without the guard, any side-effectful
+// Read through getProcess() so the module stays loadable in a plain browser
+// runtime where `process` is undefined. Without that guard, any side-effectful
 // runtime import of `@prosopo/types` (which transitively reaches here via
 // `LanguageSchema`) crashes the page in Vite's dev/preview mode.
-const logLevel =
-	typeof process !== "undefined" ? process.env?.PROSOPO_LOG_LEVEL : undefined;
+const logLevel = getProcess()?.env?.PROSOPO_LOG_LEVEL;
 
 export const i18nSharedOptions = {
 	debug: logLevel === "debug",

package/src/i18nBackend.ts

@@ -43,9 +43,25 @@ export function initializeI18n(
 					loadPath,
 				},
 			});
+		// "loaded" fires once per namespace, and again after changeLanguage(),
+		// so the raw event is not the one-shot signal the callback expects.
+		// Latch it here as well as in loadI18next: this callback is public and
+		// a caller could reasonably use it to run a side effect.
+		let notified = false;
 		i18n.on("loaded", () => {
+			if (notified) {
+				return;
+			}
+			notified = true;
 			i18nLoadedCallback?.(i18n);
 		});
+	} else {
+		// Nothing to initialise — either i18next is already up (a frontend
+		// consumer got there first) or we are not on the server. The `loaded`
+		// handler above is only registered inside the init branch, so without
+		// this the callback would never fire and loadI18next() would stay
+		// pending forever instead of handing back the instance we already have.
+		i18nLoadedCallback?.(i18n);
 	}
 	return i18n;
 }

package/src/i18nFrontend.ts

@@ -79,9 +79,25 @@ export function initializeI18n(
 				},
 				...reactOptions,
 			} as InitOptions);
+		// "loaded" fires once per namespace, and again after changeLanguage(),
+		// so the raw event is not the one-shot signal the callback expects.
+		// Latch it here as well as in loadI18next: this callback is public and
+		// a caller could reasonably use it to run a side effect.
+		let notified = false;
 		i18n.on("loaded", () => {
+			if (notified) {
+				return;
+			}
+			notified = true;
 			i18nLoadedCallback?.(i18n);
 		});
+	} else {
+		// Already initialised (e.g. useTranslation() ran first, or a second
+		// widget mounted). The `loaded` handler is only registered in the init
+		// branch, so the callback has to fire here or loadI18next() never
+		// settles. Resources are already present, so resolving immediately is
+		// correct; the caller reconciles the language afterwards.
+		i18nLoadedCallback?.(i18n);
 	}
 	return i18n;
 }

package/src/loadI18next.ts

@@ -15,6 +15,18 @@
 import type { i18n } from "i18next";
 let i18nInstance: i18n;
 
+/**
+ * How long to wait for i18next to report `loaded` before giving up on it.
+ *
+ * Resolution is driven by an event, and events are not guaranteed: a backend
+ * that never answers (http backend against a dead CDN, fs backend against a
+ * missing locales dir) leaves the listener armed and the promise pending for
+ * the lifetime of the process. `cli.ts` calls loadI18next(true).then(...) with
+ * nothing to time it out, so a pending promise there is a silent boot hang with
+ * no log line to explain it.
+ */
+export const I18N_LOAD_TIMEOUT_MS = 10_000;
+
 const reconcileLanguage = async (
 	instance: i18n,
 	lng: string | undefined,
@@ -27,26 +39,82 @@ const reconcileLanguage = async (
 
 async function loadI18next(backend: boolean, lng?: string): Promise<i18n> {
 	return new Promise((resolve, reject) => {
-		try {
-			if (backend) {
-				import("./i18nBackend.js").then(({ default: initializeI18n }) => {
+		// On timeout we resolve with the (possibly not fully loaded) instance
+		// rather than rejecting. i18next falls back to the key itself when a
+		// resource is missing, so a degraded instance renders untranslated text;
+		// a rejection instead takes down the caller, and neither caller handles
+		// one — cli.ts has no .catch, and widgetFactory awaits it inside the
+		// render path, so the widget would not appear at all. Untranslated beats
+		// absent. Genuine errors still reject: this arm only fires on silence.
+		let settled = false;
+		// No `settled` guard needed here: both latches clear this timer, so it
+		// can only fire while nothing has settled.
+		const timer = setTimeout(() => {
+			settled = true;
+			if (i18nInstance) {
+				resolve(i18nInstance);
+			} else {
+				reject(
+					new Error(
+						`i18next did not load within ${I18N_LOAD_TIMEOUT_MS}ms and no instance was created`,
+					),
+				);
+			}
+		}, I18N_LOAD_TIMEOUT_MS);
+		// Node keeps the event loop alive for a pending timer, which would hold
+		// a short-lived CLI process open for the full timeout after it had
+		// otherwise finished.
+		timer.unref?.();
+
+		// Both latches are one-shot: i18next can emit `loaded` more than once
+		// (per namespace, and again after changeLanguage), and a late event
+		// arriving after the timeout must not re-settle or leak a second timer.
+		const done = (instance: i18n): void => {
+			if (settled) {
+				return;
+			}
+			settled = true;
+			clearTimeout(timer);
+			resolve(instance);
+		};
+		const failWith = (error: unknown): void => {
+			if (settled) {
+				return;
+			}
+			settled = true;
+			clearTimeout(timer);
+			reject(error);
+		};
+
+		// Every asynchronous branch below terminates in `.catch(failWith)`. A
+		// synchronous try/catch cannot see a rejected dynamic import or a
+		// rejected changeLanguage(), so without these the executor would
+		// simply return and the promise would stay pending forever — callers
+		// (i18nMiddleware, and through it the whole server bootstrap) would
+		// hang rather than fail.
+		if (backend) {
+			import("./i18nBackend.js")
+				.then(({ default: initializeI18n }) => {
 					if (!i18nInstance) {
-						// pass the resolver into the i18n init fn which will resolve after i18n connected fires
-						i18nInstance = initializeI18n(resolve);
+						// pass the resolver into the i18n init fn, which fires it on the first
+						// "loaded" event
+						i18nInstance = initializeI18n(done);
 					} else {
 						// we've already initialised i18n so just return it
-						resolve(i18nInstance);
+						done(i18nInstance);
 					}
-				});
-			} else {
-				import("./i18nFrontend.js").then(({ default: initializeI18n }) => {
+				})
+				.catch(failWith);
+		} else {
+			import("./i18nFrontend.js")
+				.then(({ default: initializeI18n }) => {
 					if (!i18nInstance) {
 						// Pass `lng` in on first init so browser detection is skipped
 						// entirely when the site owner has supplied a language. The
 						// resolver only fires on the `loaded` event, so at resolve
 						// time the target-language resources are guaranteed present.
 						i18nInstance = initializeI18n((instance) => {
-							void reconcileLanguage(instance, lng).then(resolve);
+							void reconcileLanguage(instance, lng).then(done).catch(failWith);
 						}, lng);
 					} else {
 						// Singleton already exists (e.g. a prior widget mounted with a
@@ -54,12 +122,12 @@ async function loadI18next(backend: boolean, lng?: string): Promise<i18n> {
 						// Reconcile before resolving so callers can render synchronously
 						// against the requested language instead of seeing a flash of
 						// the previous one.
-						void reconcileLanguage(i18nInstance, lng).then(resolve);
+						void reconcileLanguage(i18nInstance, lng)
+							.then(done)
+							.catch(failWith);
 					}
-				});
-			}
-		} catch (e) {
-			reject(e);
+				})
+				.catch(failWith);
 		}
 	});
 }

package/src/process.ts

@@ -0,0 +1,29 @@
+// 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.
+
+/**
+ * The `process` global, or undefined where there is none.
+ *
+ * This package is reached transitively from browser bundles, where `process`
+ * may be missing entirely or present but stripped down. A bare `process.env`
+ * read throws a ReferenceError in that case and takes the whole page down.
+ *
+ * It is a function, and it lives in its own module, so callers can be tested
+ * against a runtime that has no `process` at all. Inlining the `typeof` check
+ * at the point of use makes that branch untestable: vitest calls
+ * `process.memoryUsage()` between suites, so stubbing the real global away
+ * fails the run rather than the module under test.
+ */
+export const getProcess = (): NodeJS.Process | undefined =>
+	typeof process !== "undefined" ? process : undefined;

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

@@ -0,0 +1,139 @@
+// 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 { Languages } from "../translations.js";
+
+// The module reads process.env at import time, so every expectation about the
+// debug flag has to re-import it under a fresh module registry.
+type SharedOptions =
+	typeof import("../i18SharedOptions.js")["i18nSharedOptions"];
+
+const loadOptions = async (): Promise<SharedOptions> => {
+	vi.resetModules();
+	const { i18nSharedOptions } = await import("../i18SharedOptions.js");
+	return i18nSharedOptions;
+};
+
+const originalLogLevel = process.env.PROSOPO_LOG_LEVEL;
+
+beforeEach(() => {
+	Reflect.deleteProperty(process.env, "PROSOPO_LOG_LEVEL");
+});
+
+afterEach(() => {
+	vi.doUnmock("../process.js");
+	vi.resetModules();
+	if (originalLogLevel === undefined) {
+		Reflect.deleteProperty(process.env, "PROSOPO_LOG_LEVEL");
+	} else {
+		process.env.PROSOPO_LOG_LEVEL = originalLogLevel;
+	}
+});
+
+describe("i18nSharedOptions", () => {
+	test("falls back to English", async () => {
+		const options = await loadOptions();
+		expect(options.fallbackLng).toBe("en");
+	});
+
+	test("uses the single translation namespace", async () => {
+		const options = await loadOptions();
+		expect(options.namespace).toBe("translation");
+	});
+
+	test("supports exactly the declared language codes", async () => {
+		const options = await loadOptions();
+		expect(new Set(options.supportedLngs)).toEqual(
+			new Set(Object.values(Languages)),
+		);
+	});
+
+	// With this false, i18next will not silently serve `en` resources for a
+	// request for `en-GB`. Flipping it would quietly change which file a
+	// regional locale resolves to.
+	test("does not accept non-explicit regional variants", async () => {
+		const options = await loadOptions();
+		expect(options.nonExplicitSupportedLngs).toBe(false);
+	});
+
+	describe("debug flag", () => {
+		test("is off when PROSOPO_LOG_LEVEL is unset", async () => {
+			const options = await loadOptions();
+			expect(options.debug).toBe(false);
+		});
+
+		test("is on only for the exact value 'debug'", async () => {
+			process.env.PROSOPO_LOG_LEVEL = "debug";
+			expect((await loadOptions()).debug).toBe(true);
+		});
+
+		test("is off for any other log level", async () => {
+			for (const level of ["info", "warn", "error", "trace", ""]) {
+				process.env.PROSOPO_LOG_LEVEL = level;
+				expect((await loadOptions()).debug, level).toBe(false);
+			}
+		});
+
+		test("is case sensitive — 'DEBUG' does not enable it", async () => {
+			process.env.PROSOPO_LOG_LEVEL = "DEBUG";
+			expect((await loadOptions()).debug).toBe(false);
+		});
+	});
+
+	// This module is reached transitively from browser bundles, where `process`
+	// is absent or partial, so both degraded shapes have to load cleanly.
+	//
+	// The `process` read goes through getProcess() precisely so it can be mocked
+	// here. Stubbing the global instead is not viable: vitest itself calls
+	// process.memoryUsage() between suites, so removing the real global fails
+	// the run rather than the module under test.
+	describe("browser runtime, where process may be absent or partial", () => {
+		const mockProcess = (value: NodeJS.Process | undefined): void => {
+			vi.resetModules();
+			vi.doMock("../process.js", () => ({
+				getProcess: (): NodeJS.Process | undefined => value,
+			}));
+		};
+
+		test("loads when there is no process at all", async () => {
+			mockProcess(undefined);
+			const { i18nSharedOptions } = await import("../i18SharedOptions.js");
+			expect(i18nSharedOptions.debug).toBe(false);
+			expect(i18nSharedOptions.fallbackLng).toBe("en");
+		});
+
+		test("loads when process exists but exposes no env", async () => {
+			// Prototype-chained off the real process so the shape stays honest;
+			// only `env` is shadowed away.
+			const partial: NodeJS.Process = Object.create(process);
+			Reflect.defineProperty(partial, "env", {
+				value: undefined,
+				configurable: true,
+			});
+			mockProcess(partial);
+
+			const { i18nSharedOptions } = await import("../i18SharedOptions.js");
+			expect(i18nSharedOptions.debug).toBe(false);
+			expect(i18nSharedOptions.fallbackLng).toBe("en");
+		});
+
+		test("still reads the log level when process is present", async () => {
+			process.env.PROSOPO_LOG_LEVEL = "debug";
+			mockProcess(process);
+			const { i18nSharedOptions } = await import("../i18SharedOptions.js");
+			expect(i18nSharedOptions.debug).toBe(true);
+		});
+	});
+});