i18n-date-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

i18n and Localization Patterns

国际化(i18n)与本地化模式

Overview

概述

This skill provides comprehensive guidance for implementing internationalization in React applications. It ensures ALL user-facing strings, date displays, currency, lists, and time calculations are locale-aware.
When to use this skill:
  • Adding ANY user-facing text to components
  • Formatting dates, times, currency, lists, or ordinals
  • Implementing complex pluralization
  • Embedding React components in translated text
  • Supporting RTL languages (Hebrew, Arabic)
Bundled Resources:
  • references/formatting-utilities.md
    - useFormatting hook API reference
  • references/icu-messageformat.md
    - ICU plural/select syntax
  • references/trans-component.md
    - Trans component for rich text
  • checklists/i18n-checklist.md
    - Implementation and review checklist
  • examples/component-i18n-example.md
    - Complete component example
Canonical Reference: See
docs/i18n-standards.md
for the full i18n standards document.

本技能为在React应用中实现国际化提供全面指导。确保所有面向用户的字符串、日期显示、货币、列表和时间计算都具备区域感知能力。
何时使用本技能:
  • 向组件中添加任何面向用户的文本
  • 格式化日期、时间、货币、列表或序数词
  • 实现复杂的复数规则
  • 在翻译文本中嵌入React组件
  • 支持RTL语言(希伯来语、阿拉伯语)
附带资源:
  • references/formatting-utilities.md
    - useFormatting钩子API参考文档
  • references/icu-messageformat.md
    - ICU复数/选择语法说明
  • references/trans-component.md
    - 用于富文本的Trans组件说明
  • checklists/i18n-checklist.md
    - 实现与审查检查清单
  • examples/component-i18n-example.md
    - 完整组件示例
标准参考文档: 详见
docs/i18n-standards.md
获取完整的国际化标准文档。

Core Patterns

核心模式

1. useTranslation Hook (All UI Strings)

1. useTranslation钩子(所有UI字符串)

Every visible string MUST use the translation function:
tsx
import { useTranslation } from 'react-i18next';

function MyComponent() {
  const { t } = useTranslation(['patients', 'common']);
  
  return (
    <div>
      <h1>{t('patients:title')}</h1>
      <button>{t('common:actions.save')}</button>
    </div>
  );
}
所有可见字符串必须使用翻译函数:
tsx
import { useTranslation } from 'react-i18next';

function MyComponent() {
  const { t } = useTranslation(['patients', 'common']);
  
  return (
    <div>
      <h1>{t('patients:title')}</h1>
      <button>{t('common:actions.save')}</button>
    </div>
  );
}

2. useFormatting Hook (Locale-Aware Data)

2. useFormatting钩子(区域感知数据)

All locale-sensitive formatting MUST use the centralized hook:
tsx
import { useFormatting } from '@/hooks';

function PriceDisplay({ amount, items }) {
  const { formatILS, formatList, formatOrdinal } = useFormatting();
  
  return (
    <div>
      <p>Price: {formatILS(amount)}</p>        {/* ₪1,500.00 */}
      <p>Items: {formatList(items)}</p>        {/* "a, b, and c" */}
      <p>Position: {formatOrdinal(3)}</p>      {/* "3rd" */}
    </div>
  );
}
See
references/formatting-utilities.md
for the complete API.
所有区域敏感的格式化必须使用集中式钩子:
tsx
import { useFormatting } from '@/hooks';

function PriceDisplay({ amount, items }) {
  const { formatILS, formatList, formatOrdinal } = useFormatting();
  
  return (
    <div>
      <p>价格:{formatILS(amount)}</p>        {/* ₪1,500.00 */}
      <p>物品:{formatList(items)}</p>        {/* "a, b, and c" */}
      <p>排名:{formatOrdinal(3)}</p>      {/* "3rd" */}
    </div>
  );
}
详见
references/formatting-utilities.md
获取完整API说明。

3. Date Formatting

3. 日期格式化

All dates MUST use the centralized
@/lib/dates
library:
tsx
import { formatDate, formatDateShort, calculateWaitTime } from '@/lib/dates';

const date = formatDate(appointment.date);    // "Jan 6, 2026"
const waitTime = calculateWaitTime('09:30');  // "15 min"
所有日期必须使用集中式的
@/lib/dates
库:
tsx
import { formatDate, formatDateShort, calculateWaitTime } from '@/lib/dates';

const date = formatDate(appointment.date);    // "Jan 6, 2026"
const waitTime = calculateWaitTime('09:30');  // "15 min"

4. ICU MessageFormat (Complex Plurals)

4. ICU MessageFormat(复杂复数)

