feat(i18n): Implement server-side internationalization support

- Added ServerI18nManager to handle translations and locale settings on the server.
- Integrated server-side translations into templates, reducing language flashing on initial load.
- Created API endpoints for setting and getting user language preferences.
- Enhanced client-side i18n handling to work seamlessly with server-rendered content.
- Updated various templates to utilize the new translation system.
- Added mixed i18n handler to coordinate server and client translations, improving user experience.
- Expanded translation files to include initialization messages for various components.
This commit is contained in:
Will Miao
2025-08-30 16:56:56 +08:00
parent 3c9e402bc0
commit 29160bd6e5
14 changed files with 775 additions and 42 deletions

View File

@@ -0,0 +1,155 @@
# 服务端渲染 I18n 实现总结
## 问题分析
原始的纯前端i18n方案存在以下问题
1. **语言闪烁问题**:页面首次加载时会显示英文,然后才切换到用户设置的语言
2. **首屏渲染慢**需要等待JavaScript加载并执行才能显示正确的语言
3. **SEO不友好**:搜索引擎爬虫看到的是默认语言内容
## 解决方案
实现了**混合式服务端+客户端i18n系统**
### 1. 服务端 I18n 管理器 (`py/services/server_i18n.py`)
**功能**
- 解析JavaScript格式的语言文件`.js`文件中的`export const`语法)
- 提供Jinja2模板过滤器支持
- 支持嵌套键值查找(如`header.navigation.loras`
- 支持参数插值(`{param}``{{param}}`语法)
- 自动回退到英语翻译
**核心特性**
```python
# 设置语言
server_i18n.set_locale('zh-CN')
# 获取翻译
title = server_i18n.get_translation('header.appTitle')
# 创建模板过滤器
template_filter = server_i18n.create_template_filter()
```
### 2. 模板层面的改进
**修改的文件**
- `templates/base.html` - 添加服务端翻译数据预设
- `templates/components/header.html` - 使用服务端翻译
- `templates/loras.html` - 标题和初始化消息服务端渲染
**模板语法示例**
```html
<!-- 服务端渲染 -->
<span class="app-title">{{ t('header.appTitle') }}</span>
<!-- 动态内容仍使用客户端 -->
<span data-i18n="dynamic.content">Content</span>
```
### 3. 路由层面的集成
**修改的文件**
- `py/routes/base_model_routes.py` - 基础模型路由
- `py/routes/recipe_routes.py` - 配方路由
- `py/routes/stats_routes.py` - 统计路由
- `py/routes/misc_routes.py` - 添加语言设置API
**路由实现**
```python
# 获取用户语言设置
user_language = settings.get('language', 'en')
# 设置服务端i18n语言
server_i18n.set_locale(user_language)
# 为模板环境添加i18n过滤器
self.template_env.filters['t'] = server_i18n.create_template_filter()
# 模板上下文
template_context = {
'user_language': user_language,
't': server_i18n.get_translation,
'server_i18n': server_i18n,
'common_translations': {
'loading': server_i18n.get_translation('common.status.loading'),
# ... 其他常用翻译
}
}
```
### 4. 前端混合处理器 (`static/js/utils/mixedI18n.js`)
**功能**
- 协调服务端和客户端翻译
- 避免重复翻译已经服务端渲染的内容
- 处理动态内容的客户端翻译
- 支持语言切换(触发页面重新加载)
**工作流程**
1. 检查`window.__SERVER_TRANSLATIONS__`获取服务端预设的翻译
2. 导入客户端i18n模块
3. 同步客户端和服务端的语言设置
4. 只翻译需要客户端处理的剩余元素
### 5. API支持
**新增API端点**
- `POST /api/set-language` - 设置用户语言偏好
- `GET /api/get-language` - 获取当前语言设置
### 6. 语言文件扩展
**新增翻译内容**
```javascript
initialization: {
loras: {
title: 'Initializing LoRA Manager',
message: 'Scanning and building LoRA cache...'
},
checkpoints: {
title: 'Initializing Checkpoint Manager',
message: 'Scanning and building checkpoint cache...'
},
// ... 其他模块的初始化消息
}
```
## 实现效果
### 🎯 解决的问题
1. **✅ 消除语言闪烁**:首屏内容直接以用户设置的语言渲染
2. **✅ 提升首屏性能**关键UI元素无需等待JavaScript即可显示正确语言
3. **✅ 改善SEO**:搜索引擎可以抓取到本地化内容
4. **✅ 保持兼容性**动态内容仍使用前端i18n现有功能不受影响
### 🔧 技术优势
1. **渐进式增强**:服务端渲染提供基础体验,客户端增强交互功能
2. **智能协调**:避免重复翻译,优化性能
3. **回退机制**:如果服务端翻译失败,自动回退到客户端翻译
4. **统一管理**:使用相同的语言文件,保持翻译一致性
### 🎨 用户体验提升
- **即时显示**:页面打开即显示用户语言,无等待时间
- **无缝切换**:语言切换通过页面重载,确保所有内容都正确翻译
- **一致性**:服务端和客户端使用相同翻译源,避免不一致
## 部署说明
1. 现有的JavaScript语言文件无需修改
2. 服务端会自动解析并缓存翻译数据
3. 用户的语言偏好保存在`settings.json`
4. 页面刷新后自动应用服务端翻译
## 兼容性
- ✅ 保持现有前端i18n功能完整
- ✅ 支持所有现有语言en, zh-CN, zh-TW, ru, de, ja, ko, fr, es
- ✅ 向后兼容现有的`data-i18n`属性
- ✅ 支持复杂的动态内容翻译
此实现完美解决了原始问题,在不破坏现有功能的前提下,显著提升了用户体验和应用性能。