# 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 种语言
✅ **用户友好**: 无需用户手动设置
✅ **实时切换**: 切换语言后立即生效
✅ **可扩展**: 易于添加新语言支持