Back to Details

i18n-localization

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

i18n & Localization

i18n & Localization

Internationalization (i18n) and Localization (L10n) best practices.
国际化（i18n）与本地化（L10n）最佳实践。

1. Core Concepts

1. 核心概念

TermMeaning
i18nInternationalization - making app translatable
L10nLocalization - actual translations
LocaleLanguage + Region (en-US, tr-TR)
RTLRight-to-left languages (Arabic, Hebrew)
术语含义
i18nInternationalization - 使应用可被翻译
L10nLocalization - 实际翻译工作
Locale语言 + 地区（en-US, tr-TR）
RTL从右到左书写的语言（阿拉伯语、希伯来语）

2. When to Use i18n

2. 何时使用i18n

Project Typei18n Needed?
Public web app✅ Yes
SaaS product✅ Yes
Internal tool⚠️ Maybe
Single-region app⚠️ Consider future
Personal project❌ Optional
项目类型是否需要i18n？
公共Web应用✅ 是
SaaS产品✅ 是
内部工具⚠️ 可能需要
单区域应用⚠️ 考虑未来需求
个人项目❌ 可选

3. Implementation Patterns

3. 实现模式

React (react-i18next)

React (react-i18next)

tsx
import { useTranslation } from 'react-i18next';

function Welcome() {
  const { t } = useTranslation();
  return <h1>{t('welcome.title')}</h1>;
}
tsx
import { useTranslation } from 'react-i18next';

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

Next.js (next-intl)

Next.js (next-intl)

tsx
import { useTranslations } from 'next-intl';

export default function Page() {
  const t = useTranslations('Home');
  return <h1>{t('title')}</h1>;
}
tsx
import { useTranslations } from 'next-intl';

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

Python (gettext)

Python (gettext)

python
from gettext import gettext as _

print(_("Welcome to our app"))
python
from gettext import gettext as _

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

4. File Structure

4. 文件结构

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

5. Best Practices

5. 最佳实践

DO ✅

推荐做法 ✅

  • Use translation keys, not raw text
  • Namespace translations by feature
  • Support pluralization
  • Handle date/number formats per locale
  • Plan for RTL from the start
  • Use ICU message format for complex strings
  • 使用翻译键，而非原始文本
  • 按功能对翻译内容进行命名空间划分
  • 支持复数形式
  • 根据区域设置处理日期/数字格式
  • 从项目初期就规划RTL支持
  • 对复杂字符串使用ICU消息格式

DON'T ❌

避免做法 ❌

  • Hardcode strings in components
  • Concatenate translated strings
  • Assume text length (German is 30% longer)
  • Forget about RTL layout
  • Mix languages in same file
  • 在组件中硬编码字符串
  • 拼接翻译后的字符串
  • 假设文本长度（德语通常比英语长30%）
  • 忽略RTL布局
  • 在同一文件中混合多种语言

6. Common Issues

6. 常见问题

IssueSolution
Missing translationFallback to default language
Hardcoded stringsUse linter/checker script
Date formatUse Intl.DateTimeFormat
Number formatUse Intl.NumberFormat
PluralizationUse ICU message format
问题解决方案
缺失翻译内容回退到默认语言
硬编码字符串使用代码检查器脚本
日期格式使用Intl.DateTimeFormat
数字格式使用Intl.NumberFormat
复数形式使用ICU消息格式

7. RTL Support

7. RTL支持

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

[dir="rtl"] .icon {
  transform: scaleX(-1);
}
css
/* 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. Checklist

8. 检查清单

Before shipping:
  • All user-facing strings use translation keys
  • Locale files exist for all supported languages
  • Date/number formatting uses Intl API
  • RTL layout tested (if applicable)
  • Fallback language configured
  • No hardcoded strings in components
发布前：
  • 所有面向用户的字符串都使用翻译键
  • 为所有支持的语言准备了区域设置文件
  • 日期/数字格式使用Intl API
  • 已测试RTL布局（如适用）
  • 已配置回退语言
  • 组件中无硬编码字符串

Script

脚本

ScriptPurposeCommand
scripts/i18n_checker.py
Detect hardcoded strings & missing translations
python scripts/i18n_checker.py <project_path>
脚本用途命令
scripts/i18n_checker.py
检测硬编码字符串及缺失的翻译内容
python scripts/i18n_checker.py <project_path>

When to Use

使用场景

This skill is applicable to execute the workflow or actions described in the overview.
本技能适用于执行概述中描述的工作流或操作。

Limitations

局限性

  • Use this skill only when the task clearly matches the scope described above.
  • Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
  • Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
  • 仅当任务明确匹配上述描述的范围时使用本技能。
  • 不要将输出结果视为特定环境下验证、测试或专家评审的替代品。
  • 如果缺少必要的输入、权限、安全边界或成功标准，请暂停并请求澄清。