i18n-date-patterns

i18n とローカライズのパターン

概要

このスキルでは、React アプリケーションに国際化を実装するための包括的なガイダンスを提供します。ユーザーに表示されるすべての文字列、日付表示、通貨、リスト、時刻の計算がロケールに対応するようにします。

このスキルを使用する場面：

• コンポーネントにユーザー向けのテキストを追加するとき
• 日付、時刻、通貨、リスト、序数をフォーマットするとき
• 複雑な複数形処理を実装するとき
• 翻訳テキストに React コンポーネントを埋め込むとき
• RTL 言語（ヘブライ語、アラビア語）をサポートするとき

同梱リソース（Read("<path>") で読み込みます）：

• references/formatting-utilities.md - useFormatting フックの API リファレンス
• references/ork-delta.md - 上流ドキュメントに含まれていない、プロジェクト内の決定事項と運用設定
• checklists/i18n-checklist.md - 実装およびレビュー用チェックリスト
• examples/component-i18n-example.md - コンポーネントの完全な例

正式なリファレンス： i18n 標準の全ドキュメントについては、docs/i18n-standards.md を参照してください。

---

基本パターン

1. useTranslation フック（すべての 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 フック（ロケール対応データ）

ロケールに依存するフォーマットには、すべて一元化されたフックを使用する必要があります。

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

API 全体については、Read("references/formatting-utilities.md") を読み込んでください。

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 を使用しない、インデックス付きタグより名前付きタグを優先
i18next への ICU パーサーの組み込み	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 にプロジェクト内のフック API を記載
useFormatting の基盤となる Intl.NumberFormat	https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat	references/formatting-utilities.md にプロジェクト内のフック 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") を読み込んでください。

---

エージェントとの連携

フロントエンド UI 開発者

• コンポーネントで i18n のパターンをすべて使用します
• 書式設定についてこのスキルを参照します
• ハードコードされた文字列がないことを確認します

コード品質レビュアー

• アンチパターン（.join()、console.log など）を確認します
• 翻訳キーの網羅性を検証します
• RTL との互換性を確認します

---

スキルのバージョン: 1.2.0 最終更新日: 2026-01-06 メンテナンス担当: Yonatan Gross

関連スキル

• ork:testing-e2e - i18n のアクセシビリティテストを含む E2E テストのパターン
• 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 hook, translation hook 解決する課題:

• useTranslation で UI 文字列を翻訳します
• 名前空間付きの翻訳を実装します
• 翻訳キーの欠落に対処します

formatting-hooks

キーワード: useFormatting, formatCurrency, formatList, formatOrdinal 解決する課題:

• ロケールに応じて通貨の値を書式設定します
• 適切な区切り文字を使ってリストを書式設定します
• ロケールごとの序数を処理します

icu-messageformat

キーワード: ICU, MessageFormat, plural, pluralization 解決する課題:

• このプロジェクトで定めたヘブライ語の複数形カテゴリーの方針を適用します（references/ork-delta.md を参照）
• ICU の select、性別形、および入れ子のメッセージ文法は上流に委ねます（Upstream coverage を参照）
• 複雑なメッセージパターンを構築します

date-time-formatting

キーワード: date format, time format, dayjs, locale date, calendar 解決する課題:

• dayjs とロケールを使って日付を書式設定します
• タイムゾーンを考慮した書式設定に対応します
• i18n 対応のカレンダーコンポーネントを構築します

rtl-support

キーワード: RTL, right-to-left, hebrew, arabic, direction 解決する課題:

• ヘブライ語などの RTL 言語に対応します
• 双方向テキストを処理します
• RTL 対応のレイアウトを設定します

trans-component

キーワード: Trans, rich text, embedded JSX, interpolation 解決する課題:

• 翻訳に React コンポーネントを埋め込みます
• リッチテキストの書式設定に対応します
• 翻訳内で安全な HTML を実装します