@prosopo/locale 3.6.2 → 3.8.0

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

@@ -1,213 +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 { i18n } from "i18next";
-import { afterEach, describe, expect, test, vi } from "vitest";
-import type { Translator } from "../translator.js";
-
-// The translator is a thin wrapper: it forces the package's own i18next
-// instance in rather than letting a host app's provider decide, and exposes the
-// three events that used to drive a React re-render. i18next itself is mocked
-// so the tests observe the wiring rather than i18next's own behaviour.
-
-interface FakeI18n {
-	readonly instance: i18n;
-	readonly handlers: Map<string, Set<() => void>>;
-	isInitialized: boolean;
-	loadedNamespaces: string[];
-	translations: Record<string, string>;
-}
-
-const fakeI18n = (): FakeI18n => {
-	const handlers = new Map<string, Set<() => void>>();
-	const fake: FakeI18n = {
-		handlers,
-		isInitialized: true,
-		loadedNamespaces: ["translation"],
-		translations: {},
-		instance: {
-			t: (key: string): string => fake.translations[key] ?? key,
-			get isInitialized(): boolean {
-				return fake.isInitialized;
-			},
-			hasLoadedNamespace: (namespace: string): boolean =>
-				fake.loadedNamespaces.includes(namespace),
-			on: (event: string, listener: () => void): void => {
-				const existing = handlers.get(event) ?? new Set<() => void>();
-				existing.add(listener);
-				handlers.set(event, existing);
-			},
-			off: (event: string, listener: () => void): void => {
-				handlers.get(event)?.delete(listener);
-			},
-		} as unknown as i18n,
-	};
-	return fake;
-};
-
-const emit = (fake: FakeI18n, event: string): void => {
-	for (const listener of fake.handlers.get(event) ?? []) {
-		listener();
-	}
-};
-
-const load = async (): Promise<{
-	createTranslator: (existing?: i18n) => Translator;
-	packageInstance: i18n;
-	initCount: () => number;
-}> => {
-	vi.resetModules();
-
-	const packageInstance = fakeI18n().instance;
-	let initCalls = 0;
-
-	vi.doMock("../i18nFrontend.js", () => ({
-		default: (): i18n => {
-			initCalls += 1;
-			return packageInstance;
-		},
-	}));
-
-	const imported = await import("../translator.js");
-	return {
-		createTranslator: imported.createTranslator,
-		packageInstance,
-		initCount: (): number => initCalls,
-	};
-};
-
-afterEach(() => {
-	vi.resetModules();
-	vi.doUnmock("../i18nFrontend.js");
-});
-
-describe("which i18next instance the translator talks to", () => {
-	test("initialises the package's own instance when given none", async () => {
-		// Without this, a host application running its own i18next would capture
-		// the widget's translations and render its keys instead.
-		const { createTranslator, packageInstance, initCount } = await load();
-
-		const translator = createTranslator();
-
-		expect(translator.i18n).toBe(packageInstance);
-		expect(initCount()).toBe(1);
-	});
-
-	test("adopts an instance the caller already has", async () => {
-		// The bundle loads i18next once and hands the same instance to every
-		// widget on the page, so a second init would be wasted work.
-		const { createTranslator, initCount } = await load();
-		const existing = fakeI18n().instance;
-
-		const translator = createTranslator(existing);
-
-		expect(translator.i18n).toBe(existing);
-		expect(initCount()).toBe(0);
-	});
-});
-
-describe("translating", () => {
-	test("delegates to the instance", async () => {
-		const { createTranslator } = await load();
-		const fake = fakeI18n();
-		fake.translations = { "WIDGET.SUBMIT": "Submit" };
-
-		expect(createTranslator(fake.instance).t("WIDGET.SUBMIT")).toBe("Submit");
-	});
-
-	test("reads the instance at call time, not at creation time", async () => {
-		// A language switch mutates the instance in place; a translator that
-		// cached `t` would keep serving the previous language.
-		const { createTranslator } = await load();
-		const fake = fakeI18n();
-		const translator = createTranslator(fake.instance);
-
-		fake.translations = { "WIDGET.SUBMIT": "Envoyer" };
-
-		expect(translator.t("WIDGET.SUBMIT")).toBe("Envoyer");
-	});
-});
-
-describe("readiness", () => {
-	test("is ready once the instance has loaded the translation namespace", async () => {
-		const { createTranslator } = await load();
-		const fake = fakeI18n();
-
-		expect(createTranslator(fake.instance).isReady()).toBe(true);
-	});
-
-	test("is not ready before initialisation", async () => {
-		const { createTranslator } = await load();
-		const fake = fakeI18n();
-		fake.isInitialized = false;
-
-		expect(createTranslator(fake.instance).isReady()).toBe(false);
-	});
-
-	test("is not ready while the namespace is still loading", async () => {
-		// Widgets render an empty label until this flips, rather than flashing a
-		// raw translation key at the user.
-		const { createTranslator } = await load();
-		const fake = fakeI18n();
-		fake.loadedNamespaces = [];
-
-		expect(createTranslator(fake.instance).isReady()).toBe(false);
-	});
-});
-
-describe("subscribing", () => {
-	test.each(["initialized", "loaded", "languageChanged"])(
-		"notifies the listener on %s",
-		async (event: string) => {
-			const { createTranslator } = await load();
-			const fake = fakeI18n();
-			const listener = vi.fn<() => void>();
-
-			createTranslator(fake.instance).subscribe(listener);
-			emit(fake, event);
-
-			expect(listener).toHaveBeenCalledTimes(1);
-		},
-	);
-
-	test("stops notifying once unsubscribed", async () => {
-		// Widgets unsubscribe on destroy; a leaked listener would keep a torn-down
-		// widget alive for the lifetime of the page.
-		const { createTranslator } = await load();
-		const fake = fakeI18n();
-		const listener = vi.fn<() => void>();
-
-		const unsubscribe = createTranslator(fake.instance).subscribe(listener);
-		unsubscribe();
-		emit(fake, "languageChanged");
-
-		expect(listener).not.toHaveBeenCalled();
-	});
-
-	test("keeps independent subscriptions apart", async () => {
-		const { createTranslator } = await load();
-		const fake = fakeI18n();
-		const first = vi.fn<() => void>();
-		const second = vi.fn<() => void>();
-		const translator = createTranslator(fake.instance);
-
-		const unsubscribeFirst = translator.subscribe(first);
-		translator.subscribe(second);
-		unsubscribeFirst();
-		emit(fake, "loaded");
-
-		expect(first).not.toHaveBeenCalled();
-		expect(second).toHaveBeenCalledTimes(1);
-	});
-});

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

