@prosopo/locale 3.2.9 → 3.3.0

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

@@ -0,0 +1,166 @@
+// 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 { describe, expect, test } from "vitest";
+import translationEn from "../locales/en/translation.json" with {
+	type: "json",
+};
+import {
+	TranslationKeysSchema,
+	type TranslationNode,
+	getLeafFieldPath,
+} from "../translationKey.js";
+
+describe("getLeafFieldPath", () => {
+	test("returns no paths for a bare string, which is a leaf and not a container", () => {
+		expect(getLeafFieldPath("a string")).toEqual([]);
+	});
+
+	test("returns no paths for the empty string", () => {
+		expect(getLeafFieldPath("")).toEqual([]);
+	});
+
+	// The string is the leaf, so the path ends at its key. This used to yield
+	// [] — the recursion returned nothing for a string and the parent mapped
+	// over that empty list — which made the whole function return [] for every
+	// input and left TranslationKeysSchema an empty enum.
+	test("emits a top-level string value under its own key", () => {
+		expect(getLeafFieldPath({ topLevel: "value" })).toEqual(["topLevel"]);
+	});
+
+	test("emits section.key for a one-level-deep section", () => {
+		expect(getLeafFieldPath({ section: { key: "value" } })).toEqual([
+			"section.key",
+		]);
+	});
+
+	test("emits every key of a section, in insertion order", () => {
+		expect(
+			getLeafFieldPath({ section: { first: "1", second: "2", third: "3" } }),
+		).toEqual(["section.first", "section.second", "section.third"]);
+	});
+
+	test("recurses to arbitrary depth, joining each level with a dot", () => {
+		expect(getLeafFieldPath({ a: { b: { c: { d: "leaf" } } } })).toEqual([
+			"a.b.c.d",
+		]);
+	});
+
+	test("handles sibling branches of differing depth", () => {
+		expect(
+			getLeafFieldPath({
+				shallow: { key: "v" },
+				deep: { nested: { key: "v" } },
+			}),
+		).toEqual(["shallow.key", "deep.nested.key"]);
+	});
+
+	test("returns no paths for an empty object", () => {
+		expect(getLeafFieldPath({})).toEqual([]);
+	});
+
+	// Same silent-drop hazard as the top-level string: an empty section
+	// contributes nothing rather than erroring, so a translation file that
+	// loses all of a section's contents still parses.
+	test("drops an empty nested section rather than erroring", () => {
+		expect(getLeafFieldPath({ section: {} })).toEqual([]);
+	});
+
+	test("keeps populated siblings when one section is empty", () => {
+		expect(getLeafFieldPath({ empty: {}, full: { key: "v" } })).toEqual([
+			"full.key",
+		]);
+	});
+
+	// Object.keys never yields a key whose value is undefined by omission, so
+	// this guard is only reachable via an explicitly-assigned undefined. It
+	// still has to hold: a JSON file cannot express it, but a caller passing a
+	// hand-built object can, and a silently-skipped key would corrupt the
+	// schema.
+	test("throws on an explicitly undefined value, naming the offending key", () => {
+		const node = {
+			section: { broken: undefined },
+		} as unknown as TranslationNode;
+		expect(() => getLeafFieldPath(node)).toThrow(
+			"Undefined value for key broken",
+		);
+	});
+
+	test("throws before emitting any of the sibling keys of the broken one", () => {
+		const node = {
+			section: { ok: "v", broken: undefined },
+		} as unknown as TranslationNode;
+		expect(() => getLeafFieldPath(node)).toThrow(/Undefined value/);
+	});
+
+	test("does not mutate the input", () => {
+		const node: TranslationNode = { section: { key: "value" } };
+		const snapshot = JSON.stringify(node);
+		getLeafFieldPath(node);
+		expect(JSON.stringify(node)).toBe(snapshot);
+	});
+});
+
+describe("TranslationKeysSchema", () => {
+	const keys = getLeafFieldPath(translationEn as TranslationNode);
+
+	test("is non-empty — an empty z.enum would throw at module load", () => {
+		expect(keys.length).toBeGreaterThan(0);
+	});
+
+	test("accepts every key derived from the English translation", () => {
+		for (const key of keys) {
+			expect(TranslationKeysSchema.parse(key)).toBe(key);
+		}
+	});
+
+	test("rejects a key that is not in the English translation", () => {
+		expect(() => TranslationKeysSchema.parse("no.such.key")).toThrow();
+	});
+
+	test("rejects the empty string", () => {
+		expect(() => TranslationKeysSchema.parse("")).toThrow();
+	});
+
+	test("rejects a section name on its own — only leaves are valid keys", () => {
+		const [firstKey] = keys;
+		expect(firstKey).toBeDefined();
+		const section = String(firstKey).split(".")[0];
+		expect(() => TranslationKeysSchema.parse(section)).toThrow();
+	});
+
+	test("rejects non-string input", () => {
+		expect(() => TranslationKeysSchema.parse(42)).toThrow();
+		expect(() => TranslationKeysSchema.parse(null)).toThrow();
+		expect(() => TranslationKeysSchema.parse(undefined)).toThrow();
+	});
+
+	test("safeParse reports failure without throwing", () => {
+		const result = TranslationKeysSchema.safeParse("no.such.key");
+		expect(result.success).toBe(false);
+	});
+
+	test("is case sensitive", () => {
+		const [firstKey] = keys;
+		expect(firstKey).toBeDefined();
+		const upper = String(firstKey).toUpperCase();
+		if (upper !== firstKey) {
+			expect(() => TranslationKeysSchema.parse(upper)).toThrow();
+		}
+	});
+
+	test("exposes exactly the derived keys as enum options", () => {
+		expect(new Set(TranslationKeysSchema.options)).toEqual(new Set(keys));
+	});
+});

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

