@prosopo/locale 3.6.1 → 3.7.0

package/src/tests/locale.test-d.ts

@@ -1,160 +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.
-
-// Asserted against the package entrypoint, which is what consumers import — a
-// barrel that stops re-exporting something fails here rather than at a
-// downstream build.
-
-import { assertType, describe, expectTypeOf, it } from "vitest";
-import {
-	type Language,
-	LanguageCodes,
-	Languages,
-	type Ti18n,
-	type TranslationKey,
-	createTranslator,
-	i18nMiddleware,
-	isClientSide,
-	isLanguage,
-	loadI18next,
-	translationKeys,
-} from "../index.js";
-
-describe("Languages", () => {
-	it("is a frozen const map of name to code, not a widened record", () => {
-		// `as const` is what lets `Language` be the union of the codes.
-		// Widening this to Record<string, string> would silently reduce it to
-		// `string`.
-		expectTypeOf(Languages.english).toEqualTypeOf<"en">();
-		expectTypeOf(Languages.chinese).toEqualTypeOf<"zh-CN">();
-	});
-
-	it("rejects assignment to a code", () => {
-		// @ts-expect-error Languages is const
-		Languages.english = "fr";
-	});
-
-	it("has no member for a language that is not shipped", () => {
-		// @ts-expect-error klingon is not a supported language
-		Languages.klingon;
-	});
-});
-
-describe("isLanguage", () => {
-	it("narrows an arbitrary string to a declared code", () => {
-		expectTypeOf(isLanguage).guards.toEqualTypeOf<Language>();
-	});
-
-	it("accepts any string at the boundary — input is untrusted markup", () => {
-		expectTypeOf(isLanguage).toBeCallableWith("anything");
-	});
-
-	it("is the union of the declared codes, not a widened string", () => {
-		expectTypeOf<Language>().toExtend<string>();
-		assertType<Language>("en");
-	});
-});
-
-describe("TranslationKey", () => {
-	it("is a plain string — keys are read from JSON, never narrowed", () => {
-		expectTypeOf<TranslationKey>().toEqualTypeOf<string>();
-	});
-
-	it("accepts a key literal, so error call sites need no cast", () => {
-		// packages/common's ProsopoError takes TranslationKey and is called
-		// with literals throughout.
-		assertType<TranslationKey>("API.UNKNOWN");
-	});
-
-	it("exposes the derived keys as an array", () => {
-		// What the mongoose schemas in types-database put in their `enum` fields.
-		expectTypeOf(translationKeys).toExtend<readonly string[]>();
-	});
-
-	it("exposes the declared language codes as an array", () => {
-		expectTypeOf(LanguageCodes).toExtend<readonly string[]>();
-	});
-});
-
-describe("isClientSide", () => {
-	it("takes no arguments and returns a boolean", () => {
-		expectTypeOf(isClientSide).parameters.toEqualTypeOf<[]>();
-		expectTypeOf(isClientSide).returns.toEqualTypeOf<boolean>();
-	});
-});
-
-describe("loadI18next", () => {
-	it("requires the backend flag", () => {
-		expectTypeOf(loadI18next).toBeCallableWith(true);
-		expectTypeOf(loadI18next).toBeCallableWith(false, "fr");
-	});
-
-	it("rejects a call with no arguments", () => {
-		// @ts-expect-error the backend flag is required
-		loadI18next();
-	});
-
-	it("rejects a non-boolean first argument", () => {
-		// Catches the easy mistake of passing the language positionally.
-		// @ts-expect-error the first parameter is the backend flag
-		loadI18next("fr");
-	});
-
-	it("resolves to the i18next instance type the package re-exports", () => {
-		expectTypeOf(loadI18next).returns.toEqualTypeOf<Promise<Ti18n>>();
-	});
-});
-
-describe("Ti18n", () => {
-	it("carries the i18next surface consumers need", () => {
-		expectTypeOf<Ti18n>().toHaveProperty("t");
-		expectTypeOf<Ti18n>().toHaveProperty("language");
-		expectTypeOf<Ti18n>().toHaveProperty("changeLanguage");
-	});
-});
-
-describe("i18nMiddleware", () => {
-	it("takes handler options and resolves to an express handler", () => {
-		expectTypeOf(i18nMiddleware).toBeCallableWith({});
-		expectTypeOf(i18nMiddleware).returns.toExtend<Promise<unknown>>();
-	});
-
-	it("rejects an unknown option", () => {
-		// @ts-expect-error notAnOption is not part of HandleOptions
-		i18nMiddleware({ notAnOption: true });
-	});
-
-	it("rejects being called with no options", () => {
-		// @ts-expect-error options are required
-		i18nMiddleware();
-	});
-});
-
-describe("createTranslator", () => {
-	it("is callable with no instance, so a standalone widget can boot one", () => {
-		expectTypeOf(createTranslator).toBeCallableWith();
-	});
-
-	it("returns the translator surface the widgets render against", () => {
-		expectTypeOf(createTranslator).returns.toHaveProperty("t");
-		expectTypeOf(createTranslator).returns.toHaveProperty("isReady");
-		expectTypeOf(createTranslator).returns.toHaveProperty("subscribe");
-		expectTypeOf(createTranslator).returns.toHaveProperty("i18n");
-	});
-
-	it("rejects anything that is not an i18next instance", () => {
-		// @ts-expect-error the only parameter is an existing i18next instance
-		createTranslator({ notAnInstance: 1 });
-	});
-});

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

