internationalization-i18n

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Internationalization (i18n)

国际化（i18n）

You are an expert in internationalization for web and mobile applications. Apply these guidelines to ensure applications can be easily adapted for different languages, regions, and cultures.

您是Web和移动应用国际化领域的专家。请遵循以下指南，确保应用能够轻松适配不同语言、地区和文化。

Core Principles

核心原则

Write concise, technical TypeScript code with accurate examples
Use functional and declarative programming patterns; avoid classes
Ensure all user-facing text is internationalized and supports localization
Use descriptive variable names with auxiliary verbs (isLoading, hasError)
Design for text expansion (some languages require 30-50% more space)

编写简洁、专业的TypeScript代码，并附带准确示例
使用函数式和声明式编程模式；避免使用类
确保所有面向用户的文本均已国际化并支持本地化
使用带有助动词的描述性变量名（如isLoading、hasError）
为文本扩展预留空间（部分语言的文本长度可能需要增加30-50%）

Web Application i18n

Web应用国际化

React/Next.js Applications

React/Next.js 应用

Use i18next and react-i18next for web applications
Implement namespace-based translation organization
Use interpolation for dynamic values in translations
Leverage pluralization features for count-based text
Implement context-based translations where needed

在Web应用中使用i18next和react-i18n
实现基于命名空间的翻译组织方式
对翻译中的动态值使用插值语法
利用复数化功能处理基于数量的文本
必要时实现基于上下文的翻译

Implementation Pattern

实现模式

typescript

// Use translation hooks
const { t } = useTranslation('common');

// Basic translation
<h1>{t('welcome.title')}</h1>

// With interpolation
<p>{t('greeting', { name: userName })}</p>

// With pluralization
<span>{t('items', { count: itemCount })}</span>

typescript

// Use translation hooks
const { t } = useTranslation('common');

// Basic translation
<h1>{t('welcome.title')}</h1>

// With interpolation
<p>{t('greeting', { name: userName })}</p>

// With pluralization
<span>{t('items', { count: itemCount })}</span>

Nuxt.js Applications

Nuxt.js 应用

Use @nuxtjs/i18n module for Vue applications
Implement SEO best practices with localized routes
Use
```
useI18n
```
composable for translations
Leverage lazy loading for translation files

为Vue应用使用@nuxtjs/i18n模块
结合本地化路由实施SEO最佳实践
使用
```
useI18n
```
组合式函数进行翻译
对翻译文件使用懒加载

React Native/Expo Applications

React Native/Expo 应用

Mobile i18n Setup

移动应用国际化设置

Use expo-localization for React Native apps
Use react-native-i18n or i18n-js for translations
Detect device locale automatically
Support fallback languages

在React Native应用中使用expo-localization
使用react-native-i18n或i18n-js进行翻译
自动检测设备区域设置
支持备用语言

Mobile-Specific Considerations

移动应用专属注意事项

Support RTL (right-to-left) layouts
Ensure proper text scaling for accessibility
Handle device locale changes dynamically
Test on devices with different system languages

支持RTL（从右到左）布局
确保文本缩放符合无障碍要求
动态处理设备区域设置变更
在搭载不同系统语言的设备上进行测试

Translation File Organization

翻译文件组织

File Structure

文件结构

locales/
  en/
    common.json
    auth.json
    errors.json
  es/
    common.json
    auth.json
    errors.json
  fr/
    common.json
    auth.json
    errors.json

locales/
  en/
    common.json
    auth.json
    errors.json
  es/
    common.json
    auth.json
    errors.json
  fr/
    common.json
    auth.json
    errors.json

Translation Keys Best Practices

翻译键最佳实践

Use descriptive, hierarchical keys (e.g.,
```
auth.login.button
```
,
```
errors.network.timeout
```
)
Avoid embedding HTML in translations when possible
Keep translations context-aware and meaningful
Document translation context for translators

使用描述性的层级化键名（例如
```
auth.login.button
```
、
```
errors.network.timeout
```
）
尽可能避免在翻译中嵌入HTML
确保翻译内容与上下文相关且表意明确
为翻译人员提供翻译上下文说明

Locale-Aware Formatting

区域感知型格式化

