191 lines
5.0 KiB
Markdown
191 lines
5.0 KiB
Markdown
# Crisp 多语言支持说明
|
||
|
||
## 🌍 自动语言适配
|
||
|
||
Crisp 客服聊天**会自动跟随应用的当前语言设置**显示对应的界面！
|
||
|
||
## 支持的语言
|
||
|
||
应用支持 7 种语言，Crisp 会自动切换到对应的界面语言：
|
||
|
||
| 应用语言 | Crisp 显示语言 | 语言代码 |
|
||
|---------|--------------|---------|
|
||
| 🇬🇧 English | English | `en` |
|
||
| 🇨🇳 中文 | 简体中文 | `zh` |
|
||
| 🇹🇼 繁體中文 | 繁体中文 | `zh-tw` |
|
||
| 🇪🇸 Español | Español | `es` |
|
||
| 🇯🇵 日本語 | 日本語 | `ja` |
|
||
| 🇷🇺 Русский | Русский | `ru` |
|
||
| 🇪🇪 Eesti | Eesti keel | `et` |
|
||
|
||
## 工作原理
|
||
|
||
### 1. 获取当前语言
|
||
```dart
|
||
final currentLanguage = KRLanguageUtils.getCurrentLanguageCode();
|
||
```
|
||
|
||
### 2. 映射到 Crisp Locale
|
||
```dart
|
||
String _getLocaleForCrisp(String languageCode) {
|
||
switch (languageCode) {
|
||
case 'zh_CN':
|
||
case 'zh':
|
||
return 'zh'; // 简体中文
|
||
case 'zh_TW':
|
||
case 'zhHant':
|
||
return 'zh-tw'; // 繁体中文
|
||
case 'es':
|
||
return 'es'; // 西班牙语
|
||
case 'ja':
|
||
return 'ja'; // 日语
|
||
case 'ru':
|
||
return 'ru'; // 俄语
|
||
case 'et':
|
||
return 'et'; // 爱沙尼亚语
|
||
case 'en':
|
||
default:
|
||
return 'en'; // 英语（默认）
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 初始化 Crisp
|
||
```dart
|
||
crispController = CrispController(
|
||
websiteId: AppConfig.getInstance().kr_website_id,
|
||
locale: locale, // 自动设置的语言
|
||
);
|
||
```
|
||
|
||
## 用户体验
|
||
|
||
1. **打开应用** → 应用读取系统语言或用户设置的语言
|
||
2. **进入"我的"页面**
|
||
3. **点击"客服"按钮**
|
||
4. **Crisp 自动以当前应用语言显示界面** ✨
|
||
|
||
### 示例流程
|
||
|
||
```
|
||
用户系统语言: 简体中文
|
||
↓
|
||
应用启动，检测语言: zh_CN
|
||
↓
|
||
用户点击"客服"
|
||
↓
|
||
Crisp 初始化，locale: 'zh'
|
||
↓
|
||
显示简体中文界面 🇨🇳
|
||
```
|
||
|
||
如果用户在应用内切换语言：
|
||
```
|
||
应用设置页面 → 切换语言到 "日本語"
|
||
↓
|
||
应用重新加载，语言: ja
|
||
↓
|
||
再次点击"客服"
|
||
↓
|
||
Crisp 显示日语界面 🇯🇵
|
||
```
|
||
|
||
## 语言切换
|
||
|
||
用户可以在应用的"设置"页面切换语言：
|
||
1. 进入"我的" → "语言切换"
|
||
2. 选择想要的语言
|
||
3. 应用界面立即切换
|
||
4. **下次打开客服，Crisp 也会自动切换到新语言**
|
||
|
||
## 技术细节
|
||
|
||
### 代码位置
|
||
- **控制器**: `lib/app/modules/kr_crisp_chat/controllers/kr_crisp_controller.dart`
|
||
- **语言工具**: `lib/app/localization/kr_language_utils.dart`
|
||
|
||
### 关键方法
|
||
```dart
|
||
// 在控制器初始化时调用
|
||
Future<void> kr_initializeCrisp() async {
|
||
final currentLanguage = KRLanguageUtils.getCurrentLanguageCode();
|
||
String locale = _getLocaleForCrisp(currentLanguage);
|
||
|
||
crispController = CrispController(
|
||
websiteId: AppConfig.getInstance().kr_website_id,
|
||
locale: locale,
|
||
);
|
||
}
|
||
```
|
||
|
||
## 扩展支持
|
||
|
||
如果需要添加新语言支持：
|
||
|
||
1. **在应用中添加新语言**（`kr_language_utils.dart`）
|
||
2. **在 Crisp 控制器中添加映射**（`_getLocaleForCrisp` 方法）
|
||
3. **确保 Crisp 支持该语言**（查看 [Crisp 支持的语言列表](https://docs.crisp.chat/guides/chatbox/languages/)）
|
||
|
||
### 添加新语言示例
|
||
|
||
假设要添加法语支持：
|
||
|
||
```dart
|
||
// 1. 在 KRLanguage enum 中添加
|
||
fr('🇫🇷', 'Français', 'fr')
|
||
|
||
// 2. 在 _getLocaleForCrisp 中添加映射
|
||
case 'fr':
|
||
return 'fr'; // 法语
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **系统语言优先**: 应用会优先使用用户在应用内设置的语言，如果没有设置，则使用系统语言
|
||
2. **默认语言**: 如果检测到不支持的语言，默认使用英语（`en`）
|
||
3. **实时生效**: 语言切换后，下次打开 Crisp 客服即可看到新语言界面
|
||
4. **无需重启**: 切换语言不需要重启应用
|
||
|
||
## 验证方法
|
||
|
||
### 测试步骤
|
||
1. 打开应用
|
||
2. 进入"我的" → "语言切换"
|
||
3. 依次选择不同语言
|
||
4. 每次选择后，点击"客服"按钮
|
||
5. 验证 Crisp 界面语言是否正确切换
|
||
|
||
### 预期结果
|
||
- ✅ 界面文字使用选定的语言
|
||
- ✅ 输入框提示文字使用对应语言
|
||
- ✅ 系统消息使用对应语言
|
||
- ✅ 按钮文字使用对应语言
|
||
|
||
## 常见问题
|
||
|
||
### Q: 为什么我切换了语言，Crisp 还是英文？
|
||
A: 请确保：
|
||
1. 已关闭之前的 Crisp 窗口
|
||
2. 重新点击"客服"按钮
|
||
3. Crisp 会使用新的语言初始化
|
||
|
||
### Q: Crisp 支持哪些语言？
|
||
A: Crisp 官方支持 30+ 种语言，包括所有主流语言。查看完整列表：https://docs.crisp.chat/guides/chatbox/languages/
|
||
|
||
### Q: 可以强制使用某个语言吗？
|
||
A: 当前实现会自动跟随应用语言。如需强制使用某个语言，可以在初始化时硬编码 locale：
|
||
```dart
|
||
crispController = CrispController(
|
||
websiteId: AppConfig.getInstance().kr_website_id,
|
||
locale: 'zh', // 强制使用简体中文
|
||
);
|
||
```
|
||
|
||
## 总结
|
||
|
||
✅ **自动化**: Crisp 完全自动跟随应用语言
|
||
✅ **全面支持**: 支持应用所有 7 种语言
|
||
✅ **用户友好**: 无需用户手动设置
|
||
✅ **实时切换**: 切换语言后立即生效
|
||
✅ **可扩展**: 易于添加新语言支持
|