@@ -1,81 +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 fs from "node:fs";
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { Languages } from "../index.js";
-
-type TranslationTree = { [key: string]: string | TranslationTree };
-
-const readLocale = (locale: string): TranslationTree =>
-	JSON.parse(
-		fs.readFileSync(
-			path.resolve(`./src/locales/${locale}/translation.json`),
-			"utf8",
-		),
-	);
-
-const flatten = (tree: TranslationTree, prefix = ""): Array<[string, string]> =>
-	Object.entries(tree).flatMap(
-		([key, value]): Array<[string, string]> =>
-			typeof value === "string"
-				? [[`${prefix}${key}`, value]]
-				: flatten(value, `${prefix}${key}.`),
-	);
-
-const placeholders = (text: string): string[] =>
-	(text.match(/\{\{[^}]*\}\}/g) ?? [])
-		.map((token: string) => token.replace(/\s+/g, ""))
-		.sort();
-
-const en = new Map<string, string>(flatten(readLocale("en")));
-const locales: string[] = Object.values(Languages).filter(
-	(locale: string) => locale !== "en",
-);
-
-describe("locale interpolation placeholders", () => {
-	it.each(locales)(
-		"%s keeps every {{placeholder}} of the en source",
-		(locale: string) => {
-			const mismatches: string[] = flatten(readLocale(locale))
-				.filter(
-					([key, value]: [string, string]) =>
-						en.has(key) &&
-						placeholders(value).join() !==
-							placeholders(en.get(key) ?? "").join(),
-				)
-				.map(([key, value]: [string, string]) => `${key}: ${value}`);
-			expect(mismatches).toEqual([]);
-		},
-	);
-});
-
-// A tool once stripped every Devanagari vowel sign and virama from the Hindi
-// file ("मैं मनुष्य हूँ" became "म मनषय ह"), which the key and placeholder
-// checks cannot see.
-describe("hi translations", () => {
-	it("keep their Devanagari vowel signs", () => {
-		const devanagariLetter = /[ऄ-हक़-ॡ]/gu;
-		const sign = /[ऀ-ःऺ-ॏॕ-ॗॢॣ]/u;
-		const stripped: string[] = flatten(readLocale("hi"))
-			.filter(
-				([, value]: [string, string]) =>
-					(value.match(devanagariLetter) ?? []).length >= 4 &&
-					!sign.test(value),
-			)
-			.map(([key, value]: [string, string]) => `${key}: ${value}`);
-		expect(stripped).toEqual([]);
-	});
-});

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

