localization-validator

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

本地化验证技能

技能描述

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

技能使用原则

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

检查项目

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