@prosopo/locale 3.5.0 → 3.6.1

package/src/i18nFrontend.ts

@@ -12,89 +12,256 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import i18n, { type InitOptions } from "i18next";
-import I18nextBrowserLanguageDetector from "i18next-browser-languagedetector";
-import ChainedBackend from "i18next-chained-backend";
-import HttpBackend from "i18next-http-backend";
-import resourcesToBackend from "i18next-resources-to-backend";
+import { flatten } from "@prosopo/util";
 import { i18nSharedOptions } from "./i18SharedOptions.js";
+import type { I18nEvent, Ti18n, TranslateOptions } from "./types.js";
 
-const detectionOptions: InitOptions = {
-	detection: {
-		order: ["navigator", "htmlTag", "path", "subdomain"],
-		caches: ["localStorage", "cookie"],
-	},
+const NAMESPACE = "translation";
+const FALLBACK_LANGUAGE = i18nSharedOptions.fallbackLng;
+const STORAGE_KEY = "i18nextLng";
+const COOKIE_KEY = "i18next";
+const COOKIE_MAX_AGE_SECONDS = 7 * 24 * 60 * 60;
+
+/**
+ * How long to wait for a catalogue before rendering untranslated.
+ *
+ * A widget with no text is worse than a widget in English: every caller
+ * supplies a `defaultValue`, and `t()` falls back to the key otherwise, so a
+ * catalogue that never arrives degrades rather than blocks.
+ */
+const CATALOGUE_FETCH_TIMEOUT_MS = 10_000;
+
+type Catalogue = Record<string, string>;
+
+const SUPPORTED_LANGUAGES: readonly string[] = i18nSharedOptions.supportedLngs;
+
+/**
+ * Locale JSON sits next to the bundle that asked for it. The widget is embedded
+ * by third parties and cannot know a base URL, but it does know where its own
+ * module was served from.
+ */
+const catalogueUrl = (language: string): string => {
+	const moduleUrl = import.meta.url;
+	const directory = moduleUrl.slice(0, moduleUrl.lastIndexOf("/"));
+	return `${directory}/locales/${language}/${NAMESPACE}.json`;
 };
 
-const getLoadPath = (language: string, namespace: string) => {
-	const filename = import.meta.url.split("/").pop();
-	return `${import.meta.url.replace(`/${filename}`, "")}/locales/${language}/${namespace}.json`;
+/**
+ * `en-GB` is not in the catalogue list but `en` is, so a regional tag resolves
+ * to its base language rather than falling all the way back to English.
+ */
+const resolveLanguage = (candidate: string | undefined): string | undefined => {
+	if (!candidate) {
+		return undefined;
+	}
+	if (SUPPORTED_LANGUAGES.includes(candidate)) {
+		return candidate;
+	}
+	const base = candidate.split("-")[0];
+	return base && SUPPORTED_LANGUAGES.includes(base) ? base : undefined;
 };
 
-export function initializeI18n(
-	i18nLoadedCallback?: (value: typeof i18n) => void,
-	lng?: string,
-) {
-	if (!i18n.isInitialized) {
-		i18n
-			// @ts-ignore
-			.use(ChainedBackend)
-			.use(
-				new I18nextBrowserLanguageDetector(null, {
-					order: ["cookie", "localStorage", "navigator"],
-					lookupQuerystring: "lng",
-					lookupCookie: "i18next",
-					lookupLocalStorage: "i18nextLng",
-					caches: ["localStorage", "cookie"],
-				}),
+const readCookie = (): string | undefined => {
+	try {
+		const match = document.cookie.match(
+			new RegExp(`(?:^|; )${COOKIE_KEY}=([^;]*)`),
+		);
+		return match?.[1] ? decodeURIComponent(match[1]) : undefined;
+	} catch {
+		return undefined;
+	}
+};
+
+const readStorage = (): string | undefined => {
+	try {
+		return localStorage.getItem(STORAGE_KEY) ?? undefined;
+	} catch {
+		return undefined;
+	}
+};
+
+const navigatorLanguages = (): readonly string[] => {
+	try {
+		return navigator.languages?.length
+			? navigator.languages
+			: [navigator.language];
+	} catch {
+		return [];
+	}
+};
+
+/**
+ * Cookie and localStorage are both written, matching what the widget did when
+ * i18next-browser-languagedetector handled this, so a visitor's choice survives
+ * across pages that embed the widget. Either store can throw in a sandboxed
+ * iframe or with third-party storage blocked; neither is load-bearing.
+ */
+const cacheLanguage = (language: string): void => {
+	try {
+		localStorage.setItem(STORAGE_KEY, language);
+	} catch {
+		// storage unavailable — the language is still active for this page
+	}
+	try {
+		document.cookie = `${COOKIE_KEY}=${encodeURIComponent(language)};max-age=${COOKIE_MAX_AGE_SECONDS};path=/`;
+	} catch {
+		// cookies unavailable — as above
+	}
+};
+
+const detectLanguage = (): string => {
+	const candidates = [readCookie(), readStorage(), ...navigatorLanguages()];
+	for (const candidate of candidates) {
+		const resolved = resolveLanguage(candidate);
+		if (resolved) {
+			return resolved;
+		}
+	}
+	return FALLBACK_LANGUAGE;
+};
+
+const fetchCatalogue = async (language: string): Promise<Catalogue> => {
+	const controller = new AbortController();
+	const timer = setTimeout(
+		() => controller.abort(),
+		CATALOGUE_FETCH_TIMEOUT_MS,
+	);
+	try {
+		const response = await fetch(catalogueUrl(language), {
+			signal: controller.signal,
+		});
+		if (!response.ok) {
+			return {};
+		}
+		const body: unknown = await response.json();
+		return typeof body === "object" && body !== null ? flatten(body) : {};
+	} catch {
+		return {};
+	} finally {
+		clearTimeout(timer);
+	}
+};
+
+const interpolate = (template: string, options?: TranslateOptions): string =>
+	options
+		? template.replace(/\{\{(\w+)\}\}/g, (placeholder, name: string) =>
+				name in options ? String(options[name]) : placeholder,
 			)
-			.init({
-				...i18nSharedOptions,
-				// When the site owner has resolved a language upfront (via widget
-				// config or data-language) we set `lng` explicitly so i18next skips
-				// browser detection. This is the single source of truth for the
-				// widget language and prevents the flash-of-wrong-language race
-				// where child components read the browser-detected language on
-				// first render before an effect can call changeLanguage().
-				...(lng ? { lng } : {}),
-				backend: {
-					backends: [
-						HttpBackend, // if a namespace can't be loaded via normal http-backend loadPath, then the inMemoryLocalBackend will try to return the correct resources
-						// with dynamic import, you have to use the "default" key of the module ( https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#importing_defaults )
-						resourcesToBackend(
-							(language: string, namespace: string) =>
-								import(getLoadPath(language, namespace)),
-						),
-					],
-					backendOptions: [
-						{
-							loadPath: getLoadPath("{{lng}}", "{{ns}}"),
-						},
-					],
-				},
-				...detectionOptions,
-			} as InitOptions);
-		// "loaded" fires once per namespace, and again after changeLanguage(),
-		// so the raw event is not the one-shot signal the callback expects.
-		// Latch it here as well as in loadI18next: this callback is public and
-		// a caller could reasonably use it to run a side effect.
-		let notified = false;
-		i18n.on("loaded", () => {
-			if (notified) {
-				return;
+		: template;
+
+interface BrowserI18n extends Ti18n {
+	/** Resolves once the active language's catalogue has been fetched. */
+	ready(): Promise<BrowserI18n>;
+}
+
+const createBrowserI18n = (requested?: string): BrowserI18n => {
+	const catalogues = new Map<string, Catalogue>();
+	const listeners = new Map<I18nEvent, Set<() => void>>();
+	let language = resolveLanguage(requested) ?? detectLanguage();
+	let initialised = false;
+
+	const emit = (event: I18nEvent): void => {
+		for (const listener of listeners.get(event) ?? []) {
+			listener();
+		}
+	};
+
+	/**
+	 * The fallback catalogue is fetched alongside the active one so a key
+	 * missing from a translation still renders English rather than its key —
+	 * the same key-level fallback i18next gave us via `fallbackLng`.
+	 */
+	const loadCatalogues = async (target: string): Promise<void> => {
+		const wanted = [...new Set([target, FALLBACK_LANGUAGE])].filter(
+			(candidate) => !catalogues.has(candidate),
+		);
+		await Promise.all(
+			wanted.map(async (candidate) => {
+				catalogues.set(candidate, await fetchCatalogue(candidate));
+			}),
+		);
+	};
+
+	const lookup = (candidate: string, key: string): string | undefined =>
+		catalogues.get(candidate)?.[key];
+
+	cacheLanguage(language);
+	const loading = loadCatalogues(language).then(() => {
+		initialised = true;
+		emit("initialized");
+		emit("loaded");
+	});
+
+	const instance: BrowserI18n = {
+		get language(): string {
+			return language;
+		},
+		get isInitialized(): boolean {
+			return initialised;
+		},
+		t: (key: string, options?: TranslateOptions): string =>
+			interpolate(
+				lookup(language, key) ??
+					lookup(FALLBACK_LANGUAGE, key) ??
+					options?.defaultValue ??
+					key,
+				options,
+			),
+		hasLoadedNamespace: (namespace: string): boolean =>
+			namespace === NAMESPACE && catalogues.has(language),
+		changeLanguage: async (next: string): Promise<BrowserI18n> => {
+			const resolved = resolveLanguage(next) ?? FALLBACK_LANGUAGE;
+			if (resolved !== language) {
+				language = resolved;
+				cacheLanguage(resolved);
+				await loadCatalogues(resolved);
+				emit("loaded");
+				emit("languageChanged");
 			}
-			notified = true;
-			i18nLoadedCallback?.(i18n);
-		});
+			return instance;
+		},
+		on: (event: I18nEvent, listener: () => void): void => {
+			const existing = listeners.get(event) ?? new Set<() => void>();
+			existing.add(listener);
+			listeners.set(event, existing);
+		},
+		off: (event: I18nEvent, listener: () => void): void => {
+			listeners.get(event)?.delete(listener);
+		},
+		ready: async (): Promise<BrowserI18n> => {
+			await loading;
+			return instance;
+		},
+	};
+
+	return instance;
+};
+
+/**
+ * The widget owns this instance. A host page running its own i18n must not be
+ * able to capture the widget's translations, and every widget on the page
+ * shares one catalogue fetch.
+ */
+let instance: BrowserI18n | undefined;
+
+export function initializeI18n(
+	i18nLoadedCallback?: (value: Ti18n) => void,
+	lng?: string,
+): Ti18n {
+	if (!instance) {
+		// Passing `lng` here rather than calling changeLanguage() afterwards is
+		// what stops the widget rendering a flash of the browser's language
+		// before the site owner's choice is applied.
+		const created = createBrowserI18n(lng);
+		instance = created;
+		void created.ready().then(() => i18nLoadedCallback?.(created));
 	} else {
-		// Already initialised (e.g. createTranslator() ran first, or a second
-		// widget mounted). The `loaded` handler is only registered in the init
-		// branch, so the callback has to fire here or loadI18next() never
-		// settles. Resources are already present, so resolving immediately is
-		// correct; the caller reconciles the language afterwards.
-		i18nLoadedCallback?.(i18n);
+		// Already built (a second widget on the page, or createTranslator() got
+		// here first). The callback is only armed in the branch above, so it has
+		// to fire here or loadI18next() never settles.
+		i18nLoadedCallback?.(instance);
 	}
-	return i18n;
+	return instance;
 }
 
 export default initializeI18n;

package/src/i18nMiddleware.ts

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+import i18n from "i18next";
 import { handle } from "i18next-http-middleware";
 import loadI18next from "./loadI18next.js";
 
@@ -23,7 +24,11 @@ type HandleOptions = NonNullable<Parameters<typeof handle>[1]>;
 async function i18nMiddleware(
 	options: HandleOptions,
 ): Promise<ReturnType<typeof handle>> {
-	const i18n = await loadI18next(true);
+	// The middleware needs the i18next instance itself, not the narrow Ti18n
+	// the widget shares with it. loadI18next(true) initialises that very
+	// singleton and waits for its resources, so importing it here is the same
+	// object, fully loaded.
+	await loadI18next(true);
 	return handle(i18n, { ...options });
 }
 

package/src/index.ts

@@ -14,10 +14,16 @@
 
 export { default as i18nMiddleware } from "./i18nMiddleware.js";
 export { default as loadI18next } from "./loadI18next.js";
-export { Languages, LanguageSchema } from "./translations.js";
+export { isLanguage, LanguageCodes, Languages } from "./translations.js";
+export type { Language } from "./translations.js";
 export { isClientSide } from "./util.js";
-export { TranslationKeysSchema } from "./translationKey.js";
+export { translationKeys } from "./translationKey.js";
 export type { TranslationKey } from "./translationKey.js";
 export { createTranslator } from "./translator.js";
 export type { Translator } from "./translator.js";
-export type { Ti18n } from "./loadI18next.js";
+export type {
+	I18nEvent,
+	Ti18n,
+	TranslateFn,
+	TranslateOptions,
+} from "./types.js";

package/src/loadI18next.ts

@@ -12,8 +12,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import type { i18n } from "i18next";
-let i18nInstance: i18n;
+import type { Ti18n } from "./types.js";
+
+let i18nInstance: Ti18n;
 
 /**
  * How long to wait for i18next to report `loaded` before giving up on it.
@@ -28,16 +29,16 @@ let i18nInstance: i18n;
 export const I18N_LOAD_TIMEOUT_MS = 10_000;
 
 const reconcileLanguage = async (
-	instance: i18n,
+	instance: Ti18n,
 	lng: string | undefined,
-): Promise<i18n> => {
+): Promise<Ti18n> => {
 	if (lng && instance.language !== lng) {
 		await instance.changeLanguage(lng);
 	}
 	return instance;
 };
 
-async function loadI18next(backend: boolean, lng?: string): Promise<i18n> {
+async function loadI18next(backend: boolean, lng?: string): Promise<Ti18n> {
 	return new Promise((resolve, reject) => {
 		// On timeout we resolve with the (possibly not fully loaded) instance
 		// rather than rejecting. i18next falls back to the key itself when a
@@ -69,7 +70,7 @@ async function loadI18next(backend: boolean, lng?: string): Promise<i18n> {
 		// Both latches are one-shot: i18next can emit `loaded` more than once
 		// (per namespace, and again after changeLanguage), and a late event
 		// arriving after the timeout must not re-settle or leak a second timer.
-		const done = (instance: i18n): void => {
+		const done = (instance: Ti18n): void => {
 			if (settled) {
 				return;
 			}
@@ -132,6 +133,4 @@ async function loadI18next(backend: boolean, lng?: string): Promise<i18n> {
 	});
 }
 
-export type { i18n as Ti18n };
-
 export default loadI18next;

package/src/locales/fi/translation.json

@@ -84,7 +84,7 @@
 		"JSON_LOAD_FAILED": "JSON-tiedoston lataaminen epäonnistui",
 		"MNEMONIC_UNDEFINED": "Mnemonic Undefined. Aseta mnemonic ympäristömuuttujiin",
 		"NO_MNEMONIC_OR_SEED": "Ei annettu mnemonicia tai siemenavainta",
-		"CANT_FIND_KEYRINGPAIR": "Avainta ei löydy {{osoite}}",
+		"CANT_FIND_KEYRINGPAIR": "Avainta ei löydy {{address}}",
 		"ENVIRONMENT_NOT_READY": "Ympäristö ei ole valmis",
 		"INVALID_SIGNATURE": "Virheellinen allekirjoitus",
 		"SITE_KEY_MISSING": "Sivuston avain puuttuu",