---
name: localization-validator
description: 本地化验证技能，用于验证项目的本地化质量
---

# 本地化验证技能

## 技能描述
该技能用于验证项目的本地化质量，确保所有面向中文开发者和用户的内容都符合项目的本地化标准，同时遵循务实开发理念。

### 技能使用原则
- **保证本地化质量，但避免过度严格**：确保用户可见内容本地化，但不追求完美的本地化标准
- **实用功能优先，理论完美次之**：解决实际的本地化问题比预防所有可能更重要
- **简单解决方案优于复杂方案**：优先选择直接有效的本地化检查方式
- **务实开发指导**：评估本地化的必要性，避免过度本地化

## 检查项目
1. **代码注释本地化** - 检查是否还有英文注释
2. **测试用例描述本地化** - 检查测试文件中的 describe 和 it 语句是否使用中文
3. **用户界面字符串本地化** - 检查硬编码的英文字符串
4. **错误信息本地化** - 检查面向用户的错误信息
5. **文档和注释一致性** - 确保所有文档都使用中文

## 验证规则

### 1. 代码注释检查
```typescript
// ❌ 错误 - 英文注释
// Get user data from API

// ✅ 正确 - 中文注释
// 从 API 获取用户数据
```

### 2. 测试用例描述检查
```typescript
// ❌ 错误 - 英文描述
describe("User Component", () => {
  it("should render user name correctly", () => {
    // ...
  });
});

// ✅ 正确 - 中文描述
describe("用户组件", () => {
  it("应该正确渲染用户名称", () => {
    // ...
  });
});
```

### 3. 硬编码字符串检查
```typescript
// ❌ 错误 - 硬编码英文字符串
const serviceName = "unknown";
const status = "loading";

// ✅ 正确 - 使用中文常量
const UNKNOWN_SERVICE = "未知服务";
const LOADING_STATUS = "加载中";
```

### 4. 技术标识符例外
以下情况可以保留英文：
- 技术标识符（如 "coze", "mcp", "stdio"）
- API 路径参数
- 配置键名
- 函数和变量名（遵循编程惯例）

## 验证流程

### 自动检查
1. 使用 grep 查找英文注释模式：
   ```bash
   grep -r "//.*[A-Z][a-z].*" --include="*.ts" --include="*.tsx" src/
   ```

2. 查找英文测试描述：
   ```bash
   grep -r "describe\|it(" --include="*.test.ts" --include="*.test.tsx" src/
   ```

3. 查找硬编码英文字符串：
   ```bash
   grep -r '"[a-zA-Z]\{3,\}"' --include="*.ts" --include="*.tsx" src/
   ```

### 手动验证
1. 检查自动检查的结果
2. 确认技术标识符的例外情况
3. 验证翻译的准确性和一致性

## 修复建议

### 优先级 1：高优先级
- 用户界面中的硬编码英文字符串
- 测试用例中的英文描述
- 面向用户的错误信息

### 优先级 2：中优先级
- 代码注释中的英文
- 文档中的英文内容

### 优先级 3：低优先级
- 开发者工具中的英文（如调试信息）
- 技术标识符（如服务名称）

## 常见翻译对照

| 英文 | 中文 |
|------|------|
| unknown | 未知 |
| loading | 加载中 |
| error | 错误 |
| success | 成功 |
| failed | 失败 |
| pending | 待处理 |
| completed | 已完成 |
| configuration | 配置 |
| parameter | 参数 |
| component | 组件 |
| service | 服务 |
| server | 服务器 |
| client | 客户端 |

## 使用方法

当需要对项目进行本地化验证时：

1. **运行自动检查**：执行上述 grep 命令查找英文内容
2. **分类问题**：将发现的问题按优先级分类
3. **制定修复计划**：根据优先级制定修复顺序
4. **执行修复**：逐一修复发现的问题
5. **验证修复**：确保修复后没有引入新问题

## 长期维护

### 代码审查检查点
- [ ] 所有新代码注释使用中文
- [ ] 所有新增测试用例使用中文描述
- [ ] 用户界面字符串已本地化
- [ ] 错误信息已本地化

### CI/CD 集成建议
可以将部分检查集成到 CI/CD 流程中，确保新代码符合本地化标准。

## 经验记录

### xiaozhi-client 项目经验
在 xiaozhi-client 项目的本地化过程中发现：
1. 大部分用户界面已经中文化，主要问题集中在测试文件和代码注释
2. 技术标识符（如 "coze", "mcp"）应该保持英文，便于技术交流
3. 常量定义是处理硬编码字符串的好方法
4. 测试用例描述中文化对团队协作很重要

### 最佳实践
1. 在代码审查时加入本地化检查项
2. 使用常量定义用户可见的字符串
3. 保持技术标识符的英文形式
4. 定期运行本地化验证工具