@pie-players/pie-players-shared 0.2.0

package/src/i18n/scripts/scan-hardcoded.ts

@@ -0,0 +1,342 @@
+#!/usr/bin/env bun
+/**
+ * Hardcoded String Scanner
+ *
+ * Scans component files for hardcoded English strings that should use i18n.
+ * Adapted from pie-qti's hardcoded string scanner.
+ *
+ * Usage:
+ *   bun run packages/players-shared/src/i18n/scripts/scan-hardcoded.ts
+ *
+ * Options:
+ *   --path <dir>  - Directory to scan (default: packages/)
+ *   --fix         - Attempt to auto-fix issues (not implemented yet)
+ */
+
+import { readFileSync } from "fs";
+import { glob } from "glob";
+import { dirname, relative, resolve } from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+interface StringMatch {
+	file: string;
+	line: number;
+	context: string;
+	string: string;
+	suggestedKey: string | null;
+}
+
+/**
+ * Load all English translations
+ */
+function loadEnglishTranslations(): Record<string, string> {
+	const basePath = resolve(__dirname, "../translations/en");
+	const translations: Record<string, string> = {};
+
+	try {
+		const common = JSON.parse(
+			readFileSync(resolve(basePath, "common.json"), "utf-8"),
+		);
+		const toolkit = JSON.parse(
+			readFileSync(resolve(basePath, "toolkit.json"), "utf-8"),
+		);
+		const tools = JSON.parse(
+			readFileSync(resolve(basePath, "tools.json"), "utf-8"),
+		);
+
+		// Flatten all translations
+		flattenObject(common, "", translations);
+		flattenObject(toolkit, "", translations);
+		flattenObject(tools, "", translations);
+	} catch (error) {
+		console.error("Error loading English translations:", error);
+		throw error;
+	}
+
+	return translations;
+}
+
+/**
+ * Flatten nested object to dot notation
+ */
+function flattenObject(
+	obj: any,
+	prefix: string,
+	result: Record<string, string>,
+) {
+	for (const [key, value] of Object.entries(obj)) {
+		const fullKey = prefix ? `${prefix}.${key}` : key;
+
+		if (typeof value === "object" && value !== null) {
+			// Check for plural form
+			if ("one" in value && "other" in value) {
+				result[fullKey] = value.one as string;
+			} else {
+				flattenObject(value, fullKey, result);
+			}
+		} else if (typeof value === "string") {
+			result[fullKey] = value;
+		}
+	}
+}
+
+/**
+ * Find translation key for a given string value
+ */
+function findTranslationKey(
+	translations: Record<string, string>,
+	searchValue: string,
+): string | null {
+	// Exact match first
+	for (const [key, value] of Object.entries(translations)) {
+		if (value === searchValue) {
+			return key;
+		}
+	}
+
+	// Fuzzy match (case-insensitive)
+	const lowerSearch = searchValue.toLowerCase();
+	for (const [key, value] of Object.entries(translations)) {
+		if (value.toLowerCase() === lowerSearch) {
+			return key;
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Scan a file for hardcoded strings
+ */
+function scanFile(
+	filePath: string,
+	translations: Record<string, string>,
+): StringMatch[] {
+	const content = readFileSync(filePath, "utf-8");
+	const lines = content.split("\n");
+	const matches: StringMatch[] = [];
+
+	// Patterns to match quoted English strings
+	// Matches: "Text", 'Text', but ignores: i18n.t(...), class="...", etc.
+	const stringPattern = /["']([A-Z][A-Za-z\s,.:;!?'\-()]+)["']/g;
+
+	// Patterns to exclude (already using i18n, CSS classes, imports, etc.)
+	const excludePatterns = [
+		/i18n\./,
+		/import\s+/,
+		/from\s+['"]/,
+		/class[:=]/,
+		/className[:=]/,
+		/aria-\w+[:=]/,
+		/data-\w+[:=]/,
+		/id[:=]/,
+		/key[:=]/,
+		/name[:=]/,
+		/type[:=]/,
+		/href[:=]/,
+		/src[:=]/,
+		/alt[:=]/,
+		/title[:=]/,
+		/placeholder[:=]/,
+		/console\./,
+		/\/\//, // Comments
+		/\/\*/, // Block comments
+	];
+
+	lines.forEach((line, index) => {
+		// Skip lines that match exclude patterns
+		if (excludePatterns.some((pattern) => pattern.test(line))) {
+			return;
+		}
+
+		// Find all string matches in the line
+		let match;
+		while ((match = stringPattern.exec(line)) !== null) {
+			const string = match[1];
+
+			// Skip very short strings (likely not user-facing)
+			if (string.length < 3) continue;
+
+			// Skip strings that are mostly numbers or special characters
+			if (!/[a-zA-Z]{3,}/.test(string)) continue;
+
+			// Find corresponding translation key
+			const suggestedKey = findTranslationKey(translations, string);
+
+			matches.push({
+				file: filePath,
+				line: index + 1,
+				context: line.trim(),
+				string,
+				suggestedKey,
+			});
+		}
+	});
+
+	return matches;
+}
+
+/**
+ * Format scan results
+ */
+function formatResults(
+	matchesByFile: Map<string, StringMatch[]>,
+	rootDir: string,
+): string {
+	let report = "\n";
+	report += "┌─────────────────────────────────────────────────────┐\n";
+	report += "│      Hardcoded String Scanner                       │\n";
+	report += "└─────────────────────────────────────────────────────┘\n\n";
+
+	const fileCount = matchesByFile.size;
+	const totalMatches = Array.from(matchesByFile.values()).reduce(
+		(sum, m) => sum + m.length,
+		0,
+	);
+
+	if (fileCount === 0) {
+		report += "✅ No hardcoded strings found!\n\n";
+		return report;
+	}
+
+	// Sort files by number of matches (descending)
+	const sortedFiles = Array.from(matchesByFile.entries()).sort(
+		(a, b) => b[1].length - a[1].length,
+	);
+
+	for (const [file, matches] of sortedFiles) {
+		const relPath = relative(rootDir, file);
+		report += `📄 ${relPath} (${matches.length} match${matches.length === 1 ? "" : "es"})\n`;
+		report += "────────────────────────────────────────────────────────\n";
+
+		for (const match of matches) {
+			report += `  Line ${match.line}: ${match.context}\n`;
+			report += `           Found: "${match.string}"\n`;
+
+			if (match.suggestedKey) {
+				report += `           Use:   i18n?.t('${match.suggestedKey}') ?? '${match.suggestedKey}'\n`;
+			} else {
+				report += `           Note:  No matching translation key found. Consider adding to translations.\n`;
+			}
+
+			report += "\n";
+		}
+
+		report += "\n";
+	}
+
+	report += "════════════════════════════════════════════════════════\n";
+	report += "📊 Summary:\n";
+	report += "────────────────────────────────────────────────────────\n";
+	report += `  Total files scanned: ${fileCount}\n`;
+	report += `  Files with matches: ${fileCount}\n`;
+	report += `  Total hardcoded strings: ${totalMatches}\n\n`;
+	report += "⚠️  Recommendation: Replace hardcoded strings with i18n keys\n";
+	report += "    for proper internationalization support.\n";
+	report += "════════════════════════════════════════════════════════\n";
+
+	return report;
+}
+
+/**
+ * Find project root by looking for package.json with workspaces
+ */
+function findProjectRoot(): string {
+	let currentDir = process.cwd();
+	while (currentDir !== "/") {
+		try {
+			const pkgPath = resolve(currentDir, "package.json");
+			const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+			if (pkg.workspaces) {
+				return currentDir;
+			}
+		} catch {
+			// Continue searching
+		}
+		currentDir = dirname(currentDir);
+	}
+	// Fallback to script location's root
+	return resolve(__dirname, "../../../..");
+}
+
+/**
+ * Main entry point
+ */
+async function main() {
+	const args = process.argv.slice(2);
+	const pathArg = args.indexOf("--path");
+
+	// Find project root and default to scanning packages/
+	const projectRoot = findProjectRoot();
+	const defaultPath = resolve(projectRoot, "packages/");
+	const scanPath =
+		pathArg !== -1 ? resolve(projectRoot, args[pathArg + 1]) : defaultPath;
+
+	console.log("🔍 Scanning for hardcoded strings...\n");
+	console.log(`📂 Scan path: ${scanPath}\n`);
+
+	try {
+		// Load English translations for matching
+		const translations = loadEnglishTranslations();
+		console.log(
+			`📖 Loaded ${Object.keys(translations).length} translation keys\n`,
+		);
+
+		// Find all component files
+		const allFiles = await glob(`${scanPath}/**/*.{svelte,ts,tsx}`, {
+			absolute: true,
+		});
+
+		// Filter out unwanted directories manually
+		const files = allFiles.filter((file) => {
+			return (
+				!file.includes("/node_modules/") &&
+				!file.includes("/dist/") &&
+				!file.includes("/.svelte-kit/") &&
+				!file.includes("/build/") &&
+				!file.endsWith(".spec.ts") &&
+				!file.endsWith(".test.ts") &&
+				!file.includes("/scripts/")
+			);
+		});
+
+		console.log(`📁 Found ${files.length} files to scan\n`);
+
+		// Scan all files
+		const matchesByFile = new Map<string, StringMatch[]>();
+
+		for (const file of files) {
+			const matches = scanFile(file, translations);
+			if (matches.length > 0) {
+				matchesByFile.set(file, matches);
+			}
+		}
+
+		// Print results
+		const report = formatResults(matchesByFile, projectRoot);
+		console.log(report);
+
+		// Exit with warning if matches found
+		if (matchesByFile.size > 0) {
+			console.warn(
+				"\n⚠️  Found hardcoded strings. Consider using i18n for these strings.\n",
+			);
+			// Don't exit with error - this is informational only
+			process.exit(0);
+		}
+
+		console.log("✅ No hardcoded strings found!\n");
+		process.exit(0);
+	} catch (error) {
+		console.error("\n❌ Fatal error during scan:", error);
+		process.exit(1);
+	}
+}
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+	main();
+}

package/src/i18n/simple-i18n.ts

@@ -0,0 +1,236 @@
+/**
+ * Simple I18n Implementation
+ *
+ * Lightweight i18n without external dependencies.
+ * Used for standalone components that don't need the full service architecture.
+ */
+
+import type { I18nConfig, PluralTranslation, TranslationBundle } from "./types";
+
+/**
+ * Simple I18n class for standalone use
+ */
+export class SimpleI18n {
+	private locale: string = "en";
+	private fallbackLocale: string = "en";
+	private direction: "ltr" | "rtl" = "ltr";
+	private translations = new Map<string, TranslationBundle>();
+	private listeners = new Set<() => void>();
+	private loadingPromises = new Map<string, Promise<void>>();
+	private config: I18nConfig;
+
+	constructor(config: I18nConfig = {}) {
+		this.config = config;
+		this.fallbackLocale = config.fallbackLocale || "en";
+
+		// Load bundled translations
+		if (config.bundledTranslations) {
+			for (const [locale, bundle] of Object.entries(
+				config.bundledTranslations,
+			)) {
+				this.translations.set(locale, bundle);
+			}
+		}
+	}
+
+	/**
+	 * Initialize with locale
+	 */
+	async initialize(config: I18nConfig): Promise<void> {
+		Object.assign(this.config, config);
+
+		const locale = config.locale || this.detectBrowserLocale();
+		await this.setLocale(locale);
+	}
+
+	/**
+	 * Translate a key
+	 */
+	t(key: string, params?: Record<string, any>): string {
+		const translation = this.getTranslation(key);
+		return this.interpolate(translation as string, params);
+	}
+
+	/**
+	 * Translate with pluralization
+	 */
+	tn(key: string, count: number, params?: Record<string, any>): string {
+		const translation = this.getTranslation(key);
+
+		if (typeof translation === "object") {
+			const pluralForm = this.selectPluralForm(count, this.locale);
+			const text = translation[pluralForm] || translation.other;
+			return this.interpolate(text, { ...params, count });
+		}
+
+		return this.interpolate(translation as string, { ...params, count });
+	}
+
+	/**
+	 * Get current locale
+	 */
+	getLocale(): string {
+		return this.locale;
+	}
+
+	/**
+	 * Change locale
+	 */
+	async setLocale(locale: string): Promise<void> {
+		// Check if already loading
+		if (this.loadingPromises.has(locale)) {
+			await this.loadingPromises.get(locale);
+			return;
+		}
+
+		// Check if already loaded
+		if (this.translations.has(locale)) {
+			this.applyLocale(locale);
+			return;
+		}
+
+		// Load translations
+		const loadingPromise = this.loadTranslationsForLocale(locale);
+		this.loadingPromises.set(locale, loadingPromise);
+
+		try {
+			await loadingPromise;
+			this.applyLocale(locale);
+		} finally {
+			this.loadingPromises.delete(locale);
+		}
+	}
+
+	/**
+	 * Get current direction
+	 */
+	getDirection(): "ltr" | "rtl" {
+		return this.direction;
+	}
+
+	/**
+	 * Get available locales
+	 */
+	getAvailableLocales(): string[] {
+		return Array.from(this.translations.keys());
+	}
+
+	/**
+	 * Check if locale is loaded
+	 */
+	isLocaleLoaded(locale: string): boolean {
+		return this.translations.has(locale);
+	}
+
+	/**
+	 * Subscribe to changes
+	 */
+	subscribe(listener: () => void): () => void {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+
+	/**
+	 * Check if key exists
+	 */
+	hasKey(key: string): boolean {
+		const bundle = this.translations.get(this.locale);
+		return !!bundle?.translations[key];
+	}
+
+	private notifyListeners(): void {
+		for (const listener of this.listeners) {
+			listener();
+		}
+	}
+
+	private applyLocale(locale: string): void {
+		const bundle = this.translations.get(locale);
+		if (!bundle) return;
+
+		this.locale = locale;
+		this.direction = bundle.direction;
+
+		this.applyDOMDirection();
+		this.notifyListeners();
+	}
+
+	private applyDOMDirection(): void {
+		if (typeof document === "undefined") return;
+
+		document.documentElement.setAttribute("dir", this.direction);
+		document.documentElement.setAttribute("lang", this.locale);
+	}
+
+	private async loadTranslationsForLocale(locale: string): Promise<void> {
+		if (!this.config.loadTranslations) {
+			throw new Error(`No translation loader configured for locale: ${locale}`);
+		}
+
+		const bundle = await this.config.loadTranslations(locale);
+		this.translations.set(locale, bundle);
+	}
+
+	private getTranslation(key: string): string | PluralTranslation {
+		// Try current locale
+		const currentBundle = this.translations.get(this.locale);
+		if (currentBundle?.translations[key]) {
+			return currentBundle.translations[key];
+		}
+
+		// Try fallback locale
+		const fallbackBundle = this.translations.get(this.fallbackLocale);
+		if (fallbackBundle?.translations[key]) {
+			return fallbackBundle.translations[key];
+		}
+
+		// Missing key
+		if (this.config.onMissingKey) {
+			this.config.onMissingKey(key, this.locale);
+		}
+
+		return key;
+	}
+
+	private interpolate(text: string, params?: Record<string, any>): string {
+		if (!params) return text;
+
+		return text.replace(/\{(\w+)\}/g, (match, key) => {
+			return params[key]?.toString() || match;
+		});
+	}
+
+	private selectPluralForm(
+		count: number,
+		locale: string,
+	): keyof PluralTranslation {
+		// Use Intl.PluralRules if available
+		if (typeof Intl !== "undefined" && Intl.PluralRules) {
+			try {
+				const rules = new Intl.PluralRules(locale);
+				const category = rules.select(count);
+				return category as keyof PluralTranslation;
+			} catch {
+				// Fall through to simple rules
+			}
+		}
+
+		// Fallback to simple rules
+		if (count === 0) return "zero";
+		if (count === 1) return "one";
+		return "other";
+	}
+
+	private detectBrowserLocale(): string {
+		if (typeof navigator === "undefined") return "en";
+
+		const browserLang =
+			navigator.language ||
+			(navigator.languages && navigator.languages[0]) ||
+			"en";
+
+		return browserLang.split("-")[0];
+	}
+}

package/src/i18n/translations/ar/common.json

@@ -0,0 +1,36 @@
+{
+	"common": {
+		"save": "حفظ",
+		"cancel": "إلغاء",
+		"close": "إغلاق",
+		"loading": "جار التحميل...",
+		"error": "خطأ",
+		"retry": "إعادة المحاولة",
+		"back": "رجوع",
+		"next": "التالي",
+		"previous": "السابق",
+		"submit": "إرسال",
+		"continue": "متابعة",
+		"finish": "إنهاء",
+		"yes": "نعم",
+		"no": "لا",
+		"ok": "موافق",
+		"settings": "الإعدادات",
+		"language": "اللغة",
+		"theme": "المظهر",
+		"settings_aria": "فتح قائمة الإعدادات",
+		"rtl_notice": "اتجاه النص من اليمين إلى اليسار نشط",
+		"question": {
+			"one": "سؤال",
+			"other": "أسئلة"
+		},
+		"item": {
+			"one": "عنصر",
+			"other": "عناصر"
+		},
+		"character": {
+			"one": "حرف",
+			"other": "حروف"
+		}
+	}
+}

package/src/i18n/translations/ar/toolkit.json

@@ -0,0 +1,48 @@
+{
+	"assessment": {
+		"title": "التقييم",
+		"questions": {
+			"one": "{count} سؤال",
+			"other": "{count} أسئلة"
+		},
+		"question_of": "السؤال {current} من {total}",
+		"student_name": "اسم الطالب",
+		"fullscreen": "ملء الشاشة",
+		"exit_fullscreen": "الخروج من ملء الشاشة",
+		"enter_fullscreen_aria": "الدخول إلى ملء الشاشة",
+		"exit_fullscreen_aria": "الخروج من ملء الشاشة"
+	},
+	"accommodation": {
+		"audio": "صوت",
+		"audio_aria": "تبديل الصوت/تحويل النص إلى كلام",
+		"contrast": "التباين",
+		"contrast_aria": "تبديل تباين الألوان"
+	},
+	"navigation": {
+		"back": "← رجوع",
+		"next": "التالي ←",
+		"previous": "السابق",
+		"submit": "إرسال",
+		"navigate_to": "الانتقال إلى السؤال {index}",
+		"section": "القسم"
+	},
+	"section": {
+		"title": "بنية التقييم",
+		"add": "+ إضافة قسم",
+		"untitled": "قسم بدون عنوان",
+		"remove": "حذف القسم",
+		"items": {
+			"one": "{count} عنصر",
+			"other": "{count} عناصر"
+		},
+		"aria_label": "القسم: {title}",
+		"drop_zone": "إسقاط العناصر هنا",
+		"unassigned": "عناصر غير مخصصة",
+		"unassigned_instruction": "اسحب هذه العناصر إلى الأقسام",
+		"unassigned_item_aria": "سؤال غير مخصص: {title}"
+	},
+	"item": {
+		"load_error": "تعذر تحميل السؤال.",
+		"untitled": "بدون عنوان"
+	}
+}