@buenojs/bueno 0.8.3 → 0.8.5

package/src/i18n/engine.ts

@@ -0,0 +1,305 @@
+/**
+ * i18n Engine — Translation Lookup and Interpolation
+ *
+ * Orchestrates locale loading and exposes the t() translation function.
+ * Handles pluralisation, variable interpolation, fallback, and metrics.
+ */
+
+import { TranslationLoader } from "./loader";
+import { LocaleNegotiator } from "./negotiator";
+import type {
+	I18nConfig,
+	I18nMetrics,
+	PluralKey,
+	ResolvedI18nConfig,
+	TranslationFunction,
+	TranslationParams,
+} from "./types";
+
+// ============= Defaults =============
+
+const DEFAULT_I18N_CONFIG: ResolvedI18nConfig = {
+	defaultLocale: "en",
+	supportedLocales: ["en"],
+	basePath: "resources/i18n",
+	fallbackToDefault: true,
+	cookieName: "bueno_locale",
+	cookieMaxAge: 31536000,
+};
+
+// ============= Plural Resolution =============
+
+/**
+ * Select the appropriate plural key based on the count value.
+ * Uses simple English-style pluralisation (zero, one, other).
+ *
+ * Resolution:
+ * - count === 0  → look for "{key}_zero", fall back to "{key}_other"
+ * - count === 1  → look for "{key}_one", fall back to "{key}_other"
+ * - else         → look for "{key}_other"
+ *
+ * If no plural variant is found, returns the bare key
+ * (allowing non-plural strings to be used without variants).
+ *
+ * For full CLDR support (two, few, many forms), users can subclass
+ * and override this function.
+ *
+ * @param count The count parameter from translation params
+ * @param availableKeys Set of all available key names (for fast lookup)
+ * @param base Base key name (without _zero/_one/_other suffix)
+ * @returns The resolved plural key to use
+ */
+function selectPluralKey(
+	count: number,
+	availableKeys: Set<string>,
+	base: string,
+): string {
+	const candidates: PluralKey[] =
+		count === 0
+			? ["zero", "other"]
+			: count === 1
+				? ["one", "other"]
+				: ["other"];
+
+	for (const form of candidates) {
+		const candidate = `${base}_${form}`;
+		if (availableKeys.has(candidate)) return candidate;
+	}
+	return base; // fall back to bare key (caller handles missing)
+}
+
+// ============= Interpolation =============
+
+/**
+ * Replace {{ name }} and {{ name }} placeholders with values from params.
+ *
+ * Regex: /\{\{\s*(\w+)\s*\}\}/g
+ * Matches: {{ key }}, {{key}}, {{ key}} (with optional whitespace)
+ *
+ * Unresolved placeholders (key not in params) are replaced with empty string.
+ *
+ * @example
+ * interpolate("Hello, {{name}}!", { name: "Alice" }) → "Hello, Alice!"
+ * interpolate("You have {{count}} items", { count: 3 }) → "You have 3 items"
+ * interpolate("Hello {{missing}}", {}) → "Hello "
+ *
+ * @param template Template string with {{ }} placeholders
+ * @param params Key-value pairs for interpolation
+ * @returns Interpolated string
+ */
+function interpolate(template: string, params: TranslationParams): string {
+	return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (_, key: string) => {
+		const val = params[key];
+		return val === undefined || val === null ? "" : String(val);
+	});
+}
+
+// ============= I18n Engine =============
+
+/**
+ * Main i18n engine.
+ * Handles translation lookup, plural forms, interpolation, and caching.
+ *
+ * Usage:
+ * ```
+ * const i18n = new I18n({ defaultLocale: 'en', supportedLocales: ['en', 'fr'] });
+ * i18n.preload(); // optional
+ * const t = i18n.createTranslator('fr');
+ * console.log(t('greeting', { name: 'Alice' })); // from fr.json
+ * ```
+ */
+export class I18n {
+	private loader: TranslationLoader;
+	private negotiator: LocaleNegotiator;
+	readonly config: ResolvedI18nConfig;
+	private metrics: I18nMetrics = {
+		totalLookups: 0,
+		hits: 0,
+		fallbacks: 0,
+		misses: 0,
+		loadedLocales: [],
+	};
+
+	/**
+	 * Create an i18n engine.
+	 * @param config Optional configuration (all fields are optional)
+	 */
+	constructor(config: I18nConfig = {}) {
+		this.config = {
+			defaultLocale: config.defaultLocale ?? DEFAULT_I18N_CONFIG.defaultLocale,
+			supportedLocales:
+				config.supportedLocales ?? DEFAULT_I18N_CONFIG.supportedLocales,
+			basePath: config.basePath ?? DEFAULT_I18N_CONFIG.basePath,
+			fallbackToDefault:
+				config.fallbackToDefault ?? DEFAULT_I18N_CONFIG.fallbackToDefault,
+			cookieName: config.cookieName ?? DEFAULT_I18N_CONFIG.cookieName,
+			cookieMaxAge: config.cookieMaxAge ?? DEFAULT_I18N_CONFIG.cookieMaxAge,
+		};
+
+		this.loader = new TranslationLoader(this.config);
+		this.negotiator = new LocaleNegotiator(
+			this.config.supportedLocales,
+			this.config.defaultLocale,
+		);
+	}
+
+	/**
+	 * Pre-load all supported locale files at startup.
+	 * Optional — lazy loading works without calling this.
+	 * Useful for production to catch missing files early.
+	 */
+	preload(): void {
+		this.loader.preload();
+	}
+
+	/**
+	 * Enable hot-reload file watching for all supported locales.
+	 * Should only be called in development mode.
+	 */
+	watchAll(): void {
+		for (const locale of this.config.supportedLocales) {
+			this.loader.watch(locale);
+		}
+	}
+
+	/**
+	 * Stop all file watchers.
+	 * Call this when the application shuts down.
+	 */
+	stopWatching(): void {
+		this.loader.stopWatching();
+	}
+
+	/**
+	 * Return a bound translation function for the given locale.
+	 * This is what gets stored on context: ctx.set('t', ...)
+	 *
+	 * @param locale Locale to create translator for
+	 * @returns TranslationFunction bound to that locale
+	 */
+	createTranslator(locale: string): TranslationFunction {
+		return (key: string, params?: TranslationParams): string => {
+			return this.t(locale, key, params);
+		};
+	}
+
+	/**
+	 * Primary translation lookup.
+	 *
+	 * Resolution order:
+	 * 1. Check `locale` translations
+	 *    a. If `params.count` is provided, try plural key first ({key}_one, {key}_other, etc.)
+	 *    b. Then try bare key
+	 * 2. If fallbackToDefault and locale !== defaultLocale, repeat step 1 for defaultLocale
+	 * 3. Return the key string as last resort
+	 *
+	 * Metrics are tracked: hits (found in locale), fallbacks (found in default),
+	 * misses (returned key string).
+	 *
+	 * @param locale Locale to translate in
+	 * @param key Translation key (supports dot-notation for nested keys)
+	 * @param params Optional translation parameters (interpolation + plural count)
+	 * @returns Translated string, or key string if not found
+	 */
+	t(locale: string, key: string, params?: TranslationParams): string {
+		this.metrics.totalLookups++;
+
+		const hasCount =
+			params !== undefined &&
+			"count" in params &&
+			typeof params.count === "number";
+
+		// Attempt resolution in given locale
+		const result = this._resolve(locale, key, params, hasCount);
+		if (result !== null) {
+			this.metrics.hits++;
+			return result;
+		}
+
+		// Fallback to default locale
+		if (this.config.fallbackToDefault && locale !== this.config.defaultLocale) {
+			const fallbackResult = this._resolve(
+				this.config.defaultLocale,
+				key,
+				params,
+				hasCount,
+			);
+			if (fallbackResult !== null) {
+				this.metrics.fallbacks++;
+				return fallbackResult;
+			}
+		}
+
+		// Complete miss — return the key path
+		this.metrics.misses++;
+		return key;
+	}
+
+	/**
+	 * Returns the LocaleNegotiator instance for use by middleware.
+	 * @returns LocaleNegotiator instance
+	 */
+	getNegotiator(): LocaleNegotiator {
+		return this.negotiator;
+	}
+
+	/**
+	 * Get current translation metrics.
+	 * Useful for debugging and performance monitoring.
+	 * @returns Current I18nMetrics
+	 */
+	getMetrics(): I18nMetrics {
+		return {
+			...this.metrics,
+			loadedLocales: this.loader.loadedLocales(),
+		};
+	}
+
+	// ============= Private Helpers =============
+
+	/**
+	 * Resolve a translation key in a specific locale.
+	 * Returns null if not found (to distinguish from a successful empty string).
+	 *
+	 * @param locale Locale to resolve in
+	 * @param key Translation key
+	 * @param params Translation parameters
+	 * @param hasCount Whether params contains a count field
+	 * @returns Translated string, or null if not found
+	 */
+	private _resolve(
+		locale: string,
+		key: string,
+		params: TranslationParams | undefined,
+		hasCount: boolean,
+	): string | null {
+		const bundle = this.loader.load(locale);
+		const translations = bundle.translations;
+		const availableKeys = new Set(translations.keys());
+
+		let resolvedKey = key;
+
+		// Plural selection
+		if (hasCount) {
+			resolvedKey = selectPluralKey(params!.count!, availableKeys, key);
+		}
+
+		const raw = translations.get(resolvedKey);
+		if (raw === undefined) return null;
+
+		return params ? interpolate(raw, params) : raw;
+	}
+}
+
+// ============= Factory =============
+
+/**
+ * Create an i18n engine.
+ * Convenience factory for new I18n(config).
+ *
+ * @param config Optional configuration
+ * @returns New I18n instance
+ */
+export function createI18n(config?: I18nConfig): I18n {
+	return new I18n(config);
+}