@@ -1,79 +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 fs from "node:fs";
-import path from "node:path";
-import { describe, expect, test } from "vitest";
-import { Languages } from "../index.js";
-
-describe("logging", () => {
-	test("Make sure the number of files present in the locales folder is the same size as the Languages array", () => {
-		const locales = fs.readdirSync(path.resolve("./src/locales"));
-		expect(locales.length).to.equal(Object.keys(Languages).length);
-	});
-
-	test("Get all locale JSON files and ensure the keys are identical in each one", () => {
-		const locales = Object.values(Languages);
-		const sectionKeys = new Set<string>();
-		console.log("Local test running at ", path.resolve("."));
-		const sectionKeysObj: { [key: string]: Set<string> } = {};
-		const innerKeysObj: { [key: string]: { [key: string]: Set<string> } } = {};
-		for (const locale of locales) {
-			const localeData = fs.readFileSync(
-				path.resolve(`./src/locales/${locale}/translation.json`),
-				"utf8",
-			);
-			const localeKeys = Object.keys(JSON.parse(localeData));
-			for (const sectionKey of localeKeys) {
-				sectionKeys.add(sectionKey);
-			}
-			sectionKeysObj[locale] = new Set(localeKeys);
-			for (const sectionKey of localeKeys) {
-				const innerKeys = JSON.parse(localeData)[sectionKey];
-				if (typeof innerKeys !== "object") {
-					continue;
-				}
-
-				if (!innerKeysObj[locale]) {
-					innerKeysObj[locale] = {};
-				}
-
-				// @ts-ignore
-				if (!innerKeysObj[locale][sectionKey]) {
-					// @ts-ignore
-					innerKeysObj[locale][sectionKey] = new Set();
-				}
-
-				for (const innerKey of Object.keys(innerKeys)) {
-					// @ts-ignore
-					innerKeysObj[locale][sectionKey].add(innerKey);
-				}
-			}
-		}
-
-		for (const locale of Array.from(locales)) {
-			console.log("Checking", locale);
-			expect(sectionKeysObj[locale]).to.deep.equal(sectionKeysObj.en);
-			// @ts-ignore
-			for (const sectionKey of Object.keys(innerKeysObj[locale])) {
-				console.log(`Checking ${locale} ${sectionKey}`);
-				// @ts-ignore
-				expect(innerKeysObj[locale][sectionKey]).to.deep.equal(
-					// @ts-ignore
-					innerKeysObj.en[sectionKey],
-				);
-			}
-		}
-	});
-});

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

@@ -1,33 +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 { describe, expect, test } from "vitest";
-import { getProcess } from "../process.js";
-
-describe("getProcess", () => {
-	// Under vitest there is always a real `process`, so only this arm is
-	// directly observable here. The undefined arm is what consumers mock, and
-	// i18SharedOptions.unit.test.ts exercises their behaviour against it.
-	test("returns the process global when one exists", () => {
-		expect(getProcess()).toBe(process);
-	});
-
-	test("exposes env, which is the only member consumers use", () => {
-		expect(getProcess()?.env).toBe(process.env);
-	});
-
-	test("is stable across calls rather than returning a copy", () => {
-		expect(getProcess()).toBe(getProcess());
-	});
-});

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

@@ -1,140 +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 { describe, expect, test } from "vitest";
-import translationEn from "../locales/en/translation.json" with {
-	type: "json",
-};
-import {
-	type TranslationNode,
-	getLeafFieldPath,
-	translationKeys,
-} 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 `translationKeys` empty.
-	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("translationKeys", () => {
-	const keys = getLeafFieldPath(translationEn as TranslationNode);
-
-	test("is non-empty — mongoose validates against an empty enum too", () => {
-		expect(keys.length).toBeGreaterThan(0);
-	});
-
-	test("is exactly the set of keys derived from the English translation", () => {
-		expect(new Set(translationKeys)).toEqual(new Set(keys));
-	});
-
-	test("holds leaves, not section names", () => {
-		const [firstKey] = keys;
-		expect(firstKey).toBeDefined();
-		const section = String(firstKey).split(".")[0];
-		expect(translationKeys).not.toContain(section);
-	});
-
-	test("does not contain a key absent from the English translation", () => {
-		expect(translationKeys).not.toContain("no.such.key");
-	});
-
-	test("does not contain the empty string", () => {
-		expect(translationKeys).not.toContain("");
-	});
-});

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

@@ -1,97 +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 fs from "node:fs";
-import path from "node:path";
-import { describe, expect, test } from "vitest";
-import { LanguageCodes, Languages, isLanguage } 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 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("isLanguage", () => {
-	test("accepts every declared code", () => {
-		for (const code of codes) {
-			expect(isLanguage(code)).toBe(true);
-		}
-	});
-
-	test("every declared code is in LanguageCodes", () => {
-		expect(new Set(LanguageCodes)).toEqual(new Set(codes));
-	});
-
-	test("exposes each code as a constant for use in code", () => {
-		expect(Languages.english).toBe("en");
-	});
-
-	test("rejects an undeclared language code", () => {
-		expect(isLanguage("xx")).toBe(false);
-	});
-
-	test("rejects the empty string", () => {
-		expect(isLanguage("")).toBe(false);
-	});
-
-	// i18next treated `en-GB` as a region of `en`, and the browser i18n resolves
-	// a regional tag to its base language before asking — so a regional variant
-	// is deliberately not itself a declared code.
-	test("rejects a regional variant of a supported language", () => {
-		expect(isLanguage("en-GB")).toBe(false);
-	});
-
-	test("is case sensitive — `EN` is not `en`", () => {
-		expect(isLanguage("EN")).toBe(false);
-	});
-});