@pie-players/pie-players-shared 0.2.0

package/src/i18n/index.ts

@@ -0,0 +1,26 @@
+/**
+ * I18n Module
+ *
+ * Internationalization system for PIE Players.
+ *
+ * @module @pie-players/pie-players-shared/i18n
+ */
+
+export {
+	BUNDLED_TRANSLATIONS,
+	getAvailableLocales,
+	isRTLLocale,
+	loadTranslations,
+} from "./loader";
+export { SimpleI18n } from "./simple-i18n";
+export type {
+	I18nConfig,
+	II18nService,
+	PluralTranslation,
+	TranslationBundle,
+} from "./types";
+export { useI18n } from "./use-i18n.svelte";
+export {
+	type UseI18nStandaloneConfig,
+	useI18nStandalone,
+} from "./use-i18n-standalone.svelte";

package/src/i18n/loader.ts

@@ -0,0 +1,156 @@
+/**
+ * Translation Loader
+ *
+ * Implements hybrid loading strategy:
+ * - English bundled with application
+ * - Other languages loaded on demand
+ *
+ * Part of PIE Players i18n system.
+ */
+
+// Import English translations (bundled)
+import enCommon from "./translations/en/common.json";
+import enToolkit from "./translations/en/toolkit.json";
+import enTools from "./translations/en/tools.json";
+import type { TranslationBundle } from "./types";
+
+// RTL locales
+const RTL_LOCALES = ["ar", "he", "fa", "ur"];
+
+/**
+ * Bundled English translations
+ * Available immediately without network request
+ */
+export const BUNDLED_TRANSLATIONS: Record<string, TranslationBundle> = {
+	en: {
+		locale: "en",
+		direction: "ltr",
+		translations: {
+			...flattenTranslations(enCommon),
+			...flattenTranslations(enToolkit),
+			...flattenTranslations(enTools),
+		},
+	},
+};
+
+const LOCALE_IMPORTS: Record<string, () => Promise<[any, any, any]>> = {
+	es: () =>
+		Promise.all([
+			import("./translations/es/common.json"),
+			import("./translations/es/toolkit.json"),
+			import("./translations/es/tools.json"),
+		]),
+	zh: () =>
+		Promise.all([
+			import("./translations/zh/common.json"),
+			import("./translations/zh/toolkit.json"),
+			import("./translations/zh/tools.json"),
+		]),
+	ar: () =>
+		Promise.all([
+			import("./translations/ar/common.json"),
+			import("./translations/ar/toolkit.json"),
+			import("./translations/ar/tools.json"),
+		]),
+};
+
+/**
+ * Load translations for a locale
+ *
+ * @param locale Locale code (e.g., 'en', 'es', 'zh', 'ar')
+ * @returns Translation bundle with flattened keys
+ */
+export async function loadTranslations(
+	locale: string,
+): Promise<TranslationBundle> {
+	// Return bundled English immediately
+	if (locale === "en") {
+		return BUNDLED_TRANSLATIONS.en;
+	}
+
+	const importer = LOCALE_IMPORTS[locale];
+	if (!importer) {
+		throw new Error(
+			`Translation files not found for locale: ${locale}. Ensure translation files exist in packages/players-shared/src/i18n/translations/${locale}/`,
+		);
+	}
+
+	// Lazy load other locales
+	try {
+		const [common, toolkit, tools] = await importer();
+
+		return {
+			locale,
+			direction: RTL_LOCALES.includes(locale) ? "rtl" : "ltr",
+			translations: {
+				...flattenTranslations(common.default || common),
+				...flattenTranslations(toolkit.default || toolkit),
+				...flattenTranslations(tools.default || tools),
+			},
+		};
+	} catch (error) {
+		console.error(`Failed to load translations for locale: ${locale}`, error);
+		throw new Error(
+			`Translation files not found for locale: ${locale}. Ensure translation files exist in packages/players-shared/src/i18n/translations/${locale}/`,
+		);
+	}
+}
+
+/**
+ * Flatten nested JSON to dot notation
+ *
+ * Converts:
+ * { "common": { "save": "Save" } }
+ *
+ * To:
+ * { "common.save": "Save" }
+ *
+ * @param obj Nested translation object
+ * @param prefix Current key prefix
+ * @param result Accumulated result
+ * @returns Flattened translation object
+ */
+function flattenTranslations(
+	obj: any,
+	prefix = "",
+	result: Record<string, any> = {},
+): Record<string, any> {
+	for (const [key, value] of Object.entries(obj)) {
+		const newKey = prefix ? `${prefix}.${key}` : key;
+
+		if (value && typeof value === "object" && !Array.isArray(value)) {
+			// Check if it's a plural form (has 'one' or 'other' keys)
+			if ("one" in value || "other" in value) {
+				// This is a plural translation, keep it as an object
+				result[newKey] = value;
+			} else {
+				// This is a nested object, flatten recursively
+				flattenTranslations(value, newKey, result);
+			}
+		} else {
+			// This is a leaf value
+			result[newKey] = value;
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Get available locales
+ *
+ * @returns Array of locale codes
+ */
+export function getAvailableLocales(): string[] {
+	return ["en", "es", "zh", "ar"];
+}
+
+/**
+ * Check if locale is RTL
+ *
+ * @param locale Locale code
+ * @returns True if locale is right-to-left
+ */
+export function isRTLLocale(locale: string): boolean {
+	return RTL_LOCALES.includes(locale);
+}

package/src/i18n/scripts/check-coverage.ts

@@ -0,0 +1,345 @@
+#!/usr/bin/env bun
+/**
+ * Translation Coverage Checker
+ *
+ * Validates that all locales have complete translations compared to the reference locale (English).
+ * Adapted from pie-qti's translation coverage checker for JSON-based translations.
+ *
+ * Usage:
+ *   bun run packages/players-shared/src/i18n/scripts/check-coverage.ts
+ *
+ * Exit codes:
+ *   0 - All translations complete
+ *   1 - Missing translations found
+ */
+
+import { readFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+interface CoverageResult {
+	locale: string;
+	coverage: number; // Percentage
+	totalKeys: number;
+	translatedKeys: number;
+	missing: string[];
+	extra: string[];
+	untranslated: string[];
+}
+
+/**
+ * Extract all keys from a translation object recursively
+ */
+function extractKeys(obj: any, prefix = ""): Set<string> {
+	const keys = new Set<string>();
+
+	for (const [key, value] of Object.entries(obj)) {
+		const fullKey = prefix ? `${prefix}.${key}` : key;
+
+		if (typeof value === "object" && value !== null) {
+			// Check if it's a plural form (has 'one' and 'other' keys)
+			if ("one" in value && "other" in value) {
+				keys.add(fullKey);
+			} else {
+				// Recurse for nested objects
+				const nested = extractKeys(value, fullKey);
+				nested.forEach((k) => keys.add(k));
+			}
+		} else {
+			keys.add(fullKey);
+		}
+	}
+
+	return keys;
+}
+
+/**
+ * Load all translations for a locale
+ */
+function loadLocaleTranslations(locale: string): Record<string, any> {
+	const basePath = resolve(__dirname, "../translations", locale);
+
+	try {
+		const common = JSON.parse(
+			readFileSync(join(basePath, "common.json"), "utf-8"),
+		);
+		const toolkit = JSON.parse(
+			readFileSync(join(basePath, "toolkit.json"), "utf-8"),
+		);
+		const tools = JSON.parse(
+			readFileSync(join(basePath, "tools.json"), "utf-8"),
+		);
+
+		return { ...common, ...toolkit, ...tools };
+	} catch (error) {
+		console.error(`Error loading translations for locale ${locale}:`, error);
+		throw error;
+	}
+}
+
+/**
+ * Get value at a dot-notation path
+ */
+function getValueAtPath(obj: any, path: string): any {
+	const keys = path.split(".");
+	let current = obj;
+
+	for (const key of keys) {
+		if (current && typeof current === "object" && key in current) {
+			current = current[key];
+		} else {
+			return undefined;
+		}
+	}
+
+	return current;
+}
+
+/**
+ * Check if a value looks like English (starts with uppercase letter)
+ */
+function looksLikeEnglish(value: any): boolean {
+	if (typeof value !== "string") return false;
+	return /^[A-Z]/.test(value) && value.length > 1;
+}
+
+/**
+ * Check translation coverage for a locale
+ */
+function checkLocale(
+	referenceKeys: Set<string>,
+	referenceTranslations: Record<string, any>,
+	targetLocale: string,
+): CoverageResult {
+	const targetTranslations = loadLocaleTranslations(targetLocale);
+	const targetKeys = extractKeys(targetTranslations);
+
+	// Missing keys (in reference but not in target)
+	const missing = Array.from(referenceKeys).filter(
+		(key) => !targetKeys.has(key),
+	);
+
+	// Extra keys (in target but not in reference)
+	const extra = Array.from(targetKeys).filter((key) => !referenceKeys.has(key));
+
+	// Potentially untranslated (same value as reference and looks like English)
+	const untranslated = Array.from(targetKeys).filter((key) => {
+		const refValue = getValueAtPath(referenceTranslations, key);
+		const targetValue = getValueAtPath(targetTranslations, key);
+
+		// For plural forms, check both 'one' and 'other'
+		if (typeof refValue === "object" && "one" in refValue) {
+			return (
+				refValue.one === targetValue.one &&
+				refValue.other === targetValue.other &&
+				looksLikeEnglish(targetValue.one)
+			);
+		}
+
+		if (typeof refValue === "string" && typeof targetValue === "string") {
+			return refValue === targetValue && looksLikeEnglish(targetValue);
+		}
+
+		return false;
+	});
+
+	const translatedKeys = referenceKeys.size - missing.length;
+	const coverage =
+		referenceKeys.size > 0 ? (translatedKeys / referenceKeys.size) * 100 : 0;
+
+	return {
+		locale: targetLocale,
+		coverage,
+		totalKeys: referenceKeys.size,
+		translatedKeys,
+		missing,
+		extra,
+		untranslated,
+	};
+}
+
+/**
+ * Format coverage report
+ */
+function formatReport(results: CoverageResult[]): string {
+	let report = "\n";
+	report += "┌─────────────────────────────────────────────────────┐\n";
+	report += "│      PIE Players Translation Coverage Report        │\n";
+	report += `│      Reference Locale: en (${results[0]?.totalKeys || 0} keys)                │\n`;
+	report += "└─────────────────────────────────────────────────────┘\n\n";
+
+	for (const result of results) {
+		report += `📋 Locale: ${result.locale}\n`;
+		report += "─────────────────────────────────────────────────────\n";
+
+		const coverageEmoji =
+			result.coverage === 100 ? "✅" : result.coverage >= 95 ? "⚠️ " : "❌";
+
+		report += `${coverageEmoji} Coverage: ${result.coverage.toFixed(1)}% `;
+		report += `(${result.translatedKeys}/${result.totalKeys} keys)\n\n`;
+
+		if (
+			result.coverage === 100 &&
+			result.extra.length === 0 &&
+			result.untranslated.length === 0
+		) {
+			report += "✅ All keys present and translated!\n\n";
+		} else {
+			if (result.missing.length > 0) {
+				report += `❌ Missing Keys (${result.missing.length}):\n`;
+				const displayCount = Math.min(result.missing.length, 15);
+				result.missing.slice(0, displayCount).forEach((key) => {
+					report += `  • ${key}\n`;
+				});
+				if (result.missing.length > displayCount) {
+					report += `  ... and ${result.missing.length - displayCount} more\n`;
+				}
+				report += "\n";
+			}
+
+			if (result.extra.length > 0) {
+				report += `⚠️  Extra Keys (${result.extra.length}) - Not in reference locale:\n`;
+				const displayCount = Math.min(result.extra.length, 10);
+				result.extra.slice(0, displayCount).forEach((key) => {
+					report += `  • ${key}\n`;
+				});
+				if (result.extra.length > displayCount) {
+					report += `  ... and ${result.extra.length - displayCount} more\n`;
+				}
+				report += "\n";
+			}
+
+			if (result.untranslated.length > 0) {
+				report += `⚠️  Potentially Untranslated (${result.untranslated.length}):\n`;
+				const displayCount = Math.min(result.untranslated.length, 10);
+				result.untranslated.slice(0, displayCount).forEach((key) => {
+					const value = getValueAtPath(
+						loadLocaleTranslations(result.locale),
+						key,
+					);
+					const displayValue =
+						typeof value === "string" ? value : JSON.stringify(value);
+					report += `  • ${key} = "${displayValue}"\n`;
+				});
+				if (result.untranslated.length > displayCount) {
+					report += `  ... and ${result.untranslated.length - displayCount} more\n`;
+				}
+				report += "\n";
+			}
+		}
+	}
+
+	// Summary
+	report += "════════════════════════════════════════════════════════\n";
+	report += "📊 Summary:\n";
+	report += "────────────────────────────────────────────────────────\n";
+
+	for (const result of results) {
+		const emoji =
+			result.coverage === 100 ? "✅" : result.coverage >= 95 ? "⚠️ " : "❌";
+		const status =
+			result.coverage === 100
+				? result.extra.length > 0 || result.untranslated.length > 0
+					? `Complete (${result.extra.length} extra, ${result.untranslated.length} untranslated)`
+					: "Complete"
+				: `Missing: ${result.missing.length}`;
+
+		report += `  ${result.locale}: ${result.coverage.toFixed(1)}% `;
+		report += `(${result.translatedKeys}/${result.totalKeys})  `;
+		report += `${emoji} ${status}\n`;
+	}
+
+	const avgCoverage =
+		results.reduce((sum, r) => sum + r.coverage, 0) / results.length;
+	report += `\nOverall: ${avgCoverage.toFixed(1)}% average coverage\n`;
+
+	const allComplete = results.every((r) => r.coverage === 100);
+	const hasIssues = results.some(
+		(r) => r.extra.length > 0 || r.untranslated.length > 0,
+	);
+
+	if (allComplete && !hasIssues) {
+		report += "✅ All translations complete!\n";
+	} else if (allComplete) {
+		report +=
+			"⚠️  All keys present, but some issues found (extra keys or untranslated)\n";
+	} else {
+		report += "❌ Some translations incomplete\n";
+	}
+
+	report += "════════════════════════════════════════════════════════\n";
+
+	return report;
+}
+
+/**
+ * Main entry point
+ */
+async function main() {
+	console.log("🔍 Checking translation coverage...\n");
+
+	try {
+		// Load reference locale (English)
+		const referenceTranslations = loadLocaleTranslations("en");
+		const referenceKeys = extractKeys(referenceTranslations);
+
+		console.log(`📖 Reference locale loaded: ${referenceKeys.size} keys\n`);
+
+		// Check all other locales
+		const targetLocales = ["es", "zh", "ar"];
+		const results: CoverageResult[] = [];
+
+		for (const locale of targetLocales) {
+			try {
+				const result = checkLocale(
+					referenceKeys,
+					referenceTranslations,
+					locale,
+				);
+				results.push(result);
+			} catch (error) {
+				console.error(`❌ Error checking locale ${locale}:`, error);
+				process.exit(1);
+			}
+		}
+
+		// Print report
+		const report = formatReport(results);
+		console.log(report);
+
+		// Exit with error if any locale is incomplete
+		const allComplete = results.every((r) => r.coverage === 100);
+		if (!allComplete) {
+			console.error(
+				"\n❌ Exiting with error code 1 (translations incomplete)\n",
+			);
+			process.exit(1);
+		}
+
+		// Warn if there are extra keys or untranslated strings
+		const hasIssues = results.some(
+			(r) => r.extra.length > 0 || r.untranslated.length > 0,
+		);
+		if (hasIssues) {
+			console.warn(
+				"\n⚠️  Warning: Some locales have extra keys or potentially untranslated strings.\n" +
+					"    Consider reviewing and cleaning up these issues.\n",
+			);
+			// Don't exit with error for warnings, just inform
+		}
+
+		console.log("✅ Translation coverage check passed!\n");
+		process.exit(0);
+	} catch (error) {
+		console.error("\n❌ Fatal error during coverage check:", error);
+		process.exit(1);
+	}
+}
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+	main();
+}