i18n-localization

i18n 与本地化

国际化（i18n）和本地化（L10n）的最佳实践。

---

1. 核心概念

术语	含义
i18n	国际化——使应用可翻译
L10n	本地化——实际的翻译
Locale	语言 + 地区（en-US、tr-TR）
RTL	从右向左书写的语言（阿拉伯语、希伯来语）

---

2. 何时使用 i18n

项目类型	是否需要 i18n？
面向公众的 Web 应用	✅ 是
SaaS 产品	✅ 是
内部工具	⚠️ 视情况而定
单一区域应用	⚠️ 考虑未来需求
个人项目	❌ 可选

---

3. 实现模式

React（react-i18next）

import { useTranslation } from 'react-i18next';

function Welcome() {
  const { t } = useTranslation();
  return <h1>{t('welcome.title')}</h1>;
}

Next.js（next-intl）

import { useTranslations } from 'next-intl';

export default function Page() {
  const t = useTranslations('Home');
  return <h1>{t('title')}</h1>;
}

Python（gettext）

from gettext import gettext as _

print(_("Welcome to our app"))

---

4. 文件结构

locales/
├── en/
│   ├── common.json
│   ├── auth.json
│   └── errors.json
├── tr/
│   ├── common.json
│   ├── auth.json
│   └── errors.json
└── ar/          # RTL
    └── ...

---

5. 最佳实践

应该 ✅

• 使用翻译键，而非原始文本
• 按功能对翻译进行命名空间划分
• 支持复数形式
• 根据地区设置处理日期和数字格式
• 从一开始就规划 RTL 支持
• 对复杂字符串使用 ICU 消息格式

不应该 ❌

• 在组件中硬编码字符串
• 拼接已翻译的字符串
• 假设文本长度固定（德语文本会长 30%）
• 忘记 RTL 布局
• 在同一个文件中混用多种语言

---

6. 常见问题

问题	解决方案
缺少翻译	回退到默认语言
硬编码字符串	使用 lint 工具／检查脚本
日期格式	使用 Intl.DateTimeFormat
数字格式	使用 Intl.NumberFormat
复数形式	使用 ICU 消息格式

---

7. RTL 支持

/* CSS Logical Properties */
.container {
  margin-inline-start: 1rem;  /* Not margin-left */
  padding-inline-end: 1rem;   /* Not padding-right */
}

[dir="rtl"] .icon {
  transform: scaleX(-1);
}

---

8. 检查清单

发布前：

• 所有面向用户的字符串都使用翻译键
• 所有受支持的语言都有对应的区域设置文件
• 日期／数字格式使用 Intl API
• 已测试 RTL 布局（如适用）
• 已配置回退语言
• 组件中没有硬编码字符串

---

脚本

随附的检查器采用启发式方法，最多检查 50 个按排序排列的源文件。它使用偏向英语的正则表达式，并按目录对 JSON 区域设置进行分组；它不会完整检查 gettext 目录和 messages/en.json 布局中的键是否一致。请报告实际抽样数／发现数以及解析失败情况；抽样检查无异常并不代表内容完整、翻译质量合格或满足无障碍要求。RTL 布局中只镜像方向性图标（例如导航箭头），不要镜像所有徽标、图片或媒体控件。

脚本	用途	命令
scripts/i18n_checker.py	检测硬编码字符串和缺失的翻译	python scripts/i18n_checker.py <project_path>

何时使用

当任务与概述中描述的工作流或操作相符时，可使用此技能。

限制

• 仅在任务明确符合上述范围时使用此技能。
• 不要将输出视为可替代环境特定验证、测试或专家审查的内容。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。