MBE 多语言维护指南

概述

本文档说明如何在代码修改后维护和更新多语言翻译文件。

维护流程

1. 添加新的翻译键

当你在代码中添加新的文本时：

步骤 1: 在代码中使用翻译 Hook

import { useTranslations } from '@/hooks/use-translations';

function MyComponent() {
  const t = useTranslations('myNamespace');
  return <div>{t('newKey')}</div>;
}

步骤 2: 更新所有语言的翻译文件

必须同时更新所有语言文件：

admin-ui/messages/zh-CN.json
admin-ui/messages/en.json
（未来添加的其他语言文件）

步骤 3: 保持结构一致

确保所有语言文件的键结构完全一致：

// zh-CN.json
{
  "myNamespace": {
    "newKey": "新文本"
  }
}

// en.json
{
  "myNamespace": {
    "newKey": "New Text"
  }
}

2. 修改现有翻译

场景 A: 只修改翻译文本

直接编辑对应的 JSON 文件，更新翻译值：

// 修改前
"save": "保存"

// 修改后
"save": "保存更改"

重要: 需要同步更新所有语言文件中的对应键。

场景 B: 重命名翻译键

在代码中更新键名
在所有语言文件中：
- 删除旧键
- 添加新键（保持翻译值）

3. 删除翻译键

从代码中移除对该键的使用
从所有语言文件中删除该键

注意: 删除前确认没有其他地方使用该键。

工具和脚本

检查缺失的翻译键

运行检查脚本：

# Windows PowerShell
.\scripts\check-i18n-keys.ps1

# Linux/Mac
./scripts/check-i18n-keys.sh

该脚本会：

检测所有语言文件中的键是否一致
找出缺失的翻译键
报告未使用的翻译键（可选）

同步翻译文件结构

运行同步脚本：

# Windows PowerShell
.\scripts\sync-i18n-structure.ps1

# Linux/Mac
./scripts/sync-i18n-structure.sh

该脚本会：

以 zh-CN.json 为基准
确保其他语言文件有相同的键结构
为缺失的键添加占位符（需要手动翻译）

最佳实践

1. 命名规范

使用有意义的命名空间：common、nav、auth、dashboard 等
键名使用 camelCase：saveButton、userName
避免深层嵌套（最多 3 层）

2. 组织翻译文件

按功能模块组织：

{
  "common": { ... },      // 通用文本
  "nav": { ... },         // 导航
  "auth": { ... },        // 认证
  "dashboard": { ... },   // 仪表板
  "users": { ... }        // 用户管理
}

3. 占位符和变量

使用 next-intl 的变量插值：

{
  "welcome": "欢迎，{name}！",
  "items": "共 {count} 项"
}

t('welcome', { name: '张三' });
t('items', { count: 10 });

4. 复数形式

使用 next-intl 的复数支持：

{
  "messages": "{count, plural, =0 {没有消息} one {1 条消息} other {# 条消息}}"
}

5. 代码审查检查清单

在提交代码前检查：

所有硬编码文本都已替换为翻译键
新增的翻译键已添加到所有语言文件
所有语言文件的键结构一致
翻译文本符合目标语言习惯
占位符和变量使用正确

常见问题

Q1: 如何知道哪些翻译键缺失？

运行检查脚本 check-i18n-keys.ps1，它会列出所有不一致的地方。

Q2: 可以只更新中文文件吗？

不可以。必须同时更新所有语言文件，否则会导致其他语言显示翻译键而不是实际文本。

Q3: 如何添加新语言？

在 i18n/config.ts 中添加新语言代码
创建新的翻译文件 messages/{locale}.json
复制 zh-CN.json 的结构，翻译所有文本
更新 language-switcher.tsx 显示新语言

Q4: 翻译文件很大，如何管理？

按功能模块拆分成多个文件（需要修改加载逻辑）
使用翻译管理工具（如 Crowdin、Lokalise）
定期清理未使用的翻译键

Q5: 如何确保翻译质量？

使用专业翻译服务或母语者审核
建立术语表，保持术语一致性
定期审查和更新翻译

自动化建议

CI/CD 集成

在 CI 流程中添加检查：

# .github/workflows/ci.yml
- name: Check i18n keys
  run: ./scripts/check-i18n-keys.sh

预提交钩子

使用 Git hooks 在提交前自动检查：

# .git/hooks/pre-commit
#!/bin/bash
./scripts/check-i18n-keys.sh
if [ $? -ne 0 ]; then
  echo "i18n check failed!"
  exit 1
fi

MBE 文档中心