bc3ebc006c
重构i18n，现在game configs的配表，除了姓名这种外，都是统一的配表了。 对应的配表的名称和desc需要去i18n里取，但是其他配置不需要重复配置了。 这大大简化了之后新增i18n的心智负担。
338 lines
8.1 KiB
Markdown
338 lines
8.1 KiB
Markdown
# 新增 i18n 测试说明
|
||
|
||
## 概述
|
||
|
||
针对你完成的 `src/classes/` 本地化工作，我添加了以下测试逻辑来确保国际化的质量和完整性。
|
||
|
||
## 新增测试文件
|
||
|
||
### 1. ✅ `test_i18n_duplicates.py` - PO 文件重复项检查
|
||
|
||
**状态**: 已创建并通过测试
|
||
|
||
**功能**:
|
||
- 检查中英文 PO 文件中是否有重复的 msgid
|
||
- 检查中英文 msgid 数量是否一致
|
||
- 检查中英文 msgid 键是否完全匹配
|
||
|
||
**特点**:
|
||
- 独立运行，不依赖 conftest.py
|
||
- 快速执行（< 5秒）
|
||
- 适合 pre-commit hook
|
||
|
||
**运行方式**:
|
||
```bash
|
||
python tests/test_i18n_duplicates.py
|
||
```
|
||
|
||
**当前结果**: ✅ 所有测试通过 (4/4)
|
||
- 中文: 519 个 msgid，无重复
|
||
- 英文: 519 个 msgid，无重复
|
||
- 中英文完全匹配
|
||
|
||
---
|
||
|
||
### 2. ⚠️ `test_i18n_po_quality.py` - PO 文件质量和代码检查
|
||
|
||
**状态**: 已创建，发现需要修复的问题
|
||
|
||
**功能**:
|
||
- 🔍 检测硬编码的中文字符串（应使用 `t()` 函数）
|
||
- 🔍 检测代码中使用但 PO 文件中未定义的翻译键
|
||
- 🔍 检测格式化参数不一致问题
|
||
|
||
**特点**:
|
||
- 使用 AST 解析器静态分析代码
|
||
- 不依赖项目导入，避免循环依赖
|
||
- 提供详细的问题定位信息
|
||
|
||
**运行方式**:
|
||
```bash
|
||
python tests/test_i18n_po_quality.py
|
||
```
|
||
|
||
**当前发现的问题**:
|
||
|
||
#### 1. 硬编码中文字符串 (~460 处)
|
||
主要在以下文件:
|
||
- `classes/appearance.py` - 外貌描述数据
|
||
- `classes/alignment.py` - 枚举注释
|
||
- `classes/animal.py` - 动物信息
|
||
|
||
**分析**:
|
||
- 大部分是**数据文件**中的内容（如 appearance.py 中的外貌描述）
|
||
- 一些是**枚举常量的注释**（可接受）
|
||
- 需要评估哪些应该本地化，哪些可以作为数据保留
|
||
|
||
**建议优先级**:
|
||
- 🔴 高优先级: 用户可见的运行时文本
|
||
- 🟡 中优先级: 数据文件中的描述
|
||
- 🟢 低优先级: 注释和调试信息
|
||
|
||
#### 2. 缺失的翻译键 (9 个)
|
||
|
||
```
|
||
❌ 代码中使用但 PO 文件中未定义:
|
||
- '\n(Selecting {replace} will sell old {label})'
|
||
- '\n--- Current Effects Detail ---'
|
||
- '\n【Related Avatars Information】'
|
||
- 'Current {label}: {old_info}\n{new_desc}'
|
||
- 'Event Type: Mysterious Auction\nScene Setting: ...'
|
||
- 'Unsupported item type: {item_type}'
|
||
- '{avatar} gained cultivation experience +{exp} points'
|
||
- '{winner} defeated {loser}'
|
||
- '【Current Situation】: {context}\n\n{choices}'
|
||
```
|
||
|
||
**修复方法**: 需要在两个 PO 文件中添加这些 msgid 及其翻译
|
||
|
||
#### 3. 格式化参数一致性
|
||
✅ **当前状态**: 所有翻译的格式化参数都一致
|
||
|
||
---
|
||
|
||
### 3. 📝 `test_i18n_classes_coverage.py` - Classes 模块深度测试
|
||
|
||
**状态**: 已创建，需要修复项目导入问题后运行
|
||
|
||
**功能**:
|
||
- 测试各种枚举的翻译（境界、性别、阵营等）
|
||
- 测试动作名称翻译
|
||
- 测试效果名称翻译
|
||
- 测试中英文切换
|
||
|
||
**特点**:
|
||
- 全面测试 classes 模块的国际化
|
||
- 包含实际的翻译功能测试
|
||
- 验证参数化翻译
|
||
|
||
**阻塞问题**:
|
||
```python
|
||
ImportError: cannot import name 'EFFECT_DESC_MAP' from 'src.classes.effect.desc'
|
||
```
|
||
|
||
**建议**: 修复项目导入后再启用此测试
|
||
|
||
---
|
||
|
||
### 4. 📚 文档
|
||
|
||
#### `README_i18n_tests.md` - 测试套件完整文档
|
||
详细说明了:
|
||
- 所有测试的用途和运行方式
|
||
- 快速检查清单
|
||
- 修复常见问题的指南
|
||
- CI/CD 集成示例
|
||
- 最佳实践
|
||
|
||
#### `README_i18n_duplicates.md` - 重复项检查专项文档
|
||
之前创建的，专门针对 PO 文件重复项检查
|
||
|
||
---
|
||
|
||
### 5. 🌍 `test_csv_i18n.py` - CSV 配置国际化测试
|
||
|
||
**状态**: 已创建并通过测试
|
||
|
||
**功能**:
|
||
- 测试 CSV 配置的单源加载机制（Single Source of Truth）
|
||
- 验证 `load_game_configs` 时自动注入翻译
|
||
- 测试中英文切换时配置值的正确变化
|
||
- 验证随机姓名生成器的国际化支持
|
||
|
||
**特点**:
|
||
- 包含 Mock 单元测试（无需真实文件）
|
||
- 包含集成测试（使用真实 `static/game_configs`）
|
||
- 覆盖了重构后的配置加载核心逻辑
|
||
|
||
**运行方式**:
|
||
```bash
|
||
python -m pytest tests/test_csv_i18n.py
|
||
```
|
||
|
||
---
|
||
|
||
## 测试覆盖的方面
|
||
|
||
### ✅ 已覆盖
|
||
|
||
1. **PO 文件完整性**
|
||
- 无重复 msgid ✅
|
||
- 中英文数量一致 ✅
|
||
- 中英文键匹配 ✅
|
||
- 格式化参数一致 ✅
|
||
|
||
2. **代码质量检查**
|
||
- 硬编码字符串检测 ✅
|
||
- 翻译键定义检查 ✅
|
||
- AST 静态分析 ✅
|
||
|
||
3. **配置国际化**
|
||
- CSV 单源加载机制 ✅
|
||
- 动态翻译注入 ✅
|
||
- 姓名生成器适配 ✅
|
||
|
||
4. **文档和工具**
|
||
- 详细测试文档 ✅
|
||
- 独立检查工具 ✅
|
||
- CI/CD 集成示例 ✅
|
||
|
||
### 🔄 待完善
|
||
|
||
1. **深度功能测试**
|
||
- 需要修复项目导入问题
|
||
- 需要测试更多实际场景
|
||
|
||
2. **自动化修复**
|
||
- 考虑添加自动修复脚本
|
||
- 批量添加缺失翻译的工具
|
||
|
||
3. **性能测试**
|
||
- 翻译性能测试
|
||
- 缓存效果测试
|
||
|
||
---
|
||
|
||
## 推荐的工作流程
|
||
|
||
### 日常开发
|
||
|
||
```bash
|
||
# 1. 编写代码，使用 t() 函数
|
||
code = t("{name} obtained {amount} spirit stones", name=name, amount=100)
|
||
|
||
# 2. 运行快速检查（提交前）
|
||
python tests/test_i18n_duplicates.py
|
||
python tests/test_i18n_po_quality.py
|
||
|
||
# 3. 如果发现缺失的翻译，添加到 PO 文件
|
||
|
||
# 4. 重新运行测试确认
|
||
python tests/test_i18n_duplicates.py
|
||
```
|
||
|
||
### 大规模修改后
|
||
|
||
```bash
|
||
# 运行完整测试套件
|
||
python -m pytest tests/test_i18n_*.py -v
|
||
|
||
# 如果有导入问题，先运行独立测试
|
||
python tests/test_i18n_duplicates.py
|
||
python tests/test_i18n_po_quality.py
|
||
```
|
||
|
||
---
|
||
|
||
## 需要你处理的事项
|
||
|
||
### 🔴 高优先级
|
||
|
||
1. **修复缺失的翻译键**
|
||
- 在两个 PO 文件中添加 9 个缺失的 msgid
|
||
- 参考 `test_i18n_po_quality.py` 的输出
|
||
|
||
2. **评估硬编码字符串**
|
||
- 查看 `classes/appearance.py` 等文件
|
||
- 决定哪些需要本地化，哪些作为数据保留
|
||
|
||
### 🟡 中优先级
|
||
|
||
3. **修复项目导入问题**
|
||
```python
|
||
# 修复这个导入错误
|
||
ImportError: cannot import name 'EFFECT_DESC_MAP'
|
||
```
|
||
|
||
4. **添加 CI/CD 集成**
|
||
- 参考 `README_i18n_tests.md` 中的 GitHub Actions 示例
|
||
|
||
### 🟢 低优先级
|
||
|
||
5. **优化测试性能**
|
||
- 考虑缓存 AST 解析结果
|
||
|
||
6. **添加更多测试场景**
|
||
- 测试特殊字符处理
|
||
- 测试复数形式（如果需要）
|
||
|
||
---
|
||
|
||
## 测试统计
|
||
|
||
### 当前测试覆盖
|
||
|
||
| 测试类别 | 测试数量 | 通过 | 警告 | 失败 |
|
||
|---------|---------|------|------|------|
|
||
| PO 重复项 | 4 | 4 | 0 | 0 |
|
||
| 翻译键定义 | 1 | 0 | 1 | 0 |
|
||
| 硬编码检测 | 1 | 0 | 1 | 0 |
|
||
| 参数一致性 | 1 | 1 | 0 | 0 |
|
||
| **总计** | **7** | **5** | **2** | **0** |
|
||
|
||
### PO 文件统计
|
||
|
||
- **总 msgid 数**: 519
|
||
- **代码中使用**: 239 个唯一 msgid
|
||
- **使用率**: 46%
|
||
- **缺失定义**: 9 个
|
||
- **重复项**: 0 个
|
||
- **参数错误**: 0 个
|
||
|
||
---
|
||
|
||
## 技术亮点
|
||
|
||
### 1. 独立测试设计
|
||
所有新测试都不依赖 conftest.py，避免了项目导入问题
|
||
|
||
### 2. AST 静态分析
|
||
使用 Python AST 解析器精确提取 `t()` 函数调用
|
||
|
||
### 3. 详细错误定位
|
||
提供文件名、行号和具体内容，便于快速修复
|
||
|
||
### 4. 可扩展性
|
||
测试框架易于扩展，可以添加更多检查规则
|
||
|
||
---
|
||
|
||
## 下一步建议
|
||
|
||
1. **立即行动**:
|
||
- 在 PO 文件中添加 9 个缺失的 msgid
|
||
- 运行测试确认修复
|
||
|
||
2. **短期计划**:
|
||
- 评估硬编码中文字符串，决定处理策略
|
||
- 修复项目导入问题
|
||
|
||
3. **长期规划**:
|
||
- 将测试集成到 CI/CD
|
||
- 建立翻译工作流程文档
|
||
- 考虑使用翻译管理工具
|
||
|
||
---
|
||
|
||
## 相关文件
|
||
|
||
- ✅ `tests/test_i18n_duplicates.py` - 重复项检查
|
||
- ✅ `tests/test_i18n_po_quality.py` - 质量检查
|
||
- ✅ `tests/test_i18n_classes_coverage.py` - 覆盖率测试
|
||
- ✅ `tests/README_i18n_tests.md` - 详细文档
|
||
- ✅ `tests/README_i18n_duplicates.md` - 重复项文档
|
||
- ✅ `tools/i18n/check_po_duplicates.py` - 独立工具
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
通过添加这套测试，我们现在可以：
|
||
|
||
✅ **自动检测** PO 文件中的重复项
|
||
✅ **自动发现** 代码中缺失的翻译
|
||
✅ **自动验证** 格式化参数的一致性
|
||
✅ **持续监控** 国际化工作的质量
|
||
|
||
这将大大提高国际化工作的效率和质量！🎉
|