I18N Localization

i18n & 本地化

国际化 (i18n) 和本地化 (L10n) 最佳实践。

1. 核心概念

2. 何时使用 i18n

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. 常见问题

7. RTL 支持

/* CSS 逻辑属性 */
.container {
  margin-inline-start: 1rem;  /* 而非 margin-left */
  padding-inline-end: 1rem;   /* 而非 padding-right */
}

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

8. 检查清单

发布前检查：

• 所有面向用户的字符串使用翻译键
• 所有支持语言的翻译文件已存在
• 日期/数字格式使用 Intl API
• RTL 布局已测试（如适用）
• 已配置回退语言
• 组件中无硬编码字符串

脚本

使用时机

本技能适用于执行概述中描述的工作流程或操作。

限制

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