@pie-players/pie-players-shared 0.2.0

package/src/i18n/translations/zh/tools.json

@@ -0,0 +1,109 @@
+{
+	"tool": {
+		"calculator": "计算器",
+		"calculator_aria": "打开计算器",
+		"graph": "图表",
+		"graph_aria": "打开图表工具",
+		"periodic_table": "元素周期表",
+		"periodic_table_aria": "打开元素周期表",
+		"protractor": "量角器",
+		"protractor_aria": "打开量角器",
+		"ruler": "尺子",
+		"ruler_aria": "打开尺子",
+		"line_reader": "行阅读器",
+		"line_reader_aria": "打开行阅读器",
+		"magnifier": "文本放大镜",
+		"magnifier_aria": "打开文本放大镜",
+		"text_to_speech": "文字转语音",
+		"text_to_speech_aria": "打开文字转语音",
+		"color_scheme": "配色方案",
+		"color_scheme_aria": "打开配色方案选择器",
+		"annotation": "注释",
+		"annotation_aria": "打开注释工具栏",
+		"answer_eliminator": "答案消除器"
+	},
+	"tts": {
+		"title": "文字转语音",
+		"close_aria": "关闭文字转语音",
+		"failed_init": "初始化 TTS 失败",
+		"initializing": "初始化中...",
+		"select_text": "选择页面上的文本以朗读。",
+		"selected": "已选择 {count} {character}",
+		"speed": "速度：",
+		"rate_slow": "慢",
+		"rate_slower": "较慢",
+		"rate_normal": "正常",
+		"rate_faster": "较快",
+		"rate_fast": "快",
+		"rate_very_fast": "很快",
+		"play": "播放",
+		"pause": "暂停",
+		"resume": "继续",
+		"stop": "停止",
+		"speaking": "朗读中...",
+		"paused": "已暂停"
+	},
+	"calculator": {
+		"title": "计算器",
+		"aria_label": "计算器工具 - 使用 Alt+箭头键移动，Escape 关闭",
+		"settings": "计算器设置",
+		"close": "关闭计算器",
+		"settings_title": "计算器设置",
+		"type": "计算器类型",
+		"basic": "基础",
+		"scientific": "科学",
+		"graphing": "图形",
+		"ti_84": "TI-84 Plus CE",
+		"ti_108": "TI-108 小学",
+		"ti_34": "TI-34 MultiView",
+		"configuration": "配置",
+		"config_help": "这些设置对测试很有用。在生产环境中可能对学生隐藏或限制。",
+		"restricted_mode": "受限模式（测试模式）",
+		"angle_mode": "角度模式",
+		"degrees": "度数",
+		"radians": "弧度",
+		"qwerty": "QWERTY 键盘",
+		"screen_reader": "屏幕阅读器支持",
+		"accessible_display": "无障碍显示",
+		"settings_menu": "设置菜单",
+		"notes": "笔记",
+		"folders": "文件夹",
+		"sliders": "滑块",
+		"display_mode": "显示模式",
+		"classic": "经典",
+		"mathprint": "MathPrint"
+	},
+	"color_scheme": {
+		"title": "配色方案",
+		"description": "选择配色方案以提高可读性并减少眼睛疲劳。",
+		"close_aria": "关闭配色方案选择器",
+		"select_aria": "选择配色方案",
+		"default": "默认",
+		"default_desc": "标准 PIE 颜色",
+		"black_on_white": "黑底白字",
+		"black_on_white_desc": "高对比度便于阅读",
+		"white_on_black": "白底黑字",
+		"white_on_black_desc": "反向高对比度",
+		"rose_on_green": "玫瑰色底绿字",
+		"rose_on_green_desc": "减少眩光",
+		"yellow_on_blue": "黄底蓝字",
+		"yellow_on_blue_desc": "高对比度替代方案",
+		"black_on_rose": "黑底玫瑰色字",
+		"black_on_rose_desc": "温暖的背景",
+		"light_gray_on_dark_gray": "浅灰底深灰字",
+		"light_gray_on_dark_gray_desc": "降低亮度"
+	},
+	"annotation": {
+		"yellow_aria": "黄色高亮",
+		"pink_aria": "粉色高亮",
+		"blue_aria": "蓝色高亮",
+		"green_aria": "绿色高亮",
+		"read_selection": "朗读选择",
+		"dictionary": "字典查询",
+		"translation": "翻译请求",
+		"clear": "清除高亮"
+	},
+	"ruler": {
+		"switched_to": "已切换到 {unit}"
+	}
+}

package/src/i18n/types.ts

