@prosopo/locale 3.6.1 → 3.6.2

package/src/locales/vi/translation.json

@@ -10,7 +10,9 @@
 		"INVALID_SIGNATURE": "Chữ ký không hợp lệ",
 		"SITE_KEY_MISSING": "SITE KEY thiếu",
 		"ACCOUNT_NOT_FOUND": "Không tìm thấy tài khoản",
-		"INVALID_TIMESTAMP": "Thời điểm không hợp lệ"
+		"INVALID_TIMESTAMP": "Thời điểm không hợp lệ",
+		"MISSING_AUTH_HEADER": "Thiếu tiêu đề ủy quyền",
+		"INVALID_JWT": "JWT không hợp lệ"
 	},
 	"API": {
 		"INSUFFICIENT_PERMISSIONS": "Không đủ quyền để thực hiện hành động này",
@@ -54,7 +56,8 @@
 		"MOBILE_BLOCKED": "Các yêu cầu từ kết nối mạng di động không được phép cho trang web này",
 		"SATELLITE_BLOCKED": "Các yêu cầu từ kết nối vệ tinh không được phép cho trang web này",
 		"CRAWLER_BLOCKED": "Các yêu cầu từ trình thu thập dữ liệu đã biết không được phép cho trang web này",
-		"DISALLOWED_WEBVIEW": "Yêu cầu từ trình duyệt trong ứng dụng (WebView) không được phép cho trang web này"
+		"DISALLOWED_WEBVIEW": "Yêu cầu từ trình duyệt trong ứng dụng (WebView) không được phép cho trang web này",
+		"INTERNAL_SERVER_ERROR": "Lỗi máy chủ nội bộ"
 	},
 	"PORTAL": {
 		"CANNOT_MODIFY_OWNER_USER": "Không thể sửa đổi người dùng chủ sở hữu",
@@ -381,6 +384,11 @@
 		"INSECURE_CONTEXT": "Procaptcha yêu cầu kết nối an toàn (HTTPS)",
 		"CHECKING": "Đang xác minh bạn là người thật",
 		"IMAGE_DIALOG_LABEL": "Thử thách hình ảnh",
+		"CANNOT_LOAD": "Không thể tải CAPTCHA",
+		"RELOAD": "Tải lại",
+		"VERIFIED_AGENT": "Tác nhân đã xác minh",
+		"TRUSTED_REQUEST": "Yêu cầu đáng tin cậy",
+		"LOADING": "Đang tải",
 		"PUZZLE": {
 			"DIALOG_LABEL": "Thử thách ghép hình",
 			"DRAG": "Kéo mảnh ghép đến vị trí đích",
@@ -436,7 +444,13 @@
 		"TABLES_UNDEFINED": "Bảng chưa xác định",
 		"CONNECTION_UNDEFINED": "Kết nối không xác định",
 		"COMMITMENT_FLAG_FAILED": "Không thể đánh dấu cam kết là đã xử lý",
-		"UNKNOWN": "Lỗi cơ sở dữ liệu không xác định"
+		"UNKNOWN": "Lỗi cơ sở dữ liệu không xác định",
+		"QUERY_ERROR": "Truy vấn cơ sở dữ liệu thất bại",
+		"REDIS_ACCESS_RULES_CONNECTION_UNDEFINED": "Chưa xác định kết nối Redis cho quy tắc truy cập",
+		"USER_ACCESS_RULES_STORAGE_UNDEFINED": "Chưa xác định bộ lưu trữ quy tắc truy cập người dùng",
+		"SESSION_STORE_FAILED": "Không thể lưu phiên",
+		"SESSION_CHECK_REMOVE_FAILED": "Không thể kiểm tra và xóa phiên",
+		"SESSION_GET_FAILED": "Không thể lấy phiên"
 	},
 	"CAPTCHA": {
 		"PARSE_ERROR": "Lỗi phân tích captcha",
@@ -455,7 +469,10 @@
 		"INVALID_SALT": "Salt không hợp lệ",
 		"INVALID_TOKEN": "Token không hợp lệ",
 		"INVALID_SOLUTION": "Giải pháp không hợp lệ",
-		"DECRYPTION_ERROR": "Lỗi giải mã"
+		"DECRYPTION_ERROR": "Lỗi giải mã",
+		"SOLUTION_NOT_FOUND": "Không tìm thấy lời giải",
+		"DECISION_MACHINE_DENIED": "Bị máy quyết định từ chối",
+		"INVALID_TIMESTAMP": "Thời điểm không hợp lệ"
 	},
 	"CLI": {
 		"PARAMETER_ERROR": "Tham số không hợp lệ"

package/src/locales/zh-CN/translation.json

@@ -10,7 +10,9 @@
 		"INVALID_SIGNATURE": "无效的签名",
 		"SITE_KEY_MISSING": "缺少SITE KEY",
 		"ACCOUNT_NOT_FOUND": "找不到帐户",
-		"INVALID_TIMESTAMP": "无效的时间戳"
+		"INVALID_TIMESTAMP": "无效的时间戳",
+		"MISSING_AUTH_HEADER": "缺少授权标头",
+		"INVALID_JWT": "无效的 JWT"
 	},
 	"API": {
 		"INSUFFICIENT_PERMISSIONS": "权限不足，无法执行此操作",
@@ -54,7 +56,8 @@
 		"MOBILE_BLOCKED": "此网站不允许来自移动网络连接的请求",
 		"SATELLITE_BLOCKED": "此网站不允许来自卫星连接的请求",
 		"CRAWLER_BLOCKED": "此网站不允许来自已知爬虫的请求",
-		"DISALLOWED_WEBVIEW": "此站点不允许来自应用内浏览器 (WebView) 的请求"
+		"DISALLOWED_WEBVIEW": "此站点不允许来自应用内浏览器 (WebView) 的请求",
+		"INTERNAL_SERVER_ERROR": "服务器内部错误"
 	},
 	"PORTAL": {
 		"CANNOT_MODIFY_OWNER_USER": "无法修改所有者用户",
@@ -381,6 +384,11 @@
 		"INSECURE_CONTEXT": "Procaptcha 需要安全连接 (HTTPS)",
 		"CHECKING": "正在验证您是真人",
 		"IMAGE_DIALOG_LABEL": "图片验证",
+		"CANNOT_LOAD": "无法加载验证码",
+		"RELOAD": "重新加载",
+		"VERIFIED_AGENT": "已验证的代理",
+		"TRUSTED_REQUEST": "受信任的请求",
+		"LOADING": "加载中",
 		"PUZZLE": {
 			"DIALOG_LABEL": "拼图验证",
 			"DRAG": "将拼块拖到目标位置",
@@ -436,7 +444,13 @@
 		"TABLES_UNDEFINED": "未定义表",
 		"CONNECTION_UNDEFINED": "连接未定义",
 		"COMMITMENT_FLAG_FAILED": "标记承诺为已处理失败",
-		"UNKNOWN": "未知数据库错误"
+		"UNKNOWN": "未知数据库错误",
+		"QUERY_ERROR": "数据库查询失败",
+		"REDIS_ACCESS_RULES_CONNECTION_UNDEFINED": "访问规则的 Redis 连接未定义",
+		"USER_ACCESS_RULES_STORAGE_UNDEFINED": "用户访问规则存储未定义",
+		"SESSION_STORE_FAILED": "存储会话失败",
+		"SESSION_CHECK_REMOVE_FAILED": "检查并移除会话失败",
+		"SESSION_GET_FAILED": "获取会话失败"
 	},
 	"CAPTCHA": {
 		"PARSE_ERROR": "解析验证码时出错",
@@ -455,7 +469,10 @@
 		"INVALID_SALT": "盐值无效",
 		"INVALID_TOKEN": "无效的令牌",
 		"INVALID_SOLUTION": "无效的解决方案",
-		"DECRYPTION_ERROR": "解密错误"
+		"DECRYPTION_ERROR": "解密错误",
+		"SOLUTION_NOT_FOUND": "未找到解答",
+		"DECISION_MACHINE_DENIED": "被决策机拒绝",
+		"INVALID_TIMESTAMP": "无效的时间戳"
 	},
 	"CLI": {
 		"PARAMETER_ERROR": "无效的参数"

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

@@ -0,0 +1,52 @@
+// 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 { getLanguageDirection } from "../direction.js";
+import { LanguageCodes } from "../translations.js";
+
+describe("getLanguageDirection", () => {
+	test("is rtl for Arabic", () => {
+		expect(getLanguageDirection("ar")).toBe("rtl");
+	});
+
+	test("is rtl for regional and differently-cased Arabic tags", () => {
+		expect(getLanguageDirection("ar-EG")).toBe("rtl");
+		expect(getLanguageDirection("AR_sa")).toBe("rtl");
+	});
+
+	test("is rtl for other right-to-left scripts", () => {
+		for (const language of ["he", "fa", "ur", "yi"]) {
+			expect(getLanguageDirection(language)).toBe("rtl");
+		}
+	});
+
+	test("is ltr for every other shipped language", () => {
+		const others: string[] = LanguageCodes.filter(
+			(code: string) => code !== "ar",
+		);
+		for (const language of others) {
+			expect(getLanguageDirection(language)).toBe("ltr");
+		}
+	});
+
+	test("is ltr for an empty or unknown tag", () => {
+		expect(getLanguageDirection("")).toBe("ltr");
+		expect(getLanguageDirection("xx")).toBe("ltr");
+	});
+
+	test("matches only the primary subtag", () => {
+		expect(getLanguageDirection("en-AR")).toBe("ltr");
+	});
+});

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

@@ -0,0 +1,84 @@
+// 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 { flatten } from "@prosopo/util";
+import { describe, expect, test } from "vitest";
+import { localiseErrorMessage } from "../errorMessage.js";
+import de from "../locales/de/translation.json" with { type: "json" };
+import type { Ti18n, TranslateOptions } from "../types.js";
+
+// Same lookup order as the browser instance in i18nFrontend.ts: the active
+// catalogue, then the caller's defaultValue, then the key.
+const i18nIn = (
+	catalogue: Record<string, unknown>,
+	isInitialized = true,
+): Ti18n => {
+	const flat: Record<string, string> = flatten(catalogue);
+	return {
+		language: "de",
+		isInitialized,
+		t: (key: string, options?: TranslateOptions): string =>
+			flat[key] ?? options?.defaultValue ?? key,
+		changeLanguage: async (): Promise<void> => undefined,
+		hasLoadedNamespace: (): boolean => isInitialized,
+		on: (): void => undefined,
+		off: (): void => undefined,
+	};
+};
+
+const germanI18n = (): Ti18n => i18nIn(de);
+
+describe("localiseErrorMessage", () => {
+	test("translates a catalogue key into the widget's language, not the server's", () => {
+		const i18n = germanI18n();
+		expect(
+			localiseErrorMessage(i18n, {
+				message: "Invalid site key",
+				key: "API.INVALID_SITE_KEY",
+			}),
+		).toBe("Ungültiger Site-Schlüssel");
+	});
+
+	test("keeps the server message when the key is not in the catalogue", () => {
+		const i18n = germanI18n();
+		expect(
+			localiseErrorMessage(i18n, {
+				message: "upstream timed out",
+				key: "API.NOT_A_REAL_KEY",
+			}),
+		).toBe("upstream timed out");
+	});
+
+	test("keeps the server message when there is no key", () => {
+		const i18n = germanI18n();
+		expect(localiseErrorMessage(i18n, { message: "Invalid site key" })).toBe(
+			"Invalid site key",
+		);
+	});
+
+	test("keeps the server message until i18n is initialised", () => {
+		const i18n = i18nIn(de, false);
+		expect(
+			localiseErrorMessage(i18n, {
+				message: "Invalid site key",
+				key: "API.INVALID_SITE_KEY",
+			}),
+		).toBe("Invalid site key");
+		expect(
+			localiseErrorMessage(undefined, {
+				message: "Invalid site key",
+				key: "API.INVALID_SITE_KEY",
+			}),
+		).toBe("Invalid site key");
+	});
+});

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

@@ -220,22 +220,30 @@ describe("translating", () => {
 
 	test("substitutes interpolation values", async () => {
 		const harness = await load({
-			catalogues: { en: { POSITION: "{{x}} across, {{y}} down" } },
+			catalogues: {
+				en: { WIDGET: { PUZZLE: { POSITION: "{{x}} across, {{y}} down" } } },
+			},
 		});
 
-		expect((await initialised(harness)).t("POSITION", { x: 10, y: 20 })).toBe(
-			"10 across, 20 down",
-		);
+		expect(
+			(await initialised(harness)).t("WIDGET.PUZZLE.POSITION", {
+				x: 10,
+				y: 20,
+			}),
+		).toBe("10 across, 20 down");
 	});
 
 	test("falls back to English when the translation lacks the key", async () => {
 		const harness = await load({
-			catalogues: { fr: { KEPT: "gardé" }, en: { KEPT: "kept", ONLY: "only" } },
+			catalogues: {
+				fr: { WIDGET: { SUBMIT: "gardé" } },
+				en: { WIDGET: { SUBMIT: "kept", CANCEL: "only" } },
+			},
 		});
 		const i18n = await initialised(harness, "fr");
 
-		expect(i18n.t("KEPT")).toBe("gardé");
-		expect(i18n.t("ONLY")).toBe("only");
+		expect(i18n.t("WIDGET.SUBMIT")).toBe("gardé");
+		expect(i18n.t("WIDGET.CANCEL")).toBe("only");
 	});
 
 	test("falls back to the caller's default when no catalogue has the key", async () => {
@@ -252,7 +260,7 @@ describe("translating", () => {
 		const harness = await load({ catalogues: { en: {} } });
 
 		expect(
-			(await initialised(harness)).t("POSITION", {
+			(await initialised(harness)).t("WIDGET.PUZZLE.POSITION", {
 				defaultValue: "{{x}} across",
 				x: 7,
 			}),
@@ -262,17 +270,17 @@ describe("translating", () => {
 	test("falls back to the key when there is no default either", async () => {
 		const harness = await load({ catalogues: { en: {} } });
 
-		expect((await initialised(harness)).t("WIDGET.MISSING")).toBe(
-			"WIDGET.MISSING",
+		expect((await initialised(harness)).t("WIDGET.SUBMIT")).toBe(
+			"WIDGET.SUBMIT",
 		);
 	});
 
 	test("leaves a placeholder alone when no value was supplied for it", async () => {
 		const harness = await load({
-			catalogues: { en: { GREET: "hello {{name}}" } },
+			catalogues: { en: { WIDGET: { SUBMIT: "hello {{name}}" } } },
 		});
 
-		expect((await initialised(harness)).t("GREET", { other: 1 })).toBe(
+		expect((await initialised(harness)).t("WIDGET.SUBMIT", { other: 1 })).toBe(
 			"hello {{name}}",
 		);
 	});
@@ -304,14 +312,17 @@ describe("when the catalogue cannot be fetched", () => {
 describe("switching language", () => {
 	test("loads the new catalogue and translates against it", async () => {
 		const harness = await load({
-			catalogues: { en: { YES: "yes" }, de: { YES: "ja" } },
+			catalogues: {
+				en: { WIDGET: { SUBMIT: "yes" } },
+				de: { WIDGET: { SUBMIT: "ja" } },
+			},
 		});
 		const i18n = await initialised(harness, "en");
 
 		await i18n.changeLanguage("de");
 
 		expect(i18n.language).toBe("de");
-		expect(i18n.t("YES")).toBe("ja");
+		expect(i18n.t("WIDGET.SUBMIT")).toBe("ja");
 	});
 
 	test("notifies subscribers", async () => {

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

@@ -22,11 +22,13 @@ import {
 	LanguageCodes,
 	Languages,
 	type Ti18n,
+	type TranslateFn,
 	type TranslationKey,
 	createTranslator,
 	i18nMiddleware,
 	isClientSide,
 	isLanguage,
+	isTranslationKey,
 	loadI18next,
 	translationKeys,
 } from "../index.js";
@@ -67,8 +69,30 @@ describe("isLanguage", () => {
 });
 
 describe("TranslationKey", () => {
-	it("is a plain string — keys are read from JSON, never narrowed", () => {
-		expectTypeOf<TranslationKey>().toEqualTypeOf<string>();
+	it("is the union of the English catalogue's leaf paths", () => {
+		expectTypeOf<"WIDGET.I_AM_HUMAN">().toExtend<TranslationKey>();
+		expectTypeOf<"WIDGET.PUZZLE.RETRY">().toExtend<TranslationKey>();
+		expectTypeOf<string>().not.toExtend<TranslationKey>();
+	});
+
+	it("rejects a mistyped key", () => {
+		// @ts-expect-error not a key in the English catalogue
+		assertType<TranslationKey>("WIDGET.I_AM_HUMANN");
+	});
+
+	it("rejects a branch, which has no text of its own", () => {
+		// @ts-expect-error WIDGET is an object, not a leaf
+		assertType<TranslationKey>("WIDGET");
+	});
+
+	it("rejects a mistyped key at a translate call", () => {
+		const translate: TranslateFn = (key: TranslationKey): string => key;
+		// @ts-expect-error not a key in the English catalogue
+		translate("API.UNKNOWNN");
+	});
+
+	it("narrows a runtime string with isTranslationKey", () => {
+		expectTypeOf(isTranslationKey).guards.toEqualTypeOf<TranslationKey>();
 	});
 
 	it("accepts a key literal, so error call sites need no cast", () => {

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

@@ -0,0 +1,91 @@
+// 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 translationEn from "../locales/en/translation.json" with {
+	type: "json",
+};
+
+// Error classes and ResultReason carry a catalogue key. A key with no entry
+// reaches users and logs untranslated, so every one used in the workspace's
+// source must exist in the English catalogue (the parity test in
+// locales.unit.test.ts carries it to every other locale).
+
+const PACKAGES_DIR = path.resolve("..");
+const THROWN_KEY = /Error\(\s*["']([A-Z][A-Z_]*\.[A-Z0-9_]+)["']/g;
+const REASON_KEY = /=\s*"([A-Z][A-Z_]*\.[A-Z0-9_]+)"/g;
+
+const isCatalogueKey = (key: string): boolean => {
+	const [section, name] = key.split(".");
+	const entries: Record<string, unknown> | undefined =
+		section && section in translationEn
+			? translationEn[section as keyof typeof translationEn]
+			: undefined;
+	return name !== undefined && entries !== undefined && name in entries;
+};
+
+const sourceFiles = (dir: string): string[] =>
+	fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry: fs.Dirent) => {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			return entry.name === "tests" || entry.name === "node_modules"
+				? []
+				: sourceFiles(full);
+		}
+		return entry.name.endsWith(".ts") && !entry.name.includes(".test.")
+			? [full]
+			: [];
+	});
+
+const workspaceSources = (): string[] =>
+	fs
+		.readdirSync(PACKAGES_DIR)
+		.map((name: string) => path.join(PACKAGES_DIR, name, "src"))
+		.filter((dir: string) => fs.existsSync(dir))
+		.flatMap(sourceFiles);
+
+const uncataloguedKeys = (files: string[], pattern: RegExp): string[] => {
+	const missing = new Set<string>();
+	for (const file of files) {
+		for (const match of fs.readFileSync(file, "utf8").matchAll(pattern)) {
+			const key = match[1];
+			if (key && !isCatalogueKey(key)) {
+				missing.add(`${key} (${path.relative(PACKAGES_DIR, file)})`);
+			}
+		}
+	}
+	return [...missing].sort();
+};
+
+describe("error keys", () => {
+	test("every key an error class is constructed with is in the catalogue", () => {
+		expect(uncataloguedKeys(workspaceSources(), THROWN_KEY)).toEqual([]);
+	});
+
+	test("every ResultReason is in the catalogue", () => {
+		const reasons = path.join(PACKAGES_DIR, "types/src/provider/reasons.ts");
+		expect(uncataloguedKeys([reasons], REASON_KEY)).toEqual([]);
+	});
+
+	test("the scan finds the keys it is looking for", () => {
+		const found = workspaceSources().flatMap((file: string) =>
+			[...fs.readFileSync(file, "utf8").matchAll(THROWN_KEY)].map(
+				(match: RegExpMatchArray) => match[1],
+			),
+		);
+		expect(found).toContain("DATABASE.DATABASE_IMPORT_FAILED");
+		expect(found.length).toBeGreaterThan(100);
+	});
+});

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

@@ -19,6 +19,7 @@ import translationEn from "../locales/en/translation.json" with {
 import {
 	type TranslationNode,
 	getLeafFieldPath,
+	isTranslationKey,
 	translationKeys,
 } from "../translationKey.js";
 
@@ -138,3 +139,17 @@ describe("translationKeys", () => {
 		expect(translationKeys).not.toContain("");
 	});
 });
+
+describe("isTranslationKey", () => {
+	test("accepts a leaf of the English catalogue", () => {
+		expect(isTranslationKey("WIDGET.I_AM_HUMAN")).toBe(true);
+		expect(isTranslationKey("API.INVALID_SITE_KEY")).toBe(true);
+	});
+
+	test("rejects a section, a mistyped key, free text and the empty string", () => {
+		expect(isTranslationKey("WIDGET")).toBe(false);
+		expect(isTranslationKey("WIDGET.I_AM_HUMANN")).toBe(false);
+		expect(isTranslationKey("Invalid site key")).toBe(false);
+		expect(isTranslationKey("")).toBe(false);
+	});
+});

package/src/translationKey.ts

@@ -57,8 +57,17 @@ export function getLeafFieldPath(obj: TranslationNode): string[] {
 
 export const translationKeys: string[] = getLeafFieldPath(translationEn);
 
-/**
- * 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;
+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/translator.ts

@@ -13,6 +13,7 @@
 // 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";
@@ -23,7 +24,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?: TranslateOptions): string;
+	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
@@ -49,7 +50,7 @@ export const createTranslator = (existing?: Ti18n): Translator => {
 		i18n.isInitialized && i18n.hasLoadedNamespace(NAMESPACE);
 
 	return {
-		t: (key: string, options?: TranslateOptions): string =>
+		t: (key: TranslationKey, options?: TranslateOptions): string =>
 			i18n.t(key, options),
 		isReady,
 		i18n,

package/src/types.ts

@@ -12,6 +12,8 @@
 // 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}}`
@@ -22,7 +24,10 @@ export interface TranslateOptions {
 	[value: string]: unknown;
 }
 
-export type TranslateFn = (key: string, options?: TranslateOptions) => string;
+export type TranslateFn = (
+	key: TranslationKey,
+	options?: TranslateOptions,
+) => string;
 
 export type I18nEvent = "initialized" | "loaded" | "languageChanged";