⚡

国际化与本地化Skill i18n-localization

该技能专注于软件的国际化和本地化实现，包括管理多语言翻译、处理区域文件、支持从右到左布局等，确保应用适应全球市场。关键词：国际化、本地化、翻译管理、多语言支持、RTL、前端开发、后端开发。

前端开发 0 次安装 0 次浏览 更新于 3/21/2026

name: i18n-localization description: 国际化和本地化模式。检测硬编码字符串，管理翻译，区域文件，RTL支持。 allowed-tools: 读，全局，查找

i18n 与本地化

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

1. 核心概念

术语 含义
i18n 国际化 - 使应用可翻译
L10n 本地化 - 实际翻译
Locale 语言 + 区域 (en-US, tr-TR)
RTL 从右到左语言 (阿拉伯语，希伯来语)

2. 何时使用 i18n

项目类型 需要 i18n？
公共网络应用 ✅ 是
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(_("欢迎使用我们的应用"))

4. 文件结构

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

5. 最佳实践

做 ✅

  • 使用翻译键，而非原始文本
  • 按功能命名空间翻译
  • 支持复数形式
  • 按区域处理日期/数字格式
  • 从一开始规划 RTL
  • 对复杂字符串使用 ICU 消息格式

不做 ❌

  • 在组件中硬编码字符串
  • 拼接翻译字符串
  • 假设文本长度 (德语长 30%)
  • 忘记 RTL 布局
  • 在同一文件中混合语言

6. 常见问题

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

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 布局测试 (如适用)
  • [ ] 配置回退语言
  • [ ] 组件中没有硬编码字符串

脚本

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