@@ -0,0 +1,66 @@
+/**
+ * I18n Type Definitions
+ *
+ * Shared types for internationalization system.
+ * Defined in players-shared to avoid circular dependencies.
+ */
+
+/**
+ * Plural translation forms
+ * Follows ICU MessageFormat plural rules
+ */
+export interface PluralTranslation {
+	zero?: string;
+	one: string;
+	few?: string;
+	many?: string;
+	other: string;
+}
+
+/**
+ * Translation bundle structure
+ */
+export interface TranslationBundle {
+	locale: string;
+	translations: Record<string, string | PluralTranslation>;
+	direction: "ltr" | "rtl";
+}
+
+/**
+ * I18n configuration
+ */
+export interface I18nConfig {
+	/** Initial locale (default: browser language) */
+	locale?: string;
+
+	/** Fallback locale (default: 'en') */
+	fallbackLocale?: string;
+
+	/** Translation loader function */
+	loadTranslations?: (locale: string) => Promise<TranslationBundle>;
+
+	/** Bundled translations (for hybrid loading) */
+	bundledTranslations?: Record<string, TranslationBundle>;
+
+	/** Missing key handler */
+	onMissingKey?: (key: string, locale: string) => void;
+
+	/** Debug mode */
+	debug?: boolean;
+}
+
+/**
+ * I18nService interface
+ */
+export interface II18nService {
+	initialize(config: I18nConfig): Promise<void>;
+	t(key: string, params?: Record<string, any>): string;
+	tn(key: string, count: number, params?: Record<string, any>): string;
+	getLocale(): string;
+	setLocale(locale: string): Promise<void>;
+	getDirection(): "ltr" | "rtl";
+	getAvailableLocales(): string[];
+	isLocaleLoaded(locale: string): boolean;
+	subscribe(listener: () => void): () => void;
+	hasKey(key: string): boolean;
+}

package/src/i18n/use-i18n-standalone.svelte.ts

@@ -0,0 +1,184 @@
+/**
+ * Standalone i18n Composable
+ *
+ * Lightweight i18n for standalone components that don't use the service architecture.
+ * Creates its own internal I18nService instance with hybrid loading.
+ *
+ * Use this when:
+ * - Building standalone components (tools, players) without full toolkit integration
+ * - You want simple i18n without dependency injection
+ *
+ * Use `useI18n()` when:
+ * - Working within the full assessment toolkit architecture
+ * - You need centralized locale management across the application
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useI18nStandalone } from '@pie-players/pie-players-shared/i18n';
+ *
+ *   const i18n = useI18nStandalone({ locale: 'en' });
+ * </script>
+ *
+ * <button>{i18n.t('common.save')}</button>
+ * <span dir={i18n.direction}>{i18n.tn('assessment.questions', 10)}</span>
+ * ```
+ */
+
+import { BUNDLED_TRANSLATIONS, loadTranslations } from "./loader";
+import { SimpleI18n } from "./simple-i18n";
+
+/**
+ * Standalone i18n configuration
+ */
+export interface UseI18nStandaloneConfig {
+	/** Initial locale (default: browser language) */
+	locale?: string;
+	/** Fallback locale (default: 'en') */
+	fallbackLocale?: string;
+	/** Debug mode */
+	debug?: boolean;
+}
+
+/**
+ * Create a standalone i18n instance
+ *
+ * @param config Configuration options
+ * @returns Reactive i18n interface
+ */
+export function useI18nStandalone(config: UseI18nStandaloneConfig = {}) {
+	let locale = $state<string>(config.locale || "en");
+	let direction = $state<"ltr" | "rtl">("ltr");
+	let isLoading = $state(false);
+
+	// Create internal service instance
+	const service = new SimpleI18n({
+		locale: config.locale,
+		fallbackLocale: config.fallbackLocale || "en",
+		bundledTranslations: BUNDLED_TRANSLATIONS,
+		loadTranslations,
+		debug: config.debug,
+	});
+
+	// Initialize service
+	$effect(() => {
+		service
+			.initialize({
+				locale: config.locale,
+				fallbackLocale: config.fallbackLocale || "en",
+				bundledTranslations: BUNDLED_TRANSLATIONS,
+				loadTranslations,
+				debug: config.debug,
+			})
+			.then(() => {
+				locale = service.getLocale();
+				direction = service.getDirection();
+			});
+	});
+
+	// Subscribe to service changes
+	$effect(() => {
+		const unsubscribe = service.subscribe(() => {
+			locale = service.getLocale();
+			direction = service.getDirection();
+		});
+
+		return unsubscribe;
+	});
+
+	/**
+	 * Translate a key with optional interpolation
+	 */
+	function t(key: string, params?: Record<string, any>): string {
+		return service.t(key, params);
+	}
+
+	/**
+	 * Translate with pluralization
+	 */
+	function tn(
+		key: string,
+		count: number,
+		params?: Record<string, any>,
+	): string {
+		return service.tn(key, count, params);
+	}
+
+	/**
+	 * Change locale (async)
+	 */
+	async function setLocale(newLocale: string): Promise<void> {
+		isLoading = true;
+		try {
+			await service.setLocale(newLocale);
+		} finally {
+			isLoading = false;
+		}
+	}
+
+	return {
+		/**
+		 * Current locale (reactive)
+		 */
+		get locale() {
+			return locale;
+		},
+
+		/**
+		 * Current text direction (reactive)
+		 */
+		get direction() {
+			return direction;
+		},
+
+		/**
+		 * Loading state (reactive)
+		 */
+		get isLoading() {
+			return isLoading;
+		},
+
+		/**
+		 * Translate function
+		 */
+		t,
+
+		/**
+		 * Translate with pluralization
+		 */
+		tn,
+
+		/**
+		 * Change locale
+		 */
+		setLocale,
+
+		/**
+		 * Get available locales
+		 */
+		get availableLocales() {
+			return service.getAvailableLocales();
+		},
+
+		/**
+		 * Check if locale is loaded
+		 */
+		isLocaleLoaded(loc: string): boolean {
+			return service.isLocaleLoaded(loc);
+		},
+
+		/**
+		 * Check if translation key exists
+		 */
+		hasKey(key: string): boolean {
+			return service.hasKey(key);
+		},
+
+		/**
+		 * Access underlying service (for advanced use cases)
+		 */
+		get service() {
+			return service;
+		},
+	};
+}

