i18n国际化技能指南：多语言应用开发工作流与最佳实践 | SkillsMD⚠️重要前提
安装AI Skills的关键前提是：必须科学上网，且开启TUN模式，这一点至关重要，直接决定安装能否顺利完成，在此郑重提醒三遍：科学上网，科学上网，科学上网。查看完整安装教程 →
i18n国际化技能指南：多语言应用开发工作流与最佳实践
i18n by iofficeai/aionui
npx skills add https://github.com/iofficeai/aionui --skill i18n🇨🇳中文介绍
i18n 技能
国际化标准和工作流程。所有用户可见的文本必须使用 i18n。
开始时声明： "我正在使用 i18n 技能来确保正确的国际化。"
重要：首先阅读配置
在进行任何 i18n 工作之前，务必先阅读 src/common/config/i18n-config.json 以获取当前支持的语言和模块列表。切勿假设数量是固定的——自本技能编写以来，语言和模块可能已被添加或移除。
cat src/common/config/i18n-config.json
此文件是唯一事实来源。所有脚本、运行时代码以及此工作流程都依赖于它。
文件结构
src/common/config/i18n-config.json # 唯一事实来源：语言，模块
src/renderer/i18n/
├── index.ts # i18next 配置
├── i18n-keys.d.ts # 自动生成 — 请勿手动编辑
└── locales/
├── <lang>/ # i18n-config.json 中每种语言一个目录
│ ├── index.ts # 所有模块的桶导入
│ ├── common.json # i18n-config.json 中每个模块一个 JSON 文件
│ ├── conversation.json
│ └── ...
└── ...
关键事实
- 参考语言 : 由
i18n-config.json 中的 定义（当前为 ）
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者，精准高效
referenceLanguage
en-US
支持的语言 : 由 supportedLanguages 数组定义 — 阅读文件以获取当前列表模块 : 由 modules 数组定义 — 阅读文件以获取当前列表键结构
在代码中使用命名空间点表示法：t('module.key') 或 t('module.nested.key')。
在每个模块的 JSON 文件中，键可以是扁平或嵌套的：
// common.json — 扁平键
{
"send": "Send",
"cancel": "Cancel",
"copySuccess": "Copied"
}
// cron.json — 嵌套键
{
"scheduledTasks": "Scheduled Tasks",
"status": {
"active": "Active",
"paused": "Paused"
}
}
t('common.send'); // common.json 中的扁平键
t('cron.status.active'); // cron.json 中的嵌套键
键命名规则
- 键名使用 camelCase：
copySuccess、scheduledTasks
- 使用嵌套对相关键进行分组：
status.active、actions.pause
- 可复用的文本放在
common.json 中：保存、取消、删除、确认等。
- 特定功能的文本放在相应的模块中
常见后缀
| 后缀 | 用途 |
|---|
title | 部分/页面标题 |
placeholder | 输入占位符 |
label | 表单标签 |
success / error | 状态消息 |
confirm | 确认对话框 |
empty | 空状态消息 |
tooltip | 工具提示文本 |
添加新文本 — 工作流程
步骤 1：阅读 src/common/config/i18n-config.json
步骤 2：检查现有键
grep -r "keyword" src/renderer/i18n/locales/en-US/
步骤 3：选择正确的模块
将模块与功能区域匹配。如果没有合适的模块，请考虑是否需要新模块（见下文"添加新模块"）。
步骤 4：添加到所有语言环境目录
关键： 每个新键必须添加到 supportedLanguages 中的每个语言环境。对每个键使用此检查清单：
en-US/<module>.json — 参考语言（在步骤 3 中添加）zh-CN/<module>.json — 已添加zh-TW/<module>.json — 已添加src/common/config/i18n-config.json → supportedLanguages 中列出的任何其他语言 — 已添加
即使一个语言环境中缺少一个键，也会导致 CI 中的 node scripts/check-i18n.js 失败。
步骤 5：在组件中使用
import { useTranslation } from 'react-i18next';
function MyComponent() {
const { t } = useTranslation();
return <button>{t('common.save')}</button>;
}
步骤 6：重新生成类型并验证
按顺序运行这两个命令 — 在提交之前，两者都必须通过：
bun run i18n:types # 步骤 A：从参考语言环境重新生成 i18n-keys.d.ts
node scripts/check-i18n.js # 步骤 B：验证结构、键和类型同步
i18n:types 必须在 check-i18n.js 之前运行 — 检查会验证生成的文件- 如果
check-i18n.js 因错误退出（❌），请在继续之前修复它们
- 如果
check-i18n.js 仅因警告退出（⚠️），请检查但可以继续
- 切勿提交过时的
i18n-keys.d.ts
添加新模块
- 将模块名称添加到
src/common/config/i18n-config.json → modules 数组
- 在每个语言环境目录中创建
<module>.json（阅读 supportedLanguages 以了解是哪些）
- 在每个语言环境的
index.ts 中添加导入和导出
- 运行
bun run i18n:types 以重新生成类型定义
- 运行
node scripts/check-i18n.js 以验证
硬编码字符串检测
禁止的模式
// 错误
<span>重命名</span>
<span>Delete</span>
{name || '新对话'}
// 正确
<span>{t('common.rename')}</span>
<span>{t('common.delete')}</span>
{name || t('conversation.newConversation')}
例外情况
- 代码注释（任何语言都可以）
console.log() / 调试输出- 不向用户显示的内部字符串常量
插值
变量
{
"taskCount": "{{count}} task(s)",
"greeting": "Hello, {{name}}!"
}
t('cron.taskCount', { count: 5 });
翻译中的 HTML
import { Trans } from 'react-i18next';
<Trans i18nKey='cron.countdown'>
Task <strong>{{ taskName }}</strong> in <span>{{ countdown }}</span>
</Trans>;
zh-TW 维护
大多数术语可以从 zh-CN 自动转换，但有些需要手动审查：
| zh-CN | zh-TW | 备注 |
|---|
| 视频 | 影片 | 不同术语 |
| 软件 | 軟體 | 不同术语 |
| 信息 | 訊息 | 不同术语 |
| 默认 | 預設 | 不同术语 |
快速检查清单
- 阅读
src/common/config/i18n-config.json 以获取当前语言和模块
- 所有用户可见的文本都使用
t() 函数
- 新键已添加到
supportedLanguages 中的每个语言环境目录
- JSX 中没有硬编码的中文/英文
- zh-TW 已针对术语差异进行审查
- 首先运行了
bun run i18n:types（重新生成 i18n-keys.d.ts）
- 重新生成类型后
node scripts/check-i18n.js 已通过（无错误）
常见错误
| 错误 | 正确 |
|---|
| 假设语言数量固定 | 始终先阅读 i18n-config.json |
| 仅将键添加到某些语言环境 | 添加到 supportedLanguages 中的每个语言环境 |
手动编辑 i18n-keys.d.ts | 运行 bun run i18n:types 来生成 |
使用 t("New Chat") | 定义键：t("conversation.newChat") |
添加新模块时未更新 i18n-config.json | 先更新配置，然后创建文件 |
添加了模块 JSON 但未更新 index.ts | 必须在每个语言环境的 index.ts 中添加导入和导出 |
React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性
125,600 周安装
