@jchat/addon-sdk 1.0.0-alpha.3 → 1.0.0-alpha.31

package/dist/i18n-validator.d.mts

@@ -0,0 +1,23 @@
+//#region src/i18n-validator.d.ts
+export interface AddonLocaleValidationResult {
+  valid: boolean;
+  errors: string[];
+  missingFiles: string[];
+  missingKeys: Record<string, string[]>;
+  extraKeys: Record<string, string[]>;
+}
+export interface ValidateAddonLocalesOptions {
+  strict?: boolean;
+}
+/**
+ * Validates that an addon's `locales/` directory contains a valid `en.json` base file, and that any
+ * provided host language files contain valid JSON and matching keys. Missing translations
+ * automatically fall back to English at runtime.
+ *
+ * @param dirPath - Path to the addon's locales directory.
+ * @param domainName - Optional label for error messages (defaults to "Addon").
+ * @param options - Optional configuration (e.g. `{ strict: true }` to enforce 100% presence of all
+ *   20 language files).
+ */
+export declare function validateAddonLocales(dirPath: string, domainName?: string, options?: ValidateAddonLocalesOptions): AddonLocaleValidationResult;
+//#endregion

package/dist/i18n-validator.mjs

@@ -0,0 +1,95 @@
+import { HOST_LOCALES } from "./contracts.mjs";
+import "./i18n.mjs";
+import * as path$1 from "node:path";
+import * as fs$1 from "node:fs";
+//#region src/i18n-validator.ts
+function extractNestedKeys(obj, prefix = "") {
+	if (!obj || typeof obj !== "object") return [];
+	const keys = [];
+	for (const [key, value] of Object.entries(obj)) {
+		const fullKey = prefix ? `${prefix}.${key}` : key;
+		if (value && typeof value === "object" && !Array.isArray(value)) keys.push(...extractNestedKeys(value, fullKey));
+		else keys.push(fullKey);
+	}
+	return keys;
+}
+/**
+* Validates that an addon's `locales/` directory contains a valid `en.json` base file, and that any
+* provided host language files contain valid JSON and matching keys. Missing translations
+* automatically fall back to English at runtime.
+*
+* @param dirPath - Path to the addon's locales directory.
+* @param domainName - Optional label for error messages (defaults to "Addon").
+* @param options - Optional configuration (e.g. `{ strict: true }` to enforce 100% presence of all
+*   20 language files).
+*/
+function validateAddonLocales(dirPath, domainName = "Addon", options) {
+	const isStrict = Boolean(options?.strict);
+	const errors = [];
+	const missingFiles = [];
+	const missingKeys = {};
+	const extraKeys = {};
+	const enPath = path$1.join(dirPath, "en.json");
+	if (!fs$1.existsSync(enPath)) {
+		const errorMsg = `[${domainName}] Missing base locale file: en.json`;
+		errors.push(errorMsg);
+		missingFiles.push("en.json");
+		return {
+			valid: false,
+			errors,
+			missingFiles,
+			missingKeys,
+			extraKeys
+		};
+	}
+	let enContent;
+	try {
+		enContent = JSON.parse(fs$1.readFileSync(enPath, "utf-8"));
+	} catch (err) {
+		const errorMsg = `[${domainName}] Invalid JSON in en.json: ${err instanceof Error ? err.message : String(err)}`;
+		errors.push(errorMsg);
+		return {
+			valid: false,
+			errors,
+			missingFiles,
+			missingKeys,
+			extraKeys
+		};
+	}
+	const enKeys = new Set(extractNestedKeys(enContent));
+	for (const lang of HOST_LOCALES) {
+		if (lang === "en") continue;
+		const langFileName = `${lang}.json`;
+		const langPath = path$1.join(dirPath, langFileName);
+		if (!fs$1.existsSync(langPath)) {
+			missingFiles.push(langFileName);
+			if (isStrict) errors.push(`[${domainName}] Missing locale file: ${langFileName}`);
+			continue;
+		}
+		try {
+			const langContent = JSON.parse(fs$1.readFileSync(langPath, "utf-8"));
+			const langKeys = new Set(extractNestedKeys(langContent));
+			for (const key of enKeys) if (!langKeys.has(key)) {
+				if (!missingKeys[lang]) missingKeys[lang] = [];
+				missingKeys[lang].push(key);
+				if (isStrict) errors.push(`[${domainName}] Missing key in ${langFileName}: "${key}"`);
+			}
+			for (const key of langKeys) if (!enKeys.has(key)) {
+				errors.push(`[${domainName}] Extra key in ${langFileName} (not in en.json): "${key}"`);
+				if (!extraKeys[lang]) extraKeys[lang] = [];
+				extraKeys[lang].push(key);
+			}
+		} catch (err) {
+			errors.push(`[${domainName}] Invalid JSON in ${langFileName}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+	return {
+		valid: errors.length === 0,
+		errors,
+		missingFiles,
+		missingKeys,
+		extraKeys
+	};
+}
+//#endregion
+export { validateAddonLocales };

package/dist/i18n.mjs

@@ -0,0 +1,169 @@
+import { createContext, useContext, useEffect, useMemo, useState } from "react";
+//#region src/i18n.ts
+function checkIsRtl(code) {
+	if (!code) return false;
+	const normalized = code.toLowerCase().split("-")[0];
+	return normalized === "ar" || normalized === "he" || normalized === "ur";
+}
+function getLanguageDirection(code) {
+	return checkIsRtl(code) ? "rtl" : "ltr";
+}
+function interpolate(text, params) {
+	if (!params) return text;
+	return text.replace(/\{\{\s*(\w+)\s*\}\}|\{\s*(\w+)\s*\}/g, (match, key1, key2) => {
+		const key = key1 || key2;
+		return key in params ? String(params[key]) : match;
+	});
+}
+const LocaleContext = createContext({
+	locale: "en",
+	dir: "ltr"
+});
+/** Resolves a nested key in an object dictionary using dot-notation (e.g. "buttons.submit") */
+function resolveNestedKey(obj, keyPath) {
+	if (!obj || typeof obj !== "object") return void 0;
+	const segments = keyPath.split(".");
+	let current = obj;
+	for (const seg of segments) if (current && typeof current === "object" && seg in current) current = current[seg];
+	else return;
+	return current;
+}
+/**
+* Creates a standalone translation function for backend server routes (`src/api.ts`) or utilities.
+*
+* @param resources - Dictionary of translation resources (e.g., `{ en: enJson, ta: taJson }`).
+* @param defaultLocale - Default locale to use if not specified per call (defaults to "en").
+* @param fallbackLocale - Fallback locale if a key is missing in the target language (defaults to
+*   "en").
+*/
+function createTranslator(resources = {}, defaultLocale = "en", fallbackLocale = "en") {
+	return (key, paramsOrLang, maybeLang) => {
+		let params;
+		let lang = defaultLocale;
+		if (typeof paramsOrLang === "string") lang = paramsOrLang;
+		else if (paramsOrLang && typeof paramsOrLang === "object") {
+			params = paramsOrLang;
+			if (typeof maybeLang === "string") lang = maybeLang;
+		}
+		const normalizedLang = (lang || defaultLocale).toLowerCase().split("-")[0];
+		const normalizedFallback = fallbackLocale.toLowerCase().split("-")[0];
+		const langDict = resources[normalizedLang];
+		let resolved = resolveNestedKey(langDict, key);
+		if (resolved === void 0 && normalizedLang !== normalizedFallback) {
+			const fallbackDict = resources[normalizedFallback];
+			resolved = resolveNestedKey(fallbackDict, key);
+		}
+		if (typeof resolved === "string") return interpolate(resolved, params);
+		return typeof resolved === "number" || typeof resolved === "boolean" ? String(resolved) : interpolate(key, params);
+	};
+}
+/**
+* Hook to access the current active host locale and text direction in an addon component.
+*
+* @example
+*   ;```tsx
+*   import { useLocale } from "@jchat/addon-sdk"
+*
+*   export default function MyAddon() {
+*     const { locale, dir, isRtl } = useLocale()
+*     return <div dir={dir}>Current language: {locale}</div>
+*   }
+*   ```
+*/
+function useLocale() {
+	const context = useContext(LocaleContext);
+	const locale = context?.locale || "en";
+	const dir = context?.dir || getLanguageDirection(locale);
+	return {
+		locale,
+		dir,
+		isRtl: dir === "rtl" || checkIsRtl(locale)
+	};
+}
+const loadedChunkCache = {};
+/**
+* Hook to access translation function and locale metadata inside addon components. Automatically
+* synchronizes with host language switches and falls back to English. Supports static dictionary
+* resources or dynamic async locale loaders.
+*
+* @example
+*   ;```tsx
+*   import { useTranslation } from "@jchat/addon-sdk"
+*   import locales from "./locales"
+*
+*   export default function MyAddon() {
+*     const { t, locale, dir } = useTranslation(locales)
+*     return (
+*       <div dir={dir}>
+*         <h1>{t("welcome", { name: "Guest" })}</h1>
+*       </div>
+*     )
+*   }
+*   ```
+*
+* @param resourcesOrLoader - Addon-scoped translation dictionaries or async chunk loader.
+* @param fallbackLocale - Fallback language code when a string is missing (default: "en").
+*/
+function useTranslation(resourcesOrLoader = {}, fallbackLocale = "en") {
+	const { locale, dir, isRtl } = useLocale();
+	const isLoader = typeof resourcesOrLoader === "function";
+	const [dynamicResources, setDynamicResources] = useState(() => {
+		return isLoader ? loadedChunkCache : resourcesOrLoader;
+	});
+	const [isReady, setIsReady] = useState(!isLoader);
+	useEffect(() => {
+		if (!isLoader) {
+			setDynamicResources(resourcesOrLoader);
+			setIsReady(true);
+			return;
+		}
+		const loader = resourcesOrLoader;
+		const normLocale = locale.toLowerCase().split("-")[0];
+		if (loadedChunkCache[normLocale]) {
+			setDynamicResources((prev) => ({
+				...prev,
+				[normLocale]: loadedChunkCache[normLocale]
+			}));
+			setIsReady(true);
+			return;
+		}
+		let isMounted = true;
+		Promise.resolve(loader(normLocale)).then((dict) => {
+			if (!isMounted || !dict) return;
+			loadedChunkCache[normLocale] = dict;
+			setDynamicResources((prev) => ({
+				...prev,
+				[normLocale]: dict
+			}));
+			setIsReady(true);
+		}).catch((err) => {
+			console.warn(`[addon-sdk] Failed to dynamically load locale chunk "${normLocale}":`, err);
+			if (isMounted) setIsReady(true);
+		});
+		return () => {
+			isMounted = false;
+		};
+	}, [
+		isLoader,
+		resourcesOrLoader,
+		locale
+	]);
+	const translator = useMemo(() => {
+		return createTranslator(dynamicResources, locale, fallbackLocale);
+	}, [
+		dynamicResources,
+		locale,
+		fallbackLocale
+	]);
+	return {
+		t: useMemo(() => {
+			return (key, params) => translator(key, params, locale);
+		}, [translator, locale]),
+		locale,
+		dir,
+		isRtl,
+		isReady
+	};
+}
+//#endregion
+export { useTranslation as i, createTranslator as n, useLocale as r, LocaleContext as t };