package/src/i18n/use-i18n.svelte.ts

@@ -0,0 +1,163 @@
+/**
+ * Svelte 5 Composable for i18n
+ *
+ * Provides reactive translation functions and locale state.
+ * Uses Svelte 5 runes for reactivity.
+ *
+ * Usage in a Svelte 5 component:
+ * ```svelte
+ * <script lang="ts">
+ *   import { useI18n } from '@pie-players/pie-players-shared/i18n';
+ *
+ *   let { player } = $props();
+ *   const i18n = useI18n(() => player.getI18nService());
+ * </script>
+ *
+ * <button>{i18n.t('common.save')}</button>
+ * <span dir={i18n.direction}>
+ *   {i18n.tn('assessment.questions', totalQuestions)}
+ * </span>
+ * ```
+ */
+
+import type { II18nService } from "./types";
+
+/**
+ * Svelte 5 composable for internationalization
+ *
+ * @param getService - Function that returns the I18nService instance (reactive)
+ * @returns Object with reactive locale, direction, and translation functions
+ */
+export function useI18n(getService: () => II18nService | undefined) {
+	let locale = $state<string>("en");
+	let direction = $state<"ltr" | "rtl">("ltr");
+	let isLoading = $state(false);
+
+	// Get service instance reactively
+	const service = $derived(getService());
+
+	// Subscribe to service changes
+	$effect(() => {
+		if (service) {
+			// Initialize state from service
+			locale = service.getLocale();
+			direction = service.getDirection();
+
+			// Subscribe to changes
+			const unsubscribe = service.subscribe(() => {
+				locale = service.getLocale();
+				direction = service.getDirection();
+			});
+
+			// Cleanup subscription
+			return unsubscribe;
+		}
+		// Return no-op cleanup if service is undefined
+		return () => {};
+	});
+
+	/**
+	 * Translate a key with optional interpolation
+	 *
+	 * @param key Translation key (e.g., 'common.save')
+	 * @param params Optional parameters for interpolation
+	 * @returns Translated string
+	 */
+	function t(key: string, params?: Record<string, any>): string {
+		if (!service) return key;
+		return service.t(key, params);
+	}
+
+	/**
+	 * Translate with pluralization
+	 *
+	 * @param key Translation key
+	 * @param count Count for pluralization
+	 * @param params Optional parameters for interpolation
+	 * @returns Translated string with plural form
+	 */
+	function tn(
+		key: string,
+		count: number,
+		params?: Record<string, any>,
+	): string {
+		if (!service) return key;
+		return service.tn(key, count, params);
+	}
+
+	/**
+	 * Change locale (async)
+	 *
+	 * @param newLocale Locale code (e.g., 'en', 'es', 'zh', 'ar')
+	 */
+	async function setLocale(newLocale: string): Promise<void> {
+		if (!service) return;
+
+		isLoading = true;
+		try {
+			await service.setLocale(newLocale);
+		} finally {
+			isLoading = false;
+		}
+	}
+
+	// Return reactive getters and functions
+	return {
+		/**
+		 * Current locale (reactive)
+		 */
+		get locale() {
+			return locale;
+		},
+
+		/**
+		 * Current text direction (reactive)
+		 */
+		get direction() {
+			return direction;
+		},
+
+		/**
+		 * Loading state (reactive)
+		 */
+		get isLoading() {
+			return isLoading;
+		},
+
+		/**
+		 * Translate function
+		 */
+		t,
+
+		/**
+		 * Translate with pluralization
+		 */
+		tn,
+
+		/**
+		 * Change locale
+		 */
+		setLocale,
+
+		/**
+		 * Get available locales
+		 */
+		get availableLocales() {
+			return service?.getAvailableLocales() || [];
+		},
+
+		/**
+		 * Check if locale is loaded
+		 */
+		isLocaleLoaded(loc: string): boolean {
+			return service?.isLocaleLoaded(loc) || false;
+		},
+
+		/**
+		 * Check if translation key exists
+		 */
+		hasKey(key: string): boolean {
+			return service?.hasKey(key) || false;
+		},
+	};
+}