@@ -0,0 +1,110 @@
+// 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 fs from "node:fs";
+import path from "node:path";
+import { describe, expect, test } from "vitest";
+import { LanguageSchema, Languages } from "../translations.js";
+
+const codes: string[] = Object.values(Languages);
+
+describe("Languages", () => {
+	test("is non-empty", () => {
+		expect(codes.length).toBeGreaterThan(0);
+	});
+
+	test("maps English language names to BCP 47 codes", () => {
+		expect(Languages.english).toBe("en");
+		expect(Languages.chinese).toBe("zh-CN");
+		expect(Languages.portugeseBrazil).toBe("pt-BR");
+	});
+
+	test("includes the fallback language", () => {
+		expect(codes).toContain("en");
+	});
+
+	// A duplicated code would silently shrink LanguageSchema's enum and make
+	// one of the language names unreachable, while the locales-folder count
+	// test would still pass.
+	test("has no duplicate codes", () => {
+		expect(new Set(codes).size).toBe(codes.length);
+	});
+
+	test("every code is a well-formed, lowercase-primary language tag", () => {
+		for (const code of codes) {
+			expect(code).toMatch(/^[a-z]{2}(-[A-Z]{2})?$/);
+		}
+	});
+
+	test("every code has a locales directory containing translation.json", () => {
+		for (const code of codes) {
+			const file = path.resolve(`./src/locales/${code}/translation.json`);
+			expect(fs.existsSync(file), `missing ${code}`).toBe(true);
+		}
+	});
+
+	test("every locales directory is claimed by a code — no orphans", () => {
+		const dirs = fs.readdirSync(path.resolve("./src/locales"));
+		for (const dir of dirs) {
+			expect(codes, `orphan locale directory ${dir}`).toContain(dir);
+		}
+	});
+});
+
+describe("LanguageSchema", () => {
+	test("accepts every declared code", () => {
+		for (const code of codes) {
+			expect(LanguageSchema.parse(code)).toBe(code);
+		}
+	});
+
+	test("exposes each code on .enum for use as a constant", () => {
+		expect(LanguageSchema.enum.en).toBe("en");
+	});
+
+	test("rejects an undeclared language code", () => {
+		expect(() => LanguageSchema.parse("xx")).toThrow();
+	});
+
+	test("rejects the empty string", () => {
+		expect(() => LanguageSchema.parse("")).toThrow();
+	});
+
+	// i18next treats `en-GB` as a region of `en`, but the schema is a plain
+	// enum with `nonExplicitSupportedLngs: false` alongside it, so a regional
+	// variant of a supported language is *not* itself valid input.
+	test("rejects a regional variant of a supported language", () => {
+		expect(() => LanguageSchema.parse("en-GB")).toThrow();
+	});
+
+	test("is case sensitive — `EN` is not `en`", () => {
+		expect(() => LanguageSchema.parse("EN")).toThrow();
+	});
+
+	test("rejects non-string input", () => {
+		expect(() => LanguageSchema.parse(1)).toThrow();
+		expect(() => LanguageSchema.parse(null)).toThrow();
+		expect(() => LanguageSchema.parse(undefined)).toThrow();
+		expect(() => LanguageSchema.parse(["en"])).toThrow();
+	});
+
+	test("safeParse reports failure without throwing", () => {
+		expect(LanguageSchema.safeParse("xx").success).toBe(false);
+		expect(LanguageSchema.safeParse("en").success).toBe(true);
+	});
+
+	test("its options are exactly the declared codes", () => {
+		expect(new Set(LanguageSchema.options)).toEqual(new Set(codes));
+	});
+});

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

