@prosopo/locale 3.5.0 → 3.6.0

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

@@ -25,6 +25,8 @@ interface Harness {
 	instance: i18n;
 	handleCalls: [i18n, HandleOptions | undefined][];
 	handler: Handler;
+	/** True once loadI18next has resolved — handle() must not run before then. */
+	loaded: () => boolean;
 }
 
 const load = async (options: {
@@ -38,6 +40,11 @@ const load = async (options: {
 	const instance = asI18n({ name: "the singleton" });
 	const handleCalls: [i18n, HandleOptions | undefined][] = [];
 	const handler = ((): void => {}) as unknown as Handler;
+	let loaded = false;
+
+	// The middleware takes the i18next singleton directly: handle() needs the
+	// real instance, not the narrow Ti18n loadI18next hands back.
+	vi.doMock("i18next", () => ({ default: instance }));
 
 	vi.doMock("i18next-http-middleware", () => ({
 		handle: (i18next: i18n, opts?: HandleOptions): Handler => {
@@ -50,6 +57,7 @@ const load = async (options: {
 			if (options.loadRejects) {
 				throw new Error("i18n failed to load");
 			}
+			loaded = true;
 			return instance;
 		},
 	}));
@@ -57,7 +65,7 @@ const load = async (options: {
 	const imported = await import("../i18nMiddleware.js");
 	return {
 		i18nMiddleware: imported.default,
-		harness: { instance, handleCalls, handler },
+		harness: { instance, handleCalls, handler, loaded: (): boolean => loaded },
 	};
 };
 
@@ -65,10 +73,11 @@ afterEach(() => {
 	vi.resetModules();
 	vi.doUnmock("i18next-http-middleware");
 	vi.doUnmock("../loadI18next.js");
+	vi.doUnmock("i18next");
 });
 
 describe("i18nMiddleware", () => {
-	test("builds the handler from the loaded i18next instance", async () => {
+	test("builds the handler from the i18next singleton", async () => {
 		const { i18nMiddleware, harness } = await load({});
 
 		const handler = await i18nMiddleware({});
@@ -78,6 +87,16 @@ describe("i18nMiddleware", () => {
 		expect(handler).toBe(harness.handler);
 	});
 
+	test("waits for the resources before handing the instance over", async () => {
+		// handle() reads the instance's language list when it is built, so an
+		// uninitialised singleton would produce a middleware that detects nothing.
+		const { i18nMiddleware, harness } = await load({});
+
+		await i18nMiddleware({});
+
+		expect(harness.loaded()).toBe(true);
+	});
+
 	test("forwards the caller's options", async () => {
 		const { i18nMiddleware, harness } = await load({});
 		const options: HandleOptions = { ignoreRoutes: ["/healthz"] };

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

@@ -12,27 +12,27 @@
 // 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 { Ti18n } from "../types.js";
 
 // loadI18next keeps a module-level singleton, so every test re-imports it
-// under a fresh registry. The two i18n implementations are mocked out: they
-// pull in i18next, its plugins and the filesystem, none of which this module's
-// own logic depends on.
+// under a fresh registry. The two i18n implementations are mocked out: one
+// fetches catalogues over the network, the other pulls in i18next and the
+// filesystem, and neither is what this module's own logic does.
 
-/** The slice of the i18next instance loadI18next actually touches. */
+/** The slice of an i18n instance loadI18next actually touches. */
 interface FakeI18n {
 	language: string;
 	changeLanguage: (lng: string) => Promise<unknown>;
 }
 
 /** One cast, confined here, so the mocked module keeps the real signature. */
-const asI18n = (fake: FakeI18n): i18n => fake as unknown as i18n;
+const asI18n = (fake: FakeI18n): Ti18n => fake as unknown as Ti18n;
 
 type InitializeI18n = (
-	callback?: (instance: i18n) => void,
+	callback?: (instance: Ti18n) => void,
 	lng?: string,
-) => i18n;
+) => Ti18n;
 
 interface Harness {
 	instance: FakeI18n;
@@ -79,7 +79,7 @@ const install = (
 };
 
 const loadModule = async (): Promise<
-	(backend: boolean, lng?: string) => Promise<i18n>
+	(backend: boolean, lng?: string) => Promise<Ti18n>
 > => {
 	const imported = await import("../loadI18next.js");
 	return imported.default;
@@ -352,7 +352,7 @@ describe("loadI18next, timeout", () => {
 		// Without the one-shot latch a later emission would call resolve again
 		// and leave the timer armed.
 		vi.useFakeTimers();
-		let fire: ((instance: i18n) => void) | undefined;
+		let fire: ((instance: Ti18n) => void) | undefined;
 		const instance: FakeI18n = {
 			language: "en",
 			changeLanguage: async (): Promise<unknown> => undefined,
@@ -382,7 +382,7 @@ describe("loadI18next, timeout", () => {
 		// the degraded instance. Calling reject then would produce an unhandled
 		// rejection on an already-settled promise.
 		vi.useFakeTimers();
-		let fire: ((instance: i18n) => void) | undefined;
+		let fire: ((instance: Ti18n) => void) | undefined;
 		const instance: FakeI18n = {
 			language: "en",
 			changeLanguage: async (): Promise<unknown> => {

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

@@ -18,22 +18,24 @@
 
 import { assertType, describe, expectTypeOf, it } from "vitest";
 import {
-	LanguageSchema,
+	type Language,
+	LanguageCodes,
 	Languages,
 	type Ti18n,
 	type TranslationKey,
-	TranslationKeysSchema,
 	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 LanguageSchema derive its enum. Widening this
-		// to Record<string, string> would silently turn the schema into a
-		// runtime-only constraint.
+		// `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">();
 	});
@@ -49,28 +51,24 @@ describe("Languages", () => {
 	});
 });
 
-describe("LanguageSchema", () => {
-	it("parses to a string", () => {
-		// The enum is built from a runtime `Object.values` cast, so the parsed
-		// type is string rather than the union of codes. Pinned deliberately:
-		// a consumer must not assume narrowing it does not get.
-		expectTypeOf(LanguageSchema.parse("en")).toEqualTypeOf<string>();
+describe("isLanguage", () => {
+	it("narrows an arbitrary string to a declared code", () => {
+		expectTypeOf(isLanguage).guards.toEqualTypeOf<Language>();
 	});
 
-	it("exposes .enum as a lookup of codes", () => {
-		expectTypeOf(LanguageSchema.enum).toExtend<Record<string, string>>();
+	it("accepts any string at the boundary — input is untrusted markup", () => {
+		expectTypeOf(isLanguage).toBeCallableWith("anything");
 	});
 
-	it("accepts unknown input at the parse boundary", () => {
-		expectTypeOf(LanguageSchema.parse).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 inferred from the schema", () => {
-		expectTypeOf<TranslationKey>().toEqualTypeOf<
-			ReturnType<typeof TranslationKeysSchema.parse>
-		>();
+	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", () => {
@@ -79,10 +77,13 @@ describe("TranslationKey", () => {
 		assertType<TranslationKey>("API.UNKNOWN");
 	});
 
-	it("exposes the derived keys as an array of options", () => {
-		// A non-empty tuple, which is what z.enum requires and what the mongoose
-		// schemas in types-database spread into their `enum` fields.
-		expectTypeOf(TranslationKeysSchema.options).toExtend<readonly string[]>();
+	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[]>();
 	});
 });
 

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

@@ -17,9 +17,9 @@ import translationEn from "../locales/en/translation.json" with {
 	type: "json",
 };
 import {
-	TranslationKeysSchema,
 	type TranslationNode,
 	getLeafFieldPath,
+	translationKeys,
 } from "../translationKey.js";
 
 describe("getLeafFieldPath", () => {
@@ -34,7 +34,7 @@ describe("getLeafFieldPath", () => {
 	// 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.
+	// input and left `translationKeys` empty.
 	test("emits a top-level string value under its own key", () => {
 		expect(getLeafFieldPath({ topLevel: "value" })).toEqual(["topLevel"]);
 	});
@@ -112,55 +112,29 @@ describe("getLeafFieldPath", () => {
 	});
 });
 
-describe("TranslationKeysSchema", () => {
+describe("translationKeys", () => {
 	const keys = getLeafFieldPath(translationEn as TranslationNode);
 
-	test("is non-empty — an empty z.enum would throw at module load", () => {
+	test("is non-empty — mongoose validates against an empty enum too", () => {
 		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("is exactly the set of keys derived from the English translation", () => {
+		expect(new Set(translationKeys)).toEqual(new Set(keys));
 	});
 
-	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", () => {
+	test("holds leaves, not section names", () => {
 		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);
+		expect(translationKeys).not.toContain(section);
 	});
 
-	test("is case sensitive", () => {
-		const [firstKey] = keys;
-		expect(firstKey).toBeDefined();
-		const upper = String(firstKey).toUpperCase();
-		if (upper !== firstKey) {
-			expect(() => TranslationKeysSchema.parse(upper)).toThrow();
-		}
+	test("does not contain a key absent from the English translation", () => {
+		expect(translationKeys).not.toContain("no.such.key");
 	});
 
-	test("exposes exactly the derived keys as enum options", () => {
-		expect(new Set(TranslationKeysSchema.options)).toEqual(new Set(keys));
+	test("does not contain the empty string", () => {
+		expect(translationKeys).not.toContain("");
 	});
 });

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

@@ -15,7 +15,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { describe, expect, test } from "vitest";
-import { LanguageSchema, Languages } from "../translations.js";
+import { LanguageCodes, Languages, isLanguage } from "../translations.js";
 
 const codes: string[] = Object.values(Languages);
 
@@ -34,9 +34,8 @@ describe("Languages", () => {
 		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.
+	// 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);
 	});
@@ -62,49 +61,37 @@ describe("Languages", () => {
 	});
 });
 
-describe("LanguageSchema", () => {
+describe("isLanguage", () => {
 	test("accepts every declared code", () => {
 		for (const code of codes) {
-			expect(LanguageSchema.parse(code)).toBe(code);
+			expect(isLanguage(code)).toBe(true);
 		}
 	});
 
-	test("exposes each code on .enum for use as a constant", () => {
-		expect(LanguageSchema.enum.en).toBe("en");
+	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(() => LanguageSchema.parse("xx")).toThrow();
+		expect(isLanguage("xx")).toBe(false);
 	});
 
 	test("rejects the empty string", () => {
-		expect(() => LanguageSchema.parse("")).toThrow();
+		expect(isLanguage("")).toBe(false);
 	});
 
-	// 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.
+	// 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(() => LanguageSchema.parse("en-GB")).toThrow();
+		expect(isLanguage("en-GB")).toBe(false);
 	});
 
 	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));
+		expect(isLanguage("EN")).toBe(false);
 	});
 });

package/src/translationKey.ts

@@ -12,7 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import { z } from "zod";
 import translationEn from "./locales/en/translation.json" with { type: "json" };
 
 export type TranslationNode =
@@ -38,10 +37,10 @@ export function getLeafFieldPath(obj: TranslationNode): string[] {
 		// 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.
+		// 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);
 		}
@@ -56,8 +55,10 @@ export function getLeafFieldPath(obj: TranslationNode): string[] {
 	}, [] as string[]);
 }
 
-export const TranslationKeysSchema = z.enum(
-	getLeafFieldPath(translationEn) as [string, ...string[]],
-);
+export const translationKeys: string[] = getLeafFieldPath(translationEn);
 
-export type TranslationKey = z.infer<typeof TranslationKeysSchema>;
+/**
+ * Any leaf path in the English catalogue. Not narrowed to those paths: they are
+ * read from JSON at runtime, so the compiler only ever knew them as `string`.
+ */
+export type TranslationKey = string;

package/src/translations.ts

@@ -12,8 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import z from "zod";
-
 export const Languages = {
 	arabic: "ar",
 	azerbaijani: "az",
@@ -49,6 +47,9 @@ export const Languages = {
 	chinese: "zh-CN",
 } as const;
 
-export const LanguageSchema = z.enum(
-	Object.values(Languages) as [string, ...string[]],
-);
+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

@@ -12,9 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import type { TOptions } from "i18next";
 import initializeI18n from "./i18nFrontend.js";
-import type { Ti18n } from "./loadI18next.js";
+import type { Ti18n, TranslateOptions } from "./types.js";
 
 const NAMESPACE = "translation";
 
@@ -24,7 +23,7 @@ export interface Translator {
 	 * interpolation values and the `defaultValue` a widget falls back to when
 	 * its key has not been added to the bundled catalogues yet.
 	 */
-	t(key: string, options?: TOptions): string;
+	t(key: string, 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
@@ -40,9 +39,8 @@ export interface Translator {
 }
 
 /**
- * Vanilla replacement for the `useTranslation` hook. i18next is already
- * framework-agnostic and event-driven; this just exposes its `t` plus the three
- * events that used to trigger a React re-render.
+ * 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();
@@ -51,7 +49,8 @@ export const createTranslator = (existing?: Ti18n): Translator => {
 		i18n.isInitialized && i18n.hasLoadedNamespace(NAMESPACE);
 
 	return {
-		t: (key: string, options?: TOptions): string => i18n.t(key, options),
+		t: (key: string, options?: TranslateOptions): string =>
+			i18n.t(key, options),
 		isReady,
 		i18n,
 		subscribe: (listener: () => void): (() => void) => {

package/src/types.ts

@@ -0,0 +1,42 @@
+// 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.
+
+/**
+ * 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: string, 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/tsconfig.cjs.json

@@ -13,6 +13,9 @@
 	"references": [
 		{
 			"path": "../../dev/config/tsconfig.cjs.json"
+		},
+		{
+			"path": "../util/tsconfig.cjs.json"
 		}
 	]
 }

package/tsconfig.json

@@ -14,6 +14,9 @@
 	"references": [
 		{
 			"path": "../../dev/config/tsconfig.json"
+		},
+		{
+			"path": "../util"
 		}
 	]
 }