@prosopo/locale 3.6.1 → 3.7.0

package/src/i18nBackend.ts

@@ -1,69 +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 path from "node:path";
-import i18n from "i18next";
-import FSBackend from "i18next-fs-backend/cjs"; // https://github.com/i18next/i18next-fs-backend/issues/57
-import { LanguageDetector as MiddlewareLanguageDetector } from "i18next-http-middleware";
-import { i18nSharedOptions } from "./i18SharedOptions.js";
-import { isServerSide } from "./util.js";
-
-const loadPath =
-	`${path.dirname(import.meta.url)}/locales/{{lng}}/{{ns}}.json`.replace(
-		"file://",
-		"",
-	);
-
-export function initializeI18n(
-	i18nLoadedCallback?: (value: typeof i18n) => void,
-) {
-	if (!i18n.isInitialized && isServerSide()) {
-		const lngDetector = new MiddlewareLanguageDetector(null, {
-			order: ["header", "query", "cookie"],
-		});
-		i18n
-			// @ts-ignore https://github.com/i18next/i18next-fs-backend/issues/57
-			.use(FSBackend)
-			.use(lngDetector) // this line should switch the language to the one the user reports in the Accept-Language header
-			.init({
-				...i18nSharedOptions,
-				ns: ["translation"],
-				backend: {
-					loadPath,
-				},
-			});
-		// "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;
-			}
-			notified = true;
-			i18nLoadedCallback?.(i18n);
-		});
-	} else {
-		// Nothing to initialise — either i18next is already up (a frontend
-		// consumer got there first) or we are not on the server. The `loaded`
-		// handler above is only registered inside the init branch, so without
-		// this the callback would never fire and loadI18next() would stay
-		// pending forever instead of handing back the instance we already have.
-		i18nLoadedCallback?.(i18n);
-	}
-	return i18n;
-}
-
-export default initializeI18n;

package/src/i18nFrontend.ts

@@ -1,267 +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 { flatten } from "@prosopo/util";
-import { i18nSharedOptions } from "./i18SharedOptions.js";
-import type { I18nEvent, Ti18n, TranslateOptions } from "./types.js";
-
-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`;
-};
-
-/**
- * `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;
-};
-
-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,
-			)
-		: 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");
-			}
-			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 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 instance;
-}
-
-export default initializeI18n;

package/src/i18nMiddleware.ts

@@ -1,35 +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 i18n from "i18next";
-import { handle } from "i18next-http-middleware";
-import loadI18next from "./loadI18next.js";
-
-// i18next-http-middleware stopped exporting HandleOptions in 3.9.x (the
-// interface is still there, just no longer `export`ed). Derive it from handle()
-// so it keeps tracking whatever the library actually accepts.
-type HandleOptions = NonNullable<Parameters<typeof handle>[1]>;
-
-async function i18nMiddleware(
-	options: HandleOptions,
-): Promise<ReturnType<typeof handle>> {
-	// 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 });
-}
-
-export default i18nMiddleware;

package/src/index.ts

@@ -1,29 +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.
-
-export { default as i18nMiddleware } from "./i18nMiddleware.js";
-export { default as loadI18next } from "./loadI18next.js";
-export { isLanguage, LanguageCodes, Languages } from "./translations.js";
-export type { Language } from "./translations.js";
-export { isClientSide } from "./util.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 {
-	I18nEvent,
-	Ti18n,
-	TranslateFn,
-	TranslateOptions,
-} from "./types.js";

package/src/loadI18next.ts

@@ -1,136 +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 type { Ti18n } from "./types.js";
-
-let i18nInstance: Ti18n;
-
-/**
- * How long to wait for i18next to report `loaded` before giving up on it.
- *
- * Resolution is driven by an event, and events are not guaranteed: a backend
- * that never answers (http backend against a dead CDN, fs backend against a
- * missing locales dir) leaves the listener armed and the promise pending for
- * the lifetime of the process. `cli.ts` calls loadI18next(true).then(...) with
- * nothing to time it out, so a pending promise there is a silent boot hang with
- * no log line to explain it.
- */
-export const I18N_LOAD_TIMEOUT_MS = 10_000;
-
-const reconcileLanguage = async (
-	instance: Ti18n,
-	lng: string | undefined,
-): Promise<Ti18n> => {
-	if (lng && instance.language !== lng) {
-		await instance.changeLanguage(lng);
-	}
-	return instance;
-};
-
-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
-		// resource is missing, so a degraded instance renders untranslated text;
-		// a rejection instead takes down the caller, and neither caller handles
-		// one — cli.ts has no .catch, and widgetFactory awaits it inside the
-		// render path, so the widget would not appear at all. Untranslated beats
-		// absent. Genuine errors still reject: this arm only fires on silence.
-		let settled = false;
-		// No `settled` guard needed here: both latches clear this timer, so it
-		// can only fire while nothing has settled.
-		const timer = setTimeout(() => {
-			settled = true;
-			if (i18nInstance) {
-				resolve(i18nInstance);
-			} else {
-				reject(
-					new Error(
-						`i18next did not load within ${I18N_LOAD_TIMEOUT_MS}ms and no instance was created`,
-					),
-				);
-			}
-		}, I18N_LOAD_TIMEOUT_MS);
-		// Node keeps the event loop alive for a pending timer, which would hold
-		// a short-lived CLI process open for the full timeout after it had
-		// otherwise finished.
-		timer.unref?.();
-
-		// 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: Ti18n): void => {
-			if (settled) {
-				return;
-			}
-			settled = true;
-			clearTimeout(timer);
-			resolve(instance);
-		};
-		const failWith = (error: unknown): void => {
-			if (settled) {
-				return;
-			}
-			settled = true;
-			clearTimeout(timer);
-			reject(error);
-		};
-
-		// Every asynchronous branch below terminates in `.catch(failWith)`. A
-		// synchronous try/catch cannot see a rejected dynamic import or a
-		// rejected changeLanguage(), so without these the executor would
-		// simply return and the promise would stay pending forever — callers
-		// (i18nMiddleware, and through it the whole server bootstrap) would
-		// hang rather than fail.
-		if (backend) {
-			import("./i18nBackend.js")
-				.then(({ default: initializeI18n }) => {
-					if (!i18nInstance) {
-						// pass the resolver into the i18n init fn, which fires it on the first
-						// "loaded" event
-						i18nInstance = initializeI18n(done);
-					} else {
-						// we've already initialised i18n so just return it
-						done(i18nInstance);
-					}
-				})
-				.catch(failWith);
-		} else {
-			import("./i18nFrontend.js")
-				.then(({ default: initializeI18n }) => {
-					if (!i18nInstance) {
-						// Pass `lng` in on first init so browser detection is skipped
-						// entirely when the site owner has supplied a language. The
-						// resolver only fires on the `loaded` event, so at resolve
-						// time the target-language resources are guaranteed present.
-						i18nInstance = initializeI18n((instance) => {
-							void reconcileLanguage(instance, lng).then(done).catch(failWith);
-						}, lng);
-					} else {
-						// Singleton already exists (e.g. a prior widget mounted with a
-						// different language, or a direct consumer initialised earlier).
-						// Reconcile before resolving so callers can render synchronously
-						// against the requested language instead of seeing a flash of
-						// the previous one.
-						void reconcileLanguage(i18nInstance, lng)
-							.then(done)
-							.catch(failWith);
-					}
-				})
-				.catch(failWith);
-		}
-	});
-}
-
-export default loadI18next;