Use ICU syntax in translation files for pluralization:
json
{
  "patients": "{count, plural, =0 {No patients} one {# patient} other {# patients}}"
}
tsx
t('patients', { count: 5 })  // → "5 patients"
See
references/icu-messageformat.md
for full syntax.
在翻译文件中使用ICU语法处理复数:
json
{
  "patients": "{count, plural, =0 {没有患者} one {#位患者} other {#位患者}}"
}
tsx
t('patients', { count: 5 })  // → "5位患者"
详见
references/icu-messageformat.md
获取完整语法。

5. Trans Component (Rich Text)

5. Trans组件(富文本)

For embedded React components in translated text:
tsx
import { Trans } from 'react-i18next';

<Trans
  i18nKey="richText.welcome"
  values={{ name: userName }}
  components={{ strong: <strong /> }}
/>
See
references/trans-component.md
for patterns.

在翻译文本中嵌入React组件时使用:
tsx
import { Trans } from 'react-i18next';

<Trans
  i18nKey="richText.welcome"
  values={{ name: userName }}
  components={{ strong: <strong /> }}
/>
详见
references/trans-component.md
获取使用模式。

Translation File Structure

翻译文件结构

frontend/src/i18n/locales/
├── en/
│   ├── common.json      # Shared: actions, status, time
│   ├── patients.json    # Patient-related strings
│   ├── dashboard.json   # Dashboard strings
│   ├── owner.json       # Owner portal strings
│   └── invoices.json    # Invoice strings
└── he/
    └── (same structure)

frontend/src/i18n/locales/
├── en/
│   ├── common.json      # 通用:操作、状态、时间
│   ├── patients.json    # 患者相关字符串
│   ├── dashboard.json   # 仪表盘字符串
│   ├── owner.json       # 所有者门户字符串
│   └── invoices.json    # 发票字符串
└── he/
    └── (相同结构)

Anti-Patterns (FORBIDDEN)

反模式(禁止使用)

typescript
// ❌ NEVER hardcode strings
<h1>מטופלים</h1>                    // Use t('patients:title')
<button>Save</button>               // Use t('common:actions.save')

// ❌ NEVER use .join() for lists
items.join(', ')                    // Use formatList(items)

// ❌ NEVER hardcode currency
"₪" + price                         // Use formatILS(price)

// ❌ NEVER use new Date() for formatting
new Date().toLocaleDateString()     // Use formatDate() from @/lib/dates

// ❌ NEVER use inline plural logic
count === 1 ? 'item' : 'items'      // Use ICU MessageFormat

// ❌ NEVER leave console.log in production
console.log('debug')                // Remove before commit

// ❌ NEVER use dangerouslySetInnerHTML for i18n
dangerouslySetInnerHTML             // Use <Trans> component

typescript
// ❌ 绝对不要硬编码字符串
<h1>מטופלים</h1>                    // 请使用t('patients:title')
<button>保存</button>               // 请使用t('common:actions.save')

// ❌ 绝对不要使用.join()处理列表
items.join(', ')                    // 请使用formatList(items)

// ❌ 绝对不要硬编码货币符号
"₪" + price                         // 请使用formatILS(price)

// ❌ 绝对不要使用new Date()进行格式化
new Date().toLocaleDateString()     // 请使用@/lib/dates中的formatDate()

// ❌ 绝对不要使用内联复数逻辑
count === 1 ? 'item' : 'items'      // 请使用ICU MessageFormat

// ❌ 绝对不要在生产环境中保留console.log
console.log('debug')                // 提交前移除

// ❌ 绝对不要为了i18n使用dangerouslySetInnerHTML
dangerouslySetInnerHTML             // 请使用<Trans>组件

Quick Reference

快速参考

NeedSolution
UI text
t('namespace:key')
from
useTranslation
Currency
formatILS(amount)
from
useFormatting
Lists
formatList(items)
from
useFormatting
Ordinals
formatOrdinal(n)
from
useFormatting
Dates
formatDate(date)
from
@/lib/dates
PluralsICU MessageFormat in translation files
Rich text
<Trans>
component
RTL check
isRTL
from
useFormatting

需求解决方案
UI文本来自
useTranslation
t('namespace:key')
货币格式化来自
useFormatting
formatILS(amount)
列表格式化来自
useFormatting
formatList(items)
序数词格式化来自
useFormatting
formatOrdinal(n)
日期格式化来自
@/lib/dates
formatDate(date)
复数处理翻译文件中的ICU MessageFormat
富文本
<Trans>
组件
RTL检测来自
useFormatting
isRTL

Checklist

检查清单

See
checklists/i18n-checklist.md
for complete implementation and review checklists.

详见
checklists/i18n-checklist.md
获取完整的实现与审查检查清单。

Integration with Agents

与角色的协作

Frontend UI Developer

