shenjingnan/localization-validator

本地化验证技能

技能描述

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

技能使用原则

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

检查项目

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

验证规则

1. 代码注释检查

// ❌ 错误 - 英文注释
// Get user data from API

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

2. 测试用例描述检查

// ❌ 错误 - 英文描述
describe("User Component", () => {
  it("should render user name correctly", () => {
    // ...
  });
});

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

3. 硬编码字符串检查

// ❌ 错误 - 硬编码英文字符串
const serviceName = "unknown";
const status = "loading";

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

4. 技术标识符例外

以下情况可以保留英文：

• 技术标识符（如 "coze", "mcp", "stdio"）
• API 路径参数
• 配置键名
• 函数和变量名（遵循编程惯例）

验证流程

自动检查

1. 使用 grep 查找英文注释模式：

   grep -r "//.*[A-Z][a-z].*" --include="*.ts" --include="*.tsx" src/
   

2. 查找英文测试描述：

   grep -r "describe\|it(" --include="*.test.ts" --include="*.test.tsx" src/
   

3. 查找硬编码英文字符串：

   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. 定期运行本地化验证工具