package/src/i18n/index.ts

@@ -0,0 +1,38 @@
+/**
+ * i18n Module — Internationalisation for Bueno Framework
+ *
+ * Locale detection (cookie → Accept-Language), translation lookup with
+ * dot-notation keys, variable interpolation, plural forms, and caching.
+ */
+
+// Types
+export type {
+	PluralKey,
+	TranslationMap,
+	FlatTranslations,
+	TranslationParams,
+	TranslationFunction,
+	LocaleMatch,
+	I18nContext,
+	I18nConfig,
+	ResolvedI18nConfig,
+	LocaleBundle,
+	I18nMetrics,
+} from "./types";
+
+// Core engine
+export { I18n, createI18n } from "./engine";
+
+// Loader (advanced use)
+export { TranslationLoader } from "./loader";
+
+// Negotiator (advanced use)
+export {
+	LocaleNegotiator,
+	parseAcceptLanguage,
+	normaliseLocale,
+} from "./negotiator";
+
+// Middleware
+export { i18nMiddleware, getLocale, getT } from "./middleware";
+export type { I18nMiddlewareOptions } from "./middleware";

package/src/i18n/loader.ts

@@ -0,0 +1,218 @@
+/**
+ * Translation Loader — JSON File Loading and Caching
+ *
+ * Loads locale JSON files from disk, flattens nested keys to dot-notation,
+ * caches in memory, and supports hot-reload via file watching.
+ */
+
+import { existsSync, readFileSync, watch } from "fs";
+import { join, resolve } from "path";
+import type {
+	FlatTranslations,
+	LocaleBundle,
+	ResolvedI18nConfig,
+} from "./types";
+
+// ============= Flattening =============
+
+/**
+ * Recursively flatten a nested object into dot-notation keys.
+ *
+ * @example
+ * flattenTranslations({ nav: { home: "Home", about: "About" } })
+ * → Map { "nav.home" → "Home", "nav.about" → "About" }
+ *
+ * Already-flat keys pass through unchanged.
+ * Non-string leaf values are converted via String().
+ * Arrays are not recursed — they are stringified as-is.
+ *
+ * @param obj Object to flatten (or nested structure)
+ * @param prefix Current dot-notation prefix (used recursively)
+ * @param result Accumulator map (used recursively)
+ * @returns Flattened Map with all keys in dot-notation form
+ */
+function flattenTranslations(
+	obj: Record<string, unknown>,
+	prefix = "",
+	result: FlatTranslations = new Map(),
+): FlatTranslations {
+	for (const [key, value] of Object.entries(obj)) {
+		const dotKey = prefix ? `${prefix}.${key}` : key;
+		if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+			flattenTranslations(value as Record<string, unknown>, dotKey, result);
+		} else {
+			result.set(dotKey, String(value ?? ""));
+		}
+	}
+	return result;
+}
+
+// ============= Loader =============
+
+/**
+ * Loads and caches locale translation bundles from JSON files.
+ * Supports file watching for hot-reload in development.
+ */
+export class TranslationLoader {
+	private cache: Map<string, LocaleBundle> = new Map();
+	private watchers: Map<string, ReturnType<typeof watch>> = new Map();
+	private config: ResolvedI18nConfig;
+
+	constructor(config: ResolvedI18nConfig) {
+		this.config = config;
+	}
+
+	/**
+	 * Load a locale bundle. Returns from cache if already loaded.
+	 *
+	 * For the default locale:
+	 *   - Throws if the file is not found (cannot proceed without defaults)
+	 *
+	 * For non-default locales:
+	 *   - Returns an empty bundle if the file is not found
+	 *   - Fallback in the engine will handle the miss
+	 *
+	 * @param locale Locale identifier to load
+	 * @returns LocaleBundle with flattened translations
+	 * @throws Error if default locale file is not found
+	 */
+	load(locale: string): LocaleBundle {
+		const cached = this.cache.get(locale);
+		if (cached) return cached;
+
+		return this._loadFromDisk(locale);
+	}
+
+	/**
+	 * Pre-load all supported locales eagerly.
+	 * Call this once at application startup for best performance.
+	 *
+	 * Non-default locales that are missing are silently skipped
+	 * (returning empty bundles).
+	 */
+	preload(): void {
+		for (const locale of this.config.supportedLocales) {
+			try {
+				this._loadFromDisk(locale);
+			} catch {
+				// Non-default locales may legitimately have no file yet
+				if (locale !== this.config.defaultLocale) {
+					this.cache.set(locale, {
+						locale,
+						translations: new Map(),
+						loadedAt: Date.now(),
+					});
+				}
+			}
+		}
+	}
+
+	/**
+	 * Invalidate a locale's cache entry.
+	 * Forces a reload from disk on the next access.
+	 *
+	 * @param locale Locale to invalidate
+	 */
+	invalidate(locale: string): void {
+		this.cache.delete(locale);
+	}
+
+	/**
+	 * Return all currently loaded locale names.
+	 *
+	 * @returns Array of loaded locale identifiers
+	 */
+	loadedLocales(): string[] {
+		return Array.from(this.cache.keys());
+	}
+
+	/**
+	 * Enable file watching for a locale (hot reload in dev mode).
+	 * Invalidates cache and reloads on file change.
+	 *
+	 * @param locale Locale file to watch
+	 */
+	watch(locale: string): void {
+		const filePath = this._resolvePath(locale);
+		if (!existsSync(filePath)) return;
+		if (this.watchers.has(locale)) return;
+
+		const watcher = watch(filePath, () => {
+			this.invalidate(locale);
+			try {
+				this._loadFromDisk(locale);
+			} catch {
+				// Ignore parse errors during hot reload — log in production
+			}
+		});
+
+		this.watchers.set(locale, watcher);
+	}
+
+	/**
+	 * Stop all file watchers.
+	 * Call this when the application shuts down.
+	 */
+	stopWatching(): void {
+		for (const watcher of this.watchers.values()) {
+			watcher.close();
+		}
+		this.watchers.clear();
+	}
+
+	// ============= Private Helpers =============
+
+	/**
+	 * Resolve the full file path for a locale.
+	 * @param locale Locale identifier
+	 * @returns Full file path to the locale JSON file
+	 */
+	private _resolvePath(locale: string): string {
+		return resolve(join(this.config.basePath, `${locale}.json`));
+	}
+
+	/**
+	 * Load a locale file from disk and cache it.
+	 * @param locale Locale to load
+	 * @returns LocaleBundle with flattened translations
+	 * @throws Error if default locale file is not found or JSON is invalid
+	 */
+	private _loadFromDisk(locale: string): LocaleBundle {
+		const filePath = this._resolvePath(locale);
+
+		if (!existsSync(filePath)) {
+			if (locale === this.config.defaultLocale) {
+				throw new Error(
+					`[i18n] Default locale file not found: ${filePath}. ` +
+						`Create ${locale}.json in ${this.config.basePath}`,
+				);
+			}
+			// For non-default locales, silently return an empty bundle
+			const empty: LocaleBundle = {
+				locale,
+				translations: new Map(),
+				loadedAt: Date.now(),
+			};
+			this.cache.set(locale, empty);
+			return empty;
+		}
+
+		const raw = readFileSync(filePath, "utf-8");
+		let parsed: Record<string, unknown>;
+		try {
+			parsed = JSON.parse(raw);
+		} catch (err) {
+			throw new Error(
+				`[i18n] Failed to parse locale file ${filePath}: ${String(err)}`,
+			);
+		}
+
+		const bundle: LocaleBundle = {
+			locale,
+			translations: flattenTranslations(parsed),
+			loadedAt: Date.now(),
+		};
+		this.cache.set(locale, bundle);
+		return bundle;
+	}
+}