i18n & Localization

i18n 与本地化

Internationalization (i18n) and Localization (L10n) best practices.

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

1. Core Concepts

1. 核心概念

Term	Meaning
i18n	Internationalization - making app translatable
L10n	Localization - actual translations
Locale	Language + Region (en-US, tr-TR)
RTL	Right-to-left languages (Arabic, Hebrew)

术语	含义
i18n	国际化 - 使应用具备可翻译性
L10n	本地化 - 实际翻译工作
Locale	语言区域（en-US, tr-TR）
RTL	从右到左语言（阿拉伯语、希伯来语）

2. When to Use i18n

2. 何时使用i18n

Project Type	i18n Needed?
Public web app	✅ Yes
SaaS product	✅ Yes
Internal tool	⚠️ Maybe
Single-region app	⚠️ Consider future
Personal project	❌ Optional

项目类型	是否需要i18n？
公共网页应用	✅ 是
SaaS产品	✅ 是
内部工具	⚠️ 可能需要
单区域应用	⚠️ 考虑未来扩展
个人项目	❌ 可选

3. Implementation Patterns

3. 实现模式

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)

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

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

Issue	Solution
Missing translation	Fallback to default language
Hardcoded strings	Use linter/checker script
Date format	Use Intl.DateTimeFormat
Number format	Use Intl.NumberFormat
Pluralization	Use 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

脚本

Script	Purpose	Command
`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>`

i18n-localization

Original

Translation

i18n & Localization

i18n 与本地化

1. Core Concepts

1. 核心概念

2. When to Use i18n

2. 何时使用i18n

3. Implementation Patterns

3. 实现模式

React (react-i18next)

React (react-i18next)

Next.js (next-intl)

Next.js (next-intl)

Python (gettext)

Python (gettext)

4. File Structure

4. 文件结构

5. Best Practices

5. 最佳实践

DO ✅

建议✅

DON'T ❌

避免❌

6. Common Issues

6. 常见问题

7. RTL Support

7. RTL支持

8. Checklist

8. 检查清单

Script

脚本