feat(i18n): 统一国际化系统架构,支持插件独立翻译 (#301)

* feat(i18n): 统一国际化系统架构,支持插件独立翻译

## 主要改动

### 核心架构
- 增强 LocaleService,支持插件命名空间翻译扩展
- 新增 editor-runtime/i18n 模块,提供 createPluginLocale/createPluginTranslator
- 新增 editor-core/tokens.ts,定义 LocaleServiceToken 等服务令牌
- 改进 PluginAPI 类型安全,使用 ServiceToken<T> 替代 any

### 编辑器本地化
- 扩展 en.ts/zh.ts 翻译文件,覆盖所有 UI 组件
- 新增 es.ts 西班牙语支持
- 重构 40+ 组件使用 useLocale() hook

### 插件本地化系统
- behavior-tree-editor: 新增 locales/ 和 useBTLocale hook
- material-editor: 新增 locales/ 和 useMaterialLocale hook
- particle-editor: 新增 locales/ 和 useParticleLocale hook
- tilemap-editor: 新增 locales/ 和 useTilemapLocale hook
- ui-editor: 新增 locales/ 和 useUILocale hook

### 类型安全改进
- 修复 Debug 工具使用公共接口替代 as any
- 修复 ChunkStreamingSystem 添加 forEachChunk 公共方法
- 修复 blueprint-editor 移除不必要的向后兼容代码

* fix(behavior-tree-editor): 使用 ServiceToken 模式修复服务解析

- 创建 BehaviorTreeServiceToken 遵循"谁定义接口,谁导出Token"原则
- 使用 ServiceToken.id (symbol) 注册服务到 ServiceContainer
- 更新 PluginSDKRegistry.resolveService 支持 ServiceToken 检测
- BehaviorTreeEditorPanel 现在使用类型安全的 PluginAPI.resolve

* fix(behavior-tree-editor): 使用 ServiceContainer.resolve 获取类注册的服务

* fix: 修复多个包的依赖和类型问题

- core: EntityDataCollector.getEntityDetails 使用 HierarchySystem 获取父实体
- ui-editor: 添加 @esengine/editor-runtime 依赖
- tilemap-editor: 添加 @esengine/editor-runtime 依赖
- particle-editor: 添加 @esengine/editor-runtime 依赖
This commit is contained in:
YHH
2025-12-09 18:04:03 +08:00
committed by GitHub
parent 995fa2d514
commit 1b0d38edce
103 changed files with 8015 additions and 1633 deletions

View File

@@ -0,0 +1,5 @@
/**
* Material Editor Hooks
* 材质编辑器钩子导出
*/
export { useMaterialLocale, translateMaterial } from './useMaterialLocale';

View File

@@ -0,0 +1,169 @@
/**
* Material Editor Locale Hook
* 材质编辑器语言钩子
*
* 提供材质编辑器专用的翻译功能
*/
import { useState, useEffect, useCallback } from 'react';
import { Core } from '@esengine/ecs-framework';
import { LocaleService } from '@esengine/editor-core';
import { en, zh, es } from '../locales';
type Locale = 'en' | 'zh' | 'es';
type TranslationParams = Record<string, string | number>;
const translations = { en, zh, es } as const;
/**
* 获取嵌套对象的值
* Get nested object value by dot notation key
*/
function getNestedValue(obj: Record<string, unknown>, key: string): string | undefined {
const keys = key.split('.');
let current: unknown = obj;
for (const k of keys) {
if (current && typeof current === 'object' && k in current) {
current = (current as Record<string, unknown>)[k];
} else {
return undefined;
}
}
return typeof current === 'string' ? current : undefined;
}
/**
* 替换参数占位符
* Replace parameter placeholders in string
*/
function interpolate(text: string, params?: TranslationParams): string {
if (!params) return text;
return text.replace(/\{\{(\w+)\}\}/g, (_, key) => {
const value = params[key];
return value !== undefined ? String(value) : `{{${key}}}`;
});
}
/**
* 尝试从 LocaleService 获取当前语言
* Try to get current locale from LocaleService
*/
function tryGetLocaleFromService(): Locale | null {
try {
// 尝试动态获取 LocaleService
const localeService = Core.services.tryResolve(LocaleService);
if (localeService?.getCurrentLocale) {
return localeService.getCurrentLocale() as Locale;
}
} catch {
// LocaleService 不可用
}
return null;
}
/**
* 订阅语言变化
* Subscribe to locale changes
*/
function subscribeToLocaleChanges(callback: (locale: Locale) => void): (() => void) | undefined {
try {
const localeService = Core.services.tryResolve(LocaleService);
if (localeService?.onChange) {
return localeService.onChange((newLocale) => {
callback(newLocale as Locale);
});
}
} catch {
// LocaleService 不可用
}
return undefined;
}
/**
* Hook for accessing material editor translations
* 访问材质编辑器翻译的 Hook
*
* @example
* ```tsx
* const { t, locale } = useMaterialLocale();
* return <button title={t('panel.saveTooltip')}>{t('panel.save')}</button>;
* ```
*/
export function useMaterialLocale() {
const [locale, setLocale] = useState<Locale>(() => {
return tryGetLocaleFromService() || 'en';
});
useEffect(() => {
// 初始化时获取当前语言
const currentLocale = tryGetLocaleFromService();
if (currentLocale) {
setLocale(currentLocale);
}
// 订阅语言变化
const unsubscribe = subscribeToLocaleChanges((newLocale) => {
setLocale(newLocale);
});
return () => {
unsubscribe?.();
};
}, []);
/**
* 翻译函数
* Translation function
*
* @param key - 翻译键,如 'panel.save'
* @param params - 插值参数
* @param fallback - 回退文本
*/
const t = useCallback((key: string, params?: TranslationParams, fallback?: string): string => {
const currentTranslations = translations[locale] || translations.en;
const value = getNestedValue(currentTranslations as Record<string, unknown>, key);
if (value) {
return interpolate(value, params);
}
// 如果当前语言没有,尝试英文
if (locale !== 'en') {
const enValue = getNestedValue(translations.en as Record<string, unknown>, key);
if (enValue) {
return interpolate(enValue, params);
}
}
// 返回 fallback 或 key 本身
return fallback || key;
}, [locale]);
return { t, locale, setLocale };
}
/**
* 非 React 环境下的翻译函数
* Translation function for non-React context
*/
export function translateMaterial(key: string, locale: Locale = 'en', params?: TranslationParams): string {
const currentTranslations = translations[locale] || translations.en;
const value = getNestedValue(currentTranslations as Record<string, unknown>, key);
if (value) {
return interpolate(value, params);
}
if (locale !== 'en') {
const enValue = getNestedValue(translations.en as Record<string, unknown>, key);
if (enValue) {
return interpolate(enValue, params);
}
}
return key;
}