@@ -1,102 +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, 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

@@ -1,73 +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 translationEn from "./locales/en/translation.json" with { type: "json" };
-
-export type TranslationNode =
-	| {
-			[key: string]: TranslationNode | string;
-	  }
-	| 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 [];
-	}
-
-	return Object.keys(obj).reduce((arr, key) => {
-		const value = obj[key];
-		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 `translationKeys` empty. That list 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(
-			children.map((child) => {
-				return `${key}.${child}`;
-			}),
-		);
-	}, [] as string[]);
-}
-
-export const translationKeys: string[] = getLeafFieldPath(translationEn);
-
-type LeafPath<Node> = {
-	[Key in keyof Node & string]: Node[Key] extends string
-		? Key
-		: `${Key}.${LeafPath<Node[Key]>}`;
-}[keyof Node & string];
-
-/** A leaf path in the English catalogue, so a mistyped key fails to compile. */
-export type TranslationKey = LeafPath<typeof translationEn>;
-
-const translationKeySet: ReadonlySet<string> = new Set(translationKeys);
-
-/** For keys that only exist at runtime, e.g. an error message. */
-export const isTranslationKey = (value: string): value is TranslationKey =>
-	translationKeySet.has(value);

package/src/translations.ts

@@ -1,55 +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.
-
-export const Languages = {
-	arabic: "ar",
-	azerbaijani: "az",
-	czech: "cs",
-	german: "de",
-	greek: "el",
-	english: "en",
-	spanish: "es",
-	finnish: "fi",
-	french: "fr",
-	hindi: "hi",
-	hungarian: "hu",
-	indonesian: "id",
-	italian: "it",
-	japanese: "ja",
-	javanese: "jv",
-	korean: "ko",
-	malayalam: "ml",
-	malay: "ms",
-	dutch: "nl",
-	norwegian: "no",
-	polish: "pl",
-	portugeseBrazil: "pt-BR",
-	portuguese: "pt",
-	romanian: "ro",
-	russian: "ru",
-	serbian: "sr",
-	swedish: "sv",
-	thai: "th",
-	turkish: "tr",
-	ukrainian: "uk",
-	vietnamese: "vi",
-	chinese: "zh-CN",
-} as const;
-
-export type Language = (typeof Languages)[keyof typeof Languages];
-
-export const LanguageCodes: readonly string[] = Object.values(Languages);
-
-export const isLanguage = (value: string): value is Language =>
-	LanguageCodes.includes(value);

package/src/translator.ts

