i18n-date-patterns
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinesei18n 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:
- - useFormatting hook API reference
references/formatting-utilities.md - - ICU plural/select syntax
references/icu-messageformat.md - - Trans component for rich text
references/trans-component.md - - Implementation and review checklist
checklists/i18n-checklist.md - - Complete component example
examples/component-i18n-example.md
Canonical Reference: See for the full i18n standards document.
docs/i18n-standards.md本技能为在React应用中实现国际化提供全面指导。确保所有面向用户的字符串、日期显示、货币、列表和时间计算都具备区域感知能力。
何时使用本技能:
- 向组件中添加任何面向用户的文本
- 格式化日期、时间、货币、列表或序数词
- 实现复杂的复数规则
- 在翻译文本中嵌入React组件
- 支持RTL语言(希伯来语、阿拉伯语)
附带资源:
- - useFormatting钩子API参考文档
references/formatting-utilities.md - - ICU复数/选择语法说明
references/icu-messageformat.md - - 用于富文本的Trans组件说明
references/trans-component.md - - 实现与审查检查清单
checklists/i18n-checklist.md - - 完整组件示例
examples/component-i18n-example.md
标准参考文档: 详见获取完整的国际化标准文档。
docs/i18n-standards.mdCore 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 for the complete API.
references/formatting-utilities.md所有区域敏感的格式化必须使用集中式钩子:
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>
);
}详见获取完整API说明。
references/formatting-utilities.md3. Date Formatting
3. 日期格式化
All dates MUST use the centralized library:
@/lib/datestsx
import { formatDate, formatDateShort, calculateWaitTime } from '@/lib/dates';
const date = formatDate(appointment.date); // "Jan 6, 2026"
const waitTime = calculateWaitTime('09:30'); // "15 min"所有日期必须使用集中式的库:
@/lib/datestsx
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 for full syntax.
references/icu-messageformat.md在翻译文件中使用ICU语法处理复数:
json
{
"patients": "{count, plural, =0 {没有患者} one {#位患者} other {#位患者}}"
}tsx
t('patients', { count: 5 }) // → "5位患者"详见获取完整语法。
references/icu-messageformat.md5. 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 for patterns.
references/trans-component.md在翻译文本中嵌入React组件时使用:
tsx
import { Trans } from 'react-i18next';
<Trans
i18nKey="richText.welcome"
values={{ name: userName }}
components={{ strong: <strong /> }}
/>详见获取使用模式。
references/trans-component.mdTranslation 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> componenttypescript
// ❌ 绝对不要硬编码字符串
<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
快速参考
| Need | Solution |
|---|---|
| UI text | |
| Currency | |
| Lists | |
| Ordinals | |
| Dates | |
| Plurals | ICU MessageFormat in translation files |
| Rich text | |
| RTL check | |
| 需求 | 解决方案 |
|---|---|
| UI文本 | 来自 |
| 货币格式化 | 来自 |
| 列表格式化 | 来自 |
| 序数词格式化 | 来自 |
| 日期格式化 | 来自 |
| 复数处理 | 翻译文件中的ICU MessageFormat |
| 富文本 | |
| RTL检测 | 来自 |
Checklist
检查清单
See for complete implementation and review checklists.
checklists/i18n-checklist.md详见获取完整的实现与审查检查清单。
checklists/i18n-checklist.mdIntegration 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(), etc.)console.log - 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
相关技能
- - Comprehensive testing patterns including accessibility testing for i18n
testing-patterns - - Zod schemas for validating translation key structures and locale configs
type-safety-validation - - Server-side locale detection and RSC i18n patterns
react-server-components-framework - - RTL-aware focus management for bidirectional UI navigation
accessibility
- - 包含国际化无障碍测试的全面测试模式
testing-patterns - - 用于验证翻译键结构和区域配置的Zod模式
type-safety-validation - - 服务端区域检测与RSC国际化模式
react-server-components-framework - - 支持RTL的焦点管理,适用于双向UI导航
accessibility
Key Decisions
关键决策
| Decision | Choice | Rationale |
|---|---|---|
| Translation Library | react-i18next | React-native hooks, namespace support, ICU format |
| Date Library | dayjs | Lightweight, locale plugins, immutable API |
| Message Format | ICU MessageFormat | Industry standard, complex plural/select support |
| Locale Storage | Per-namespace JSON | Code-splitting, lazy loading per feature |
| RTL Detection | CSS logical properties | Native browser support, no JS overhead |
| 决策 | 选择 | 理由 |
|---|---|---|
| 翻译库 | react-i18next | React原生钩子、命名空间支持、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