Back to Details

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进行带本地化错误消息的运行时验证