@@ -1,69 +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 initializeI18n from "./i18nFrontend.js";
-import type { TranslationKey } from "./translationKey.js";
-import type { Ti18n, TranslateOptions } from "./types.js";
-
-const NAMESPACE = "translation";
-
-export interface Translator {
-	/**
-	 * Translate a key against the current language. `options` carries
-	 * interpolation values and the `defaultValue` a widget falls back to when
-	 * its key has not been added to the bundled catalogues yet.
-	 */
-	t(key: TranslationKey, options?: TranslateOptions): string;
-	/**
-	 * Whether the namespace for the active language has finished loading.
-	 * Mirrors `ready` from the old react-i18next hook: widgets render an empty
-	 * label until it flips, rather than flashing a raw translation key.
-	 */
-	isReady(): boolean;
-	/**
-	 * Notified when the translation output could have changed — initialisation,
-	 * a namespace load, or a language switch. Returns an unsubscribe function.
-	 */
-	subscribe(listener: () => void): () => void;
-	readonly i18n: Ti18n;
-}
-
-/**
- * Vanilla replacement for the `useTranslation` hook: the instance's `t` plus
- * the three events that used to trigger a React re-render.
- */
-export const createTranslator = (existing?: Ti18n): Translator => {
-	const i18n: Ti18n = existing ?? initializeI18n();
-
-	const isReady = (): boolean =>
-		i18n.isInitialized && i18n.hasLoadedNamespace(NAMESPACE);
-
-	return {
-		t: (key: TranslationKey, options?: TranslateOptions): string =>
-			i18n.t(key, options),
-		isReady,
-		i18n,
-		subscribe: (listener: () => void): (() => void) => {
-			const events = ["initialized", "loaded", "languageChanged"] as const;
-			for (const event of events) {
-				i18n.on(event, listener);
-			}
-			return () => {
-				for (const event of events) {
-					i18n.off(event, listener);
-				}
-			};
-		},
-	};
-};

package/src/types.ts

@@ -1,47 +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 { TranslationKey } from "./translationKey.js";
-
-/**
- * Interpolation values, plus the `defaultValue` a caller falls back to when its
- * key is not in the catalogue. Values are substituted into `{{name}}`
- * placeholders.
- */
-export interface TranslateOptions {
-	defaultValue?: string;
-	[value: string]: unknown;
-}
-
-export type TranslateFn = (
-	key: TranslationKey,
-	options?: TranslateOptions,
-) => string;
-
-export type I18nEvent = "initialized" | "loaded" | "languageChanged";
-
-/**
- * The slice of an i18n instance this repository uses. Both implementations
- * satisfy it: the browser one in `i18nFrontend.ts`, and i18next itself on the
- * server, where `i18next-http-middleware` needs the real thing.
- */
-export interface Ti18n {
-	readonly language: string;
-	readonly isInitialized: boolean;
-	t: TranslateFn;
-	changeLanguage(language: string): Promise<unknown>;
-	hasLoadedNamespace(namespace: string): boolean;
-	on(event: I18nEvent, listener: () => void): void;
-	off(event: I18nEvent, listener: () => void): void;
-}

package/src/util.ts

@@ -1,25 +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.
-
-export const isClientSide = (): boolean => {
-	return !!(
-		typeof window !== "undefined" &&
-		window.document &&
-		window.document.createElement
-	);
-};
-
-export const isServerSide = (): boolean => {
-	return !isClientSide();
-};

package/tsconfig.cjs.json

@@ -1,21 +0,0 @@
-{
-	"extends": "../../tsconfig.cjs.json",
-	"compilerOptions": {
-		"rootDir": "./src",
-		"outDir": "./dist/cjs"
-	},
-	"include": [
-		"./src/**/*.ts",
-		"./src/**/*.json",
-		"./src/**/*.d.ts",
-		"./src/**/*.tsx"
-	],
-	"references": [
-		{
-			"path": "../../dev/config/tsconfig.cjs.json"
-		},
-		{
-			"path": "../util/tsconfig.cjs.json"
-		}
-	]
-}

package/tsconfig.json

@@ -1,22 +0,0 @@
-{
-	"extends": "../../tsconfig.esm.json",
-	"compilerOptions": {
-		"rootDir": "./src",
-		"outDir": "./dist"
-	},
-	"include": [
-		"src",
-		"src/**/*.json",
-		"src/**/*.ts",
-		"src/**/*.tsx",
-		"src/**/*.d.ts"
-	],
-	"references": [
-		{
-			"path": "../../dev/config/tsconfig.json"
-		},
-		{
-			"path": "../util"
-		}
-	]
-}