@rimelight/i18n 0.0.6 → 0.0.8

package/dist/hono.d.mts

@@ -0,0 +1,8 @@
+//#region src/hono.d.ts
+/**
+ * Hono middleware for Rimelight i18n. Handles locale routing, redirection, currentLocale store
+ * updates, and Cloudflare KV binding setup.
+ */
+declare function i18n(): (c: any, next: any) => Promise<any>;
+//#endregion
+export { i18n };

package/dist/hono.mjs

@@ -0,0 +1,80 @@
+import { currentLocale } from "./runtime.mjs";
+import { setKVBinding } from "./index.mjs";
+import { defaultLocale, locales, prefixDefaultLocale } from "virtual:rimelight-i18n-config";
+import { env } from "cloudflare:workers";
+//#region src/hono.ts
+const SUPPORTED_LOCALES = new Set(locales);
+const DEFAULT_LOCALE = defaultLocale;
+function getPreferredLocale(acceptLanguage) {
+	if (!acceptLanguage) return DEFAULT_LOCALE;
+	const parsed = acceptLanguage.split(",").map((lang) => {
+		const parts = lang.split(";");
+		const code = (parts[0] ?? "").trim().toLowerCase();
+		const base = code.split("-")[0] ?? "";
+		let q = 1;
+		const qualityPart = parts[1];
+		if (qualityPart) {
+			const qMatch = qualityPart.match(/q=([0-9.]+)/);
+			if (qMatch) q = parseFloat(qMatch[1] ?? "1");
+		}
+		return {
+			code,
+			base,
+			q
+		};
+	}).toSorted((a, b) => b.q - a.q);
+	for (const item of parsed) {
+		if (SUPPORTED_LOCALES.has(item.code)) return item.code;
+		const base = item.base;
+		if (SUPPORTED_LOCALES.has(base)) return base;
+	}
+	return DEFAULT_LOCALE;
+}
+/**
+* Hono middleware for Rimelight i18n. Handles locale routing, redirection, currentLocale store
+* updates, and Cloudflare KV binding setup.
+*/
+function i18n() {
+	return async (c, next) => {
+		try {
+			const kv = Reflect.get(env, "TRANSLATIONS_KV") || c.env?.TRANSLATIONS_KV;
+			if (kv) setKVBinding(kv);
+		} catch {}
+		const url = new URL(c.req.url);
+		const pathname = url.pathname;
+		if (c.req.method !== "GET" && c.req.method !== "HEAD") {
+			const paramLocale = c.req.param("locale");
+			const firstSegment = pathname.split("/").find(Boolean);
+			const activeLocale = (paramLocale && SUPPORTED_LOCALES.has(paramLocale) ? paramLocale : null) || (firstSegment && SUPPORTED_LOCALES.has(firstSegment) ? firstSegment : null) || DEFAULT_LOCALE;
+			currentLocale.set(activeLocale);
+			return next();
+		}
+		if (pathname.startsWith("/api") || pathname.startsWith("/_") || pathname.includes(".")) return next();
+		const firstSegment = pathname.split("/").find(Boolean);
+		const firstIsLocale = firstSegment !== void 0 && SUPPORTED_LOCALES.has(firstSegment);
+		if (prefixDefaultLocale) {
+			const paramLocale = c.req.param("locale");
+			const activeLocale = (paramLocale && SUPPORTED_LOCALES.has(paramLocale) ? paramLocale : null) || (firstIsLocale ? firstSegment : null) || DEFAULT_LOCALE;
+			currentLocale.set(activeLocale);
+			if (firstIsLocale) return next();
+			const locale = getPreferredLocale(c.req.header("accept-language") || null);
+			currentLocale.set(locale);
+			const targetPath = `/${locale}${pathname}${url.search}`;
+			return c.redirect(targetPath, 302);
+		} else {
+			if (firstIsLocale) {
+				if (firstSegment === DEFAULT_LOCALE) {
+					const rest = pathname.slice(DEFAULT_LOCALE.length + 1) || "/";
+					currentLocale.set(DEFAULT_LOCALE);
+					return c.redirect(`${rest}${url.search}`, 302);
+				}
+				currentLocale.set(firstSegment);
+				return next();
+			}
+			currentLocale.set(DEFAULT_LOCALE);
+			return next();
+		}
+	};
+}
+//#endregion
+export { i18n };

