@prosopo/locale 3.4.3 → 3.6.0

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

@@ -0,0 +1,68 @@
+// 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 { 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: 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
+	 * 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: string, 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

@@ -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"
 		}
 	]
 }