i18n-date-patterns

i18n 与本地化模式

概述

本技能全面介绍如何在 React 应用中实现国际化，确保所有面向用户的字符串、日期显示、货币、列表和时间计算都能适配区域设置。

适用场景：

• 向组件添加任何面向用户的文本
• 格式化日期、时间、货币、列表或序数
• 实现复杂的复数形式
• 在翻译文本中嵌入 React 组件
• 支持 RTL 语言（希伯来语、阿拉伯语）

捆绑资源（使用 Read("<path>") 加载）：

• references/formatting-utilities.md - useFormatting hook API 参考
• references/ork-delta.md - 上游文档未涵盖的内部决策和工作配置
• checklists/i18n-checklist.md - 实施与审查清单
• examples/component-i18n-example.md - 完整组件示例

规范参考： 完整的 i18n 标准文档见 docs/i18n-standards.md。

---

核心模式

1. useTranslation Hook（所有 UI 字符串）

所有可见字符串都必须使用翻译函数：

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（区域设置感知数据）

所有受区域设置影响的格式化都必须使用集中式 hook：

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>
  );
}

使用 Read("references/formatting-utilities.md") 加载完整 API。

3. 日期格式化

所有日期都必须使用集中式 @/lib/dates 库：

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（复杂复数形式）

在翻译文件中使用 ICU 语法处理复数形式：

{
  "patients": "{count, plural, =0 {No patients} one {# patient} other {# patients}}"
}

t('patients', { count: 5 })  // → "5 patients"

复数形式的内部规则见 rules/i18n-icu-plurals.md。完整的 ICU 语法请参阅下方的上游表格。

5. Trans 组件（富文本）

在翻译文本中嵌入 React 组件时：

import { Trans } from 'react-i18next';

<Trans
  i18nKey="richText.welcome"
  values={{ name: userName }}
  components={{ strong: <strong /> }}
/>

<Trans> 的内部规则见 rules/i18n-trans-component.md；复数形式与富文本的顺序约束见 references/ork-delta.md。完整的组件 API 请参阅下方的上游表格。

---

上游文档涵盖范围（此处不再赘述）

以下主题由一手文档负责。请直接阅读这些文档，而不是在此重新推导。

主题	一手资料	此处保留的内部子集
ICU 复数、select、selectordinal、offset 和嵌套消息语法	https://formatjs.github.io/docs/core-concepts/icu-syntax/ and https://unicode-org.github.io/icu/userguide/format_parse/messages/	rules/i18n-icu-plurals.md 完整保留内部子集：不使用三元复数形式，必须包含 other 分支，零状态使用 =0，以及希伯来语双数和阿拉伯语类别
特定区域设置实际具有哪些复数类别	https://cldr.unicode.org/index/cldr-spec/plural-rules	无，请阅读上游文档
消息中的 ICU 数字骨架（::currency/ILS）	https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html	references/ork-delta.md 仅保留 ILS 骨架决策
消息内的日期和时间格式（{date, date, medium}）以及 offset: 复数形式	https://unicode-org.github.io/icu/userguide/format_parse/messages/	无，请查阅上游文档
<Trans> API：命名标签与索引标签、自闭合标签、TransProps 类型定义	https://react.i18next.com/latest/trans-component	rules/i18n-trans-component.md 完整保留内部子集：绝不将一个句子拆分到多个 t() 调用中，绝不使用 dangerouslySetInnerHTML，优先使用命名标签而非索引标签
将 ICU 解析器接入 i18next	https://github.com/i18next/i18next-icu	references/ork-delta.md 保留了相关决策以及后缀键为何不足以满足需求的原因
useFormatting 背后的 Intl.ListFormat 基元	https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat	references/formatting-utilities.md 保留内部 hook API
useFormatting 背后的 Intl.NumberFormat 基元	https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat	references/formatting-utilities.md 保留内部 hook API

---

翻译文件结构

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)

---

反模式（禁止）

// ❌ 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

---

快速参考

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

---

检查清单

加载 Read("checklists/i18n-checklist.md")，查看完整的实现和审查检查清单。

---

与 Agent 的集成

前端 UI 开发者

• 在组件中使用所有 i18n 模式
• 参考此技能进行格式化
• 确保没有硬编码字符串

代码质量审查者

• 检查反模式（.join()、console.log 等）
• 验证翻译键覆盖情况
• 确保兼容 RTL

---

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

相关技能

• ork:testing-e2e - E2E 测试模式，包括 i18n 的无障碍测试
• ork:react-server-components-framework - 服务端语言区域检测和 RSC i18n 模式
• ork:accessibility - 为双向 UI 导航提供 RTL 感知的焦点管理

关键决策

决策	选择	理由
翻译库	react-i18next	React 原生钩子、命名空间支持、ICU 格式
日期库	dayjs	轻量、语言区域插件、不可变 API
消息格式	ICU MessageFormat	行业标准，支持复杂的复数和选择格式
语言区域存储	按命名空间划分的 JSON	代码分割，按功能延迟加载
RTL 检测	CSS 逻辑属性	原生浏览器支持，无需额外的 JS 开销

功能详情

translation-hooks

关键词： useTranslation、t()、i18n 钩子、翻译钩子 解决的问题：

• 使用 useTranslation 翻译 UI 字符串
• 实现命名空间翻译
• 处理缺失的翻译键

formatting-hooks

关键词： useFormatting、formatCurrency、formatList、formatOrdinal 解决的问题：

• 根据语言区域格式化货币值
• 使用正确的分隔符格式化列表
• 处理不同语言区域中的序数

icu-messageformat

关键词： ICU、MessageFormat、复数、复数化 解决的问题：

• 应用项目的希伯来语复数类别决策（参见 references/ork-delta.md）
• ICU select、性别形式和嵌套消息语法交由上游处理（参见“上游覆盖范围”）
• 构建复杂的消息模式

date-time-formatting

关键词： 日期格式、时间格式、dayjs、本地化日期、日历 解决的问题：

• 使用 dayjs 和语言区域格式化日期
• 处理时区感知格式
• 使用 i18n 构建日历组件

rtl-support

关键词： RTL、从右向左、希伯来语、阿拉伯语、方向 解决的问题：

• 支持希伯来语等 RTL 语言
• 处理双向文本
• 配置兼容 RTL 的布局

trans-component

关键词： Trans、富文本、嵌入式 JSX、插值 解决的问题：

• 在翻译中嵌入 React 组件
• 处理富文本格式
• 在翻译中实现安全的 HTML