package/dist/index.d.mts

@@ -0,0 +1,37 @@
+import { ComponentsJSON, CustomTranslations, KVNamespaceBinding, NestedTranslationKeys, TranslationKey } from "./types.mjs";
+import { clearCache, currentLocale, getFormatterInstance, getI18nInstance, getPluralCategory, initializeI18n, useFormat, useI18n, useI18nAsync } from "./runtime.mjs";
+import { RimelightI18nOptions, RimelightI18nPlugins, i18n } from "./plugin.mjs";
+import { TranslationLoader } from "@nanostores/i18n";
+import { defaultLocale, locales, prefixDefaultLocale } from "virtual:rimelight-i18n-config";
+//#region src/index.d.ts
+/**
+ * Translates a single string key using dot-notation (e.g. `t("page_home.section_hero_title")`).
+ * When augmented via CustomTranslations, keys are strictly type-checked and autocompleted.
+ */
+declare function t<K extends string = TranslationKey>(key: K | TranslationKey, params?: Record<string, any>): string;
+declare function getLocale(): string;
+/**
+ * Returns a standard BCP 47 / RFC 5646 language tag suitable for HTML `<html lang="...">`. Maps
+ * 2-letter codes like 'en' to 'en-US', 'pt' to 'pt-BR', 'es' to 'es-ES', etc.
+ */
+declare function getHtmlLang(): string;
+/**
+ * Returns an OpenGraph-compliant locale tag (e.g. 'en_US', 'pt_BR', 'es_ES').
+ */
+declare function getOgLocale(): string;
+declare function getRelativeLocaleUrl(path: string): string;
+declare function getRelativeLocaleUrl(locale: string, path: string): string;
+declare function getRelativeLocaleUrlList(path?: string): string[];
+interface LanguageAlternate {
+  hreflang: string;
+  href: string;
+}
+/**
+ * Generates an array of hreflang alternates for SEO tags (<link rel="alternate" hreflang="...">).
+ * Automatically includes all supported locales and 'x-default'.
+ */
+declare function getLanguageAlternates(pathname: string, siteUrl?: string): LanguageAlternate[];
+declare function setKVBinding(kv: KVNamespaceBinding): void;
+declare function createTranslationLoader(translations: Record<string, ComponentsJSON>): TranslationLoader;
+//#endregion
+export { type CustomTranslations, LanguageAlternate, type NestedTranslationKeys, type RimelightI18nOptions, type RimelightI18nPlugins, type TranslationKey, clearCache, createTranslationLoader, currentLocale, defaultLocale, getFormatterInstance, getHtmlLang, getI18nInstance, getLanguageAlternates, getLocale, getOgLocale, getPluralCategory, getRelativeLocaleUrl, getRelativeLocaleUrlList, i18n, i18n as rimelightI18n, initializeI18n, locales, prefixDefaultLocale, setKVBinding, t, useFormat, useI18n, useI18nAsync };

package/dist/index.mjs