前端UI开发者

  • Uses all i18n patterns for components
  • References this skill for formatting
  • Ensures no hardcoded strings
  • 在组件中使用所有国际化模式
  • 参考本技能进行格式化
  • 确保没有硬编码字符串

Code Quality Reviewer

代码质量审核者

  • Checks for anti-patterns (
    .join()
    ,
    console.log
    , etc.)
  • Validates translation key coverage
  • Ensures RTL compatibility

Skill Version: 1.2.0 Last Updated: 2026-01-06 Maintained by: Yonatan Gross
  • 检查反模式(如
    .join()
    console.log
    等)
  • 验证翻译键的覆盖范围
  • 确保RTL兼容性

技能版本: 1.2.0 最后更新: 2026-01-06 维护人: Yonatan Gross

Related Skills

相关技能

  • testing-patterns
    - Comprehensive testing patterns including accessibility testing for i18n
  • type-safety-validation
    - Zod schemas for validating translation key structures and locale configs
  • react-server-components-framework
    - Server-side locale detection and RSC i18n patterns
  • accessibility
    - RTL-aware focus management for bidirectional UI navigation
  • testing-patterns
    - 包含国际化无障碍测试的全面测试模式
  • type-safety-validation
    - 用于验证翻译键结构和区域配置的Zod模式
  • react-server-components-framework
    - 服务端区域检测与RSC国际化模式
  • accessibility
    - 支持RTL的焦点管理,适用于双向UI导航

Key Decisions

关键决策

DecisionChoiceRationale
Translation Libraryreact-i18nextReact-native hooks, namespace support, ICU format
Date LibrarydayjsLightweight, locale plugins, immutable API
Message FormatICU MessageFormatIndustry standard, complex plural/select support
Locale StoragePer-namespace JSONCode-splitting, lazy loading per feature
RTL DetectionCSS logical propertiesNative browser support, no JS overhead
决策选择理由
翻译库react-i18nextReact原生钩子、命名空间支持、ICU格式兼容
日期库dayjs轻量、区域插件支持、不可变API
消息格式ICU MessageFormat行业标准、支持复杂复数/选择逻辑
区域存储按命名空间划分的JSON代码分割、按功能懒加载
RTL检测CSS逻辑属性原生浏览器支持、无JS性能开销

Capability Details

能力细节

translation-hooks

translation-hooks

Keywords: useTranslation, t(), i18n hook, translation hook Solves:
  • Translate UI strings with useTranslation
  • Implement namespaced translations
  • Handle missing translation keys
关键词: useTranslation, t(), i18n hook, translation hook 解决的问题:
  • 使用useTranslation翻译UI字符串
  • 实现命名空间翻译
  • 处理缺失的翻译键

formatting-hooks

formatting-hooks

Keywords: useFormatting, formatCurrency, formatList, formatOrdinal Solves:
  • Format currency values with locale
  • Format lists with proper separators
  • Handle ordinal numbers across locales
关键词: useFormatting, formatCurrency, formatList, formatOrdinal 解决的问题:
  • 按区域格式化货币值
  • 使用正确的分隔符格式化列表
  • 处理不同区域的序数词

icu-messageformat

icu-messageformat

Keywords: ICU, MessageFormat, plural, select, pluralization Solves:
  • Implement pluralization rules
  • Handle gender-specific translations
  • Build complex message patterns
关键词: ICU, MessageFormat, plural, select, pluralization 解决的问题:
  • 实现复数规则
  • 处理性别特定的翻译
  • 构建复杂的消息模式

date-time-formatting

date-time-formatting

Keywords: date format, time format, dayjs, locale date, calendar Solves:
  • Format dates with dayjs and locale
  • Handle timezone-aware formatting
  • Build calendar components with i18n
关键词: date format, time format, dayjs, locale date, calendar 解决的问题:
  • 使用dayjs和区域设置格式化日期
  • 处理时区感知格式化
  • 构建支持国际化的日历组件

rtl-support

rtl-support

Keywords: RTL, right-to-left, hebrew, arabic, direction Solves:
  • Support RTL languages like Hebrew
  • Handle bidirectional text
  • Configure RTL-aware layouts
关键词: RTL, right-to-left, hebrew, arabic, direction 解决的问题:
  • 支持希伯来语等RTL语言
  • 处理双向文本
  • 配置支持RTL的布局

trans-component

trans-component

Keywords: Trans, rich text, embedded JSX, interpolation Solves:
  • Embed React components in translations
  • Handle rich text formatting
  • Implement safe HTML in translations
关键词: Trans, rich text, embedded JSX, interpolation 解决的问题:
  • 在翻译中嵌入React组件
  • 处理富文本格式化
  • 在翻译中实现安全的HTML