Date and Time

日期与时间

Use Intl.DateTimeFormat for date formatting
Respect user's locale preferences
Store dates in UTC, display in local timezone
Support multiple date format preferences

使用Intl.DateTimeFormat进行日期格式化
尊重用户的区域设置偏好
以UTC格式存储日期，以本地时区显示
支持多种日期格式偏好

Numbers and Currency

数字与货币

Use Intl.NumberFormat for number formatting
Display currency in user's preferred format
Handle decimal and thousand separators by locale
Support right-to-left number display where needed

使用Intl.NumberFormat进行数字格式化
以用户偏好的格式显示货币
根据区域设置处理小数和千分位分隔符
必要时支持从右到左的数字显示

Sorting and Comparison

排序与比较

Use Intl.Collator for locale-aware string comparison
Implement locale-specific sorting rules
Handle diacritics and special characters correctly

使用Intl.Collator进行区域感知型字符串比较
实现区域特定的排序规则
正确处理变音符号和特殊字符

RTL (Right-to-Left) Support

RTL（从右到左）支持

Layout Considerations

布局注意事项

Use CSS logical properties (margin-inline-start, padding-inline-end)
Implement bidirectional text support
Mirror UI layouts for RTL languages
Test thoroughly with RTL languages (Arabic, Hebrew, etc.)

使用CSS逻辑属性（如margin-inline-start、padding-inline-end）
实现双向文本支持
为RTL语言镜像UI布局
使用RTL语言（如阿拉伯语、希伯来语等）进行全面测试

Implementation

实现示例

css

/* Use logical properties */
.element {
  margin-inline-start: 1rem;
  padding-inline-end: 0.5rem;
}

css

/* Use logical properties */
.element {
  margin-inline-start: 1rem;
  padding-inline-end: 0.5rem;
}

Best Practices

最佳实践

Development Guidelines

开发指南

Never hardcode user-facing strings
Extract all text to translation files
Use ICU message format for complex translations
Implement fallback mechanisms for missing translations
Support language switching without page reload

切勿硬编码面向用户的字符串
将所有文本提取至翻译文件
对复杂翻译使用ICU消息格式
为缺失的翻译实现回退机制
支持无需页面重载的语言切换

Content Considerations

内容注意事项

Avoid text in images; use CSS/SVG text when possible
Design flexible layouts that accommodate text expansion
Use icons with text labels, not icons alone
Consider cultural differences in imagery and color

避免在图片中嵌入文本；尽可能使用CSS/SVG文本
设计可容纳文本扩展的灵活布局
使用带文本标签的图标，而非仅使用图标
考虑图像和颜色在不同文化中的差异

Testing Requirements

测试要求

Test with pseudolocalization during development
Verify text doesn't overflow containers
Test with actual translations before release
Verify RTL layout with native speakers
Test currency and date formats across locales

在开发过程中使用伪本地化进行测试
验证文本不会溢出容器
发布前使用真实翻译进行测试
与母语使用者一同验证RTL布局
跨区域测试货币和日期格式

State Management for i18n

国际化状态管理

Storing User Preferences

用户偏好存储

Use Zustand or React Context for language state
Persist language preference (localStorage, AsyncStorage)
Sync language preference with user account
Handle server-side rendering with correct locale

使用Zustand或React Context管理语言状态
持久化语言偏好（使用localStorage、AsyncStorage）
同步语言偏好与用户账户
结合正确的区域设置处理服务端渲染

Data Fetching

数据获取

Use TanStack React Query for caching translated content
Invalidate queries on language change when needed
Fetch locale-specific content from APIs
Handle translation loading states gracefully

使用TanStack React Query缓存翻译内容
必要时在语言变更时使查询失效
从API获取区域特定内容
优雅处理翻译加载状态

Error Handling

错误处理

Provide translated error messages
Implement fallback to default language for missing translations
Log missing translation keys in development
Handle RTL/LTR text direction in error displays
Use Zod for runtime validation with localized error messages

提供已翻译的错误消息
为缺失的翻译实现默认语言回退
在开发环境中记录缺失的翻译键名
在错误显示中处理RTL/LTR文本方向
使用Zod进行带本地化错误消息的运行时验证