@@ -0,0 +1,134 @@
+// 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 { UseTranslationOptions } from "react-i18next";
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+// The hook is a thin wrapper: it forces the package's own i18next instance in
+// rather than letting react-i18next pick up whichever instance a host app's
+// provider happens to expose. React itself is never rendered here, so both
+// react-i18next and the frontend initialiser are mocked.
+
+type DefaultCall = [string, { i18n: i18n } & Record<string, unknown>];
+
+const asI18n = (value: object): i18n => value as unknown as i18n;
+
+const load = async (): Promise<{
+	useTranslation: (options?: UseTranslationOptions<"translation">) => unknown;
+	instance: i18n;
+	calls: DefaultCall[];
+	initCount: () => number;
+}> => {
+	vi.resetModules();
+
+	const instance = asI18n({ name: "package instance" });
+	const calls: DefaultCall[] = [];
+	let initCalls = 0;
+
+	vi.doMock("../i18nFrontend.js", () => ({
+		default: (): i18n => {
+			initCalls += 1;
+			return instance;
+		},
+	}));
+	vi.doMock("react-i18next", () => ({
+		useTranslation: (
+			namespace: string,
+			options: { i18n: i18n } & Record<string, unknown>,
+		): unknown => {
+			calls.push([namespace, options]);
+			return { t: (key: string): string => key, i18n: options.i18n };
+		},
+	}));
+
+	const imported = await import("../useTranslation.js");
+	return {
+		useTranslation: imported.default,
+		instance,
+		calls,
+		initCount: (): number => 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 () => {
+		// Without this, a host application that mounts its own I18nextProvider
+		// would capture the widget's translations and render its keys instead.
+		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 () => {
+		// Worth pinning: the spread order means a caller-supplied i18n wins.
+		// That is useful for tests and storybooks, and dangerous by accident,
+		// so it should not change silently.
+		const { useTranslation, calls, instance } = await load();
+		const other = asI18n({ name: "caller instance" });
+
+		useTranslation({ i18n: other } as UseTranslationOptions<"translation">);
+
+		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() as { t: (key: string) => string };
+		expect(result.t("WIDGET.SUBMIT")).toBe("WIDGET.SUBMIT");
+	});
+
+	test("re-initialises on every call, matching hook semantics", async () => {
+		// initializeI18n is idempotent, so calling it per render is safe; the
+		// test exists so that stops being true loudly rather than quietly.
+		const { useTranslation, initCount } = await load();
+		useTranslation();
+		useTranslation();
+		expect(initCount()).toBe(2);
+	});
+});

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

@@ -0,0 +1,102 @@
+// 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, describe, expect, test } from "vitest";
+import { isClientSide, isServerSide } from "../util.js";
+
+// The detection reads `window` off the global object, so each test installs a
+// fake and the teardown removes it. Reflect.deleteProperty rather than
+// `delete globalThis.window` keeps TypeScript happy about an optional global.
+type FakeWindow = {
+	document?: { createElement?: unknown };
+};
+
+const setWindow = (value: FakeWindow | undefined): void => {
+	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: (): void => {} } });
+		expect(isClientSide()).toBe(true);
+	});
+
+	// The three guards are checked in order and each one has to be able to
+	// veto on its own, otherwise a half-built environment (jsdom teardown, a
+	// server-side-rendering shim that stubs `window` but not `document`) would
+	// be misread as a browser and the frontend i18n path would be selected on
+	// a server.
+	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 = (): void => {};
+		setWindow({ document: { createElement } });
+		const result: boolean = 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: (): void => {} } });
+		expect(isServerSide()).toBe(false);
+	});
+
+	test("is always the exact negation of isClientSide", () => {
+		const environments: (FakeWindow | undefined)[] = [
+			undefined,
+			{},
+			{ document: {} },
+			{ document: { createElement: (): void => {} } },
+		];
+		for (const environment of environments) {
+			setWindow(environment);
+			expect(isServerSide()).toBe(!isClientSide());
+		}
+	});
+});

package/src/translationKey.ts

@@ -15,13 +15,16 @@
 import { z } from "zod";
 import translationEn from "./locales/en/translation.json" with { type: "json" };
 
-type Node =
+export type TranslationNode =
 	| {
-			[key: string]: Node | string;
+			[key: string]: TranslationNode | string;
 	  }
 	| string;
 
-function getLeafFieldPath(obj: Node): string[] {
+// Exported so the traversal can be exercised directly against shapes the
+// bundled English translation happens not to contain (deep nesting, empty
+// objects, explicitly-undefined values).
+export function getLeafFieldPath(obj: TranslationNode): string[] {
 	if (typeof obj === "string") {
 		return [];
 	}
@@ -31,6 +34,18 @@ function getLeafFieldPath(obj: Node): string[] {
 		if (value === undefined) {
 			throw new Error(`Undefined value for key ${key}`);
 		}
+
+		// A string value IS the leaf, so the path ends here. Recursing into it
+		// returns [] and the `children.map` below then contributes nothing,
+		// which is how this function used to return an empty array for every
+		// input — leaving TranslationKeysSchema an empty z.enum. That enum is
+		// spread into three mongoose `reason` fields (types-database
+		// provider.ts), and mongoose registers its enum validator even for an
+		// empty list, so every non-null reason failed validation.
+		if (typeof value === "string") {
+			return arr.concat(key);
+		}
+
 		const children = getLeafFieldPath(value);
 
 		return arr.concat(