@@ -0,0 +1,110 @@
+import { clearCache, currentLocale, getFormatterInstance, getI18nInstance, getPluralCategory, initializeI18n, t as t$1, useFormat, useI18n, useI18nAsync } from "./runtime.mjs";
+import { i18n } from "./plugin.mjs";
+import { defaultLocale, locales, prefixDefaultLocale, translations } from "virtual:rimelight-i18n-config";
+//#region src/index.ts
+if (translations && Object.keys(translations).length > 0) initializeI18n({
+	defaultLocale: defaultLocale || "en",
+	translations
+});
+/**
+* Translates a single string key using dot-notation (e.g. `t("page_home.section_hero_title")`).
+* When augmented via CustomTranslations, keys are strictly type-checked and autocompleted.
+*/
+function t(key, params) {
+	return t$1(key, params);
+}
+function getLocale() {
+	return currentLocale.get() || defaultLocale || "en";
+}
+/**
+* Returns a standard BCP 47 / RFC 5646 language tag suitable for HTML `<html lang="...">`. Maps
+* 2-letter codes like 'en' to 'en-US', 'pt' to 'pt-BR', 'es' to 'es-ES', etc.
+*/
+function getHtmlLang() {
+	const loc = getLocale();
+	return {
+		en: "en-US",
+		pt: "pt-BR",
+		es: "es-ES"
+	}[loc] || loc;
+}
+/**
+* Returns an OpenGraph-compliant locale tag (e.g. 'en_US', 'pt_BR', 'es_ES').
+*/
+function getOgLocale() {
+	const loc = getLocale();
+	return {
+		en: "en_US",
+		pt: "pt_BR",
+		es: "es_ES"
+	}[loc] || `${loc}_${loc.toUpperCase()}`;
+}
+function getRelativeLocaleUrl(arg1, arg2) {
+	let targetLocale;
+	let targetPath;
+	if (arg2 !== void 0) {
+		targetLocale = arg1;
+		targetPath = arg2;
+	} else {
+		targetLocale = getLocale();
+		targetPath = arg1;
+	}
+	if (/^(?:[a-z]+:|\/\/|#)/i.test(targetPath) || targetPath.startsWith("mailto:") || targetPath.startsWith("tel:")) return targetPath;
+	const [pathWithoutQueryAndHash, queryAndHash] = (() => {
+		const match = targetPath.match(/^([^?#]*)([?#].*)?$/);
+		return [match?.[1] ?? "", match?.[2] ?? ""];
+	})();
+	const rawCleanPath = pathWithoutQueryAndHash.replace(/^\/+/, "");
+	const segments = rawCleanPath ? rawCleanPath.split("/") : [];
+	if (segments.length > 0 && locales.includes(segments[0])) segments.shift();
+	const cleanPath = segments.join("/");
+	const prefix = prefixDefaultLocale || targetLocale !== defaultLocale ? `/${targetLocale}` : "";
+	if (!cleanPath) return `${prefix ? `${prefix}/` : "/"}${queryAndHash}`;
+	return `${`${prefix}/${cleanPath}${pathWithoutQueryAndHash.endsWith("/") ? "/" : ""}`}${queryAndHash}`;
+}
+function getRelativeLocaleUrlList(path = "/") {
+	return locales.map((locale) => getRelativeLocaleUrl(locale, path));
+}
+/**
+* Generates an array of hreflang alternates for SEO tags (<link rel="alternate" hreflang="...">).
+* Automatically includes all supported locales and 'x-default'.
+*/
+function getLanguageAlternates(pathname, siteUrl = "") {
+	const normalizedSiteUrl = siteUrl.replace(/\/+$/, "");
+	const alternates = locales.map((loc) => ({
+		hreflang: loc,
+		href: `${normalizedSiteUrl}${getRelativeLocaleUrl(loc, pathname)}`
+	}));
+	alternates.push({
+		hreflang: "x-default",
+		href: `${normalizedSiteUrl}${getRelativeLocaleUrl(defaultLocale, pathname)}`
+	});
+	return alternates;
+}
+let kvBinding = null;
+function setKVBinding(kv) {
+	kvBinding = kv;
+}
+function createTranslationLoader(translations) {
+	return async (locale, components) => {
+		const localeTranslations = translations[locale] || {};
+		if (!components || !Array.isArray(components) || components.length === 0) return localeTranslations;
+		const activeKv = kvBinding;
+		if (activeKv) try {
+			const results = await Promise.all(components.map(async (name) => {
+				const key = `locale:${locale}:${name}`;
+				const data = await activeKv.get(key, "json");
+				if (data == null) return { [name]: localeTranslations[name] ?? {} };
+				return { [name]: data };
+			}));
+			return Object.assign({}, ...results);
+		} catch {}
+		const results = await Promise.all(components.map(async (name) => {
+			const data = localeTranslations[name];
+			return { [name]: data ?? {} };
+		}));
+		return Object.assign({}, ...results);
+	};
+}
+//#endregion
+export { clearCache, createTranslationLoader, currentLocale, defaultLocale, getFormatterInstance, getHtmlLang, getI18nInstance, getLanguageAlternates, getLocale, getOgLocale, getPluralCategory, getRelativeLocaleUrl, getRelativeLocaleUrlList, i18n, i18n as rimelightI18n, initializeI18n, locales, prefixDefaultLocale, setKVBinding, t, useFormat, useI18n, useI18nAsync };

package/dist/plugin.d.mts

@@ -0,0 +1,39 @@
+//#region src/plugin.d.ts
+interface RimelightI18nOptions {
+  /**
+   * List of supported locale codes (e.g. `["en", "pt"]`).
+   */
+  locales?: string[];
+  /**
+   * The default locale code (e.g. `"en"`).
+   */
+  defaultLocale?: string;
+  /**
+   * Whether to prefix the default locale in URLs.
+   *
+   * - `true` (default): all locales are prefixed — `/en/about`, `/pt/about`
+   * - `false`: the default locale has no prefix — `/about`, `/pt/about`
+   */
+  prefixDefaultLocale?: boolean;
+  validateExtraction?: boolean;
+  translations?: Record<string, Record<string, any>>;
+  kvBinding?: string;
+  translationLoader?: string;
+}
+interface RimelightI18nVitePlugin {
+  name: string;
+  enforce?: "pre" | "post";
+  resolveId?: (id: string) => string | null | undefined;
+  load?: (id: string) => string | null | undefined;
+  config?: (config: any) => any;
+  closeBundle?: () => Promise<void> | void;
+  [key: string]: any;
+}
+type RimelightI18nPlugins = RimelightI18nVitePlugin[];
+/**
+ * Pure Vite plugin for Rimelight i18n. Provides virtual modules `@rimelight/i18n:runtime` and
+ * `virtual:rimelight-i18n-config`.
+ */
+declare function i18n(options?: RimelightI18nOptions): RimelightI18nPlugins;
+//#endregion
+export { RimelightI18nOptions, RimelightI18nPlugins, RimelightI18nVitePlugin, i18n, i18n as rimelightI18n };

package/dist/plugin.mjs

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import path from "node:path";
+//#region src/plugin.ts
+/**
+* Pure Vite plugin for Rimelight i18n. Provides virtual modules `@rimelight/i18n:runtime` and
+* `virtual:rimelight-i18n-config`.
+*/
+function i18n(options) {
+	const translations = options?.translations;
+	const kvBinding = options?.kvBinding ?? "TRANSLATIONS_KV";
+	const locales = options?.locales ?? ["en"];
+	const defaultLocale = options?.defaultLocale ?? "en";
+	const prefixDefaultLocale = options?.prefixDefaultLocale ?? true;
+	const normalisedTranslations = {};
+	if (translations) for (const [locale, val] of Object.entries(translations)) normalisedTranslations[locale] = val;
+	return [{
+		name: "vite-plugin-rimelight-i18n-config",
+		resolveId(id) {
+			if (id === "virtual:rimelight-i18n-config") return "\0" + id;
+			return null;
+		},
+		load(id) {
+			if (id === "\0virtual:rimelight-i18n-config") return `
+            export const locales = ${JSON.stringify(locales)};
+            export const defaultLocale = ${JSON.stringify(defaultLocale)};
+            export const prefixDefaultLocale = ${JSON.stringify(prefixDefaultLocale)};
+            export const translations = ${JSON.stringify(normalisedTranslations)};
+          `;
+			return null;
+		},
+		async closeBundle() {
+			if (!translations) return;
+			const seedData = { keys: [] };
+			for (const [locale, localeData] of Object.entries(translations)) for (const [component, componentData] of Object.entries(localeData)) seedData.keys.push({
+				key: `locale:${locale}:${component}`,
+				value: JSON.stringify(componentData)
+			});
+			const outDir = process.env.WRANGLER_OUT_DIR ?? "dist";
+			const seedFile = path.join(outDir, "_translations-seed.json");
+			try {
+				fs.mkdirSync(path.dirname(seedFile), { recursive: true });
+				fs.writeFileSync(seedFile, JSON.stringify(seedData, null, 2));
+				if (process.env.WRANGLER_SEED_KV === "true" || process.env.CI === "true") {
+					const { execSync } = await import("node:child_process");
+					execSync(`npx wrangler kv:bulk put --binding "${kvBinding}" "${seedFile}"`, {
+						stdio: "pipe",
+						timeout: 3e4
+					});
+				}
+			} catch {}
+		}
+	}];
+}
+//#endregion
+export { i18n, i18n as rimelightI18n };

package/dist/runtime.d.mts

@@ -0,0 +1,72 @@
+import { Components, I18n, TranslationLoader, Translations, formatter } from "@nanostores/i18n";
+//#region src/runtime.d.ts
+/**
+ * A reactive store containing the current locale code. Set by middleware on each request, or
+ * manually via `currentLocale.set(locale)`.
+ */
+declare const currentLocale: import("nanostores").PreinitializedWritableAtom<string> & object;
+type I18nInstance = I18n;
+type FormatterInstance = ReturnType<typeof formatter>;
+interface InitializeI18nOptions {
+  /**
+   * The default locale code (e.g. 'en').
+   */
+  defaultLocale: string;
+  /**
+   * Pre-loaded translations keyed by locale then component.
+   */
+  translations: Record<string, Components>;
+  /**
+   * Optional dynamic loader called when a locale is not in cache.
+   */
+  get?: TranslationLoader;
+}
+/**
+ * Initializes the i18n system. Must be called once before any other i18n functions are used (the
+ * integration virtual module does this automatically).
+ */
+declare function initializeI18n(options: InitializeI18nOptions): void;
+/**
+ * Returns the underlying nanostores/i18n instance. Throws if not initialized.
+ */
+declare function getI18nInstance(): I18nInstance;
+/**
+ * Returns the formatter instance. Throws if not initialized.
+ */
+declare function getFormatterInstance(): FormatterInstance;
+/**
+ * Returns a Formatter object for the current locale with methods for formatting numbers, dates, and
+ * relative times using the native Intl API.
+ */
+declare function useFormat(): ReturnType<FormatterInstance["get"]>;
+/**
+ * Returns the translated strings for a component in the current locale. Falls back to defaultLocale
+ * loaded translations or `baseTranslations` if provided.
+ */
+interface ComponentMessages {
+  [key: string]: string;
+}
+declare function useI18n(componentName: string): ComponentMessages;
+declare function useI18n<Body extends Translations>(componentName: string, baseTranslations: Body): ComponentMessages & Body;
+/**
+ * Async version of useI18n that waits for translations to finish loading.
+ */
+declare function useI18nAsync(componentName: string): Promise<ComponentMessages>;
+declare function useI18nAsync<Body extends Translations>(componentName: string, baseTranslations: Body): Promise<ComponentMessages & Body>;
+/**
+ * Translates a single string key using dot-notation (e.g. `t("page_home.section_hero_title")`).
+ */
+declare function t(key: string, params?: Record<string, any>): string;
+/**
+ * Returns the plural category (e.g. 'one', 'few', 'many', 'other') for a given number and locale
+ * using the native browser Intl.PluralRules API.
+ */
+declare function getPluralCategory(count: number, locale?: string): Intl.LDMLPluralRule;
+/**
+ * Clears the translation cache.
+ *
+ * @param locale - If provided, clears only that locale's cache. Otherwise clears all.
+ */
+declare function clearCache(locale?: string): void;
+//#endregion
+export { ComponentMessages, InitializeI18nOptions, clearCache, currentLocale, getFormatterInstance, getI18nInstance, getPluralCategory, initializeI18n, t, useFormat, useI18n, useI18nAsync };

package/dist/runtime.mjs

@@ -0,0 +1,183 @@
+import { createI18n, formatter, translationsLoading } from "@nanostores/i18n";
+import { atom } from "nanostores";
+//#region src/runtime.ts
+/**
+* A reactive store containing the current locale code. Set by middleware on each request, or
+* manually via `currentLocale.set(locale)`.
+*/
+const currentLocale = atom("");
+let i18nInstance;
+let formatterInstance;
+let baseLocaleDefault = "en";
+let rawTranslationsDict = {};
+function throwNotInitialized() {
+	throw new Error("i18n not initialized. Call initializeI18n first.");
+}
+/**
+* Wraps a TranslationLoader so that the returned object is guaranteed to contain a key for every
+* requested component.
+*
+* The nanostores i18n library uses the keys of the object returned from `get` to clear its internal
+* "requested" set. If a requested component is missing from the result (e.g. because the backend
+* has no translations for it in the given locale yet), the internal loading atom is never set back
+* to `false`, which causes useI18nAsync / translationsLoading to hang forever.
+*
+* This wrapper normalises the loader output so missing components are filled in with empty
+* translation objects, falling back to the base translations defined at the call site.
+*/
+function wrapLoader(loader) {
+	return async (code, components) => {
+		const raw = await loader(code, components);
+		const normalised = Array.isArray(raw) ? Object.assign({}, ...raw) : { ...raw };
+		for (const component of components) if (!(component in normalised)) normalised[component] = {};
+		return normalised;
+	};
+}
+/**
+* Initializes the i18n system. Must be called once before any other i18n functions are used (the
+* integration virtual module does this automatically).
+*/
+function initializeI18n(options) {
+	const { defaultLocale, translations, get } = options;
+	baseLocaleDefault = defaultLocale;
+	rawTranslationsDict = translations || {};
+	if (!i18nInstance) {
+		currentLocale.set(defaultLocale);
+		const formattedCache = {};
+		for (const [locale, components] of Object.entries(translations)) {
+			formattedCache[locale] = {};
+			for (const [compName, compBody] of Object.entries(components)) {
+				let bodyObj = {};
+				if (isStringRecord(compBody)) bodyObj = compBody;
+				else if (isStoreWithGet(compBody)) {
+					const res = compBody.get();
+					if (isStringRecord(res)) bodyObj = res;
+				}
+				formattedCache[locale][compName] = atom(bodyObj);
+			}
+		}
+		i18nInstance = createI18n(currentLocale, {
+			baseLocale: defaultLocale,
+			get: wrapLoader(get ?? (async () => ({}))),
+			cache: formattedCache,
+			isSSR: true
+		});
+	}
+	formatterInstance = formatter(currentLocale);
+}
+/**
+* Returns the underlying nanostores/i18n instance. Throws if not initialized.
+*/
+function getI18nInstance() {
+	if (!i18nInstance) throwNotInitialized();
+	return i18nInstance;
+}
+/**
+* Returns the formatter instance. Throws if not initialized.
+*/
+function getFormatterInstance() {
+	if (!formatterInstance) throwNotInitialized();
+	return formatterInstance;
+}
+/**
+* Returns a Formatter object for the current locale with methods for formatting numbers, dates, and
+* relative times using the native Intl API.
+*/
+function useFormat() {
+	return getFormatterInstance().get();
+}
+function isStoreWithGet(obj) {
+	if (typeof obj !== "object" || obj === null) return false;
+	return typeof Reflect.get(obj, "get") === "function";
+}
+function isStringRecord(obj) {
+	return typeof obj === "object" && obj !== null;
+}
+function getCachedComponent(locale, componentName) {
+	const normalizedLocale = locale.toLowerCase();
+	const candidates = [
+		locale,
+		normalizedLocale,
+		normalizedLocale.split("-")[0] ?? normalizedLocale,
+		baseLocaleDefault
+	];
+	for (const code of candidates) {
+		const rawComp = rawTranslationsDict[code]?.[componentName];
+		if (isStoreWithGet(rawComp)) {
+			const res = rawComp.get();
+			if (isStringRecord(res)) return res;
+		} else if (isStringRecord(rawComp)) return rawComp;
+	}
+	if (!i18nInstance) return void 0;
+	for (const code of candidates) {
+		const rawComp = i18nInstance.cache[code]?.[componentName];
+		if (isStoreWithGet(rawComp)) {
+			const res = rawComp.get();
+			if (isStringRecord(res)) return res;
+		} else if (isStringRecord(rawComp)) return rawComp;
+	}
+}
+function useI18n(componentName, baseTranslations) {
+	const i18n = getI18nInstance();
+	const activeLocale = currentLocale.get() || baseLocaleDefault;
+	const fallbackDict = isStringRecord(baseTranslations) ? baseTranslations : {};
+	const baseDict = getCachedComponent(activeLocale, componentName) ?? getCachedComponent(baseLocaleDefault, componentName) ?? fallbackDict;
+	const targetObj = i18n(componentName, baseDict).get();
+	return new Proxy(targetObj, { get(target, prop) {
+		if (typeof prop === "symbol" || prop in Object.prototype) {
+			const val = Reflect.get(target, prop);
+			return typeof val === "string" ? val : "";
+		}
+		return target[prop] ?? baseDict[prop] ?? prop;
+	} });
+}
+async function useI18nAsync(componentName, baseTranslations) {
+	const i18n = getI18nInstance();
+	const cachedActive = getCachedComponent(currentLocale.get() || baseLocaleDefault, componentName);
+	const cachedDefault = getCachedComponent(baseLocaleDefault, componentName);
+	let baseDict = cachedActive ?? cachedDefault ?? {};
+	if (!cachedActive && !cachedDefault && isStringRecord(baseTranslations)) baseDict = baseTranslations;
+	const store = i18n(componentName, baseDict);
+	const unsubscribe = store.listen(() => {});
+	await translationsLoading(i18n);
+	unsubscribe();
+	return store.get();
+}
+/**
+* Translates a single string key using dot-notation (e.g. `t("page_home.section_hero_title")`).
+*/
+function t(key, params) {
+	const dotIndex = key.indexOf(".");
+	if (dotIndex === -1) return key;
+	const componentName = key.slice(0, dotIndex);
+	const keyName = key.slice(dotIndex + 1);
+	const activeLocale = currentLocale.get() || baseLocaleDefault;
+	let value = (getCachedComponent(activeLocale, componentName) ?? getCachedComponent(baseLocaleDefault, componentName) ?? {})[keyName] ?? key;
+	if (params && typeof params.count === "number" && typeof value === "object" && value !== null) {
+		const pluralCategory = getPluralCategory(params.count, activeLocale);
+		value = value[pluralCategory] ?? value.other ?? key;
+	}
+	if (typeof value === "function") return value(params);
+	if (params && typeof value === "string") return value.replace(/\{(\w+)\}/g, (_, k) => String(params[k] ?? `{${k}}`));
+	return typeof value === "string" ? value : String(value);
+}
+/**
+* Returns the plural category (e.g. 'one', 'few', 'many', 'other') for a given number and locale
+* using the native browser Intl.PluralRules API.
+*/
+function getPluralCategory(count, locale = "en") {
+	return new Intl.PluralRules(locale).select(count);
+}
+/**
+* Clears the translation cache.
+*
+* @param locale - If provided, clears only that locale's cache. Otherwise clears all.
+*/
+function clearCache(locale) {
+	if (!i18nInstance) throwNotInitialized();
+	const cache = i18nInstance.cache;
+	if (locale) cache[locale] = {};
+	else for (const key in cache) cache[key] = {};
+}
+//#endregion
+export { clearCache, currentLocale, getFormatterInstance, getI18nInstance, getPluralCategory, initializeI18n, t, useFormat, useI18n, useI18nAsync };

package/dist/types.d.mts

@@ -0,0 +1,32 @@
+import { ComponentsJSON } from "@nanostores/i18n";
+//#region src/types.d.ts
+interface FlattenedTranslations {
+  [key: string]: string;
+}
+interface LocaleFile {
+  [component: string]: {
+    [key: string]: string;
+  };
+}
+interface KVNamespaceBinding {
+  get(key: string, type: "json"): Promise<Record<string, string> | null>;
+  put(key: string, value: string): Promise<void>;
+}
+/**
+ * Derives dot-notated nested translation keys (e.g. "page_home.section_hero_title") from a
+ * translation schema type.
+ */
+type NestedTranslationKeys<T> = T extends object ? { [K in keyof T & (string | number)]: T[K] extends object ? `${K}.${NestedTranslationKeys<T[K]>}` : `${K}`; }[keyof T & (string | number)] : never;
+/**
+ * Augmented interface for app-level strongly typed translation keys. Applications can declare:
+ *
+ * ```ts
+ * declare module "@rimelight/i18n" {
+ *   interface CustomTranslations extends typeof import("./translations/en.json") {}
+ * }
+ * ```
+ */
+interface CustomTranslations {}
+type TranslationKey = [keyof CustomTranslations] extends [never] ? string : NestedTranslationKeys<CustomTranslations>;
+//#endregion
+export { type ComponentsJSON, CustomTranslations, FlattenedTranslations, KVNamespaceBinding, LocaleFile, NestedTranslationKeys, TranslationKey };

package/dist/types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.mts

@@ -0,0 +1,12 @@
+import { ComponentsJSON, FlattenedTranslations } from "./types.mjs";
+//#region src/utils.d.ts
+declare function flatten(obj: ComponentsJSON): FlattenedTranslations;
+declare function unflatten(flat: FlattenedTranslations): ComponentsJSON;
+declare function extractKeys(source: ComponentsJSON): string[];
+/**
+ * Compares a target translation dictionary against a base/source translation dictionary, returning
+ * any missing component keys.
+ */
+declare function findMissingKeys(base: Record<string, Record<string, any>>, target: Record<string, Record<string, any>>): string[];
+//#endregion
+export { extractKeys, findMissingKeys, flatten, unflatten };