# 機能設計書 23-I18n

## 概要

本ドキュメントは、Ruby on Railsの国際化（I18n: Internationalization）機能の設計仕様を定義する。I18nは、アプリケーションのテキストを翻訳ファイルで管理し、多言語対応を実現するための基盤機能である。

### 本機能の処理概要

**業務上の目的・背景**：グローバル展開するWebアプリケーションでは、ユーザーの言語設定に応じて画面表示を切り替える必要がある。I18n機能は、ハードコードされた文字列を翻訳キーに置き換え、ロケールに応じた翻訳テキストを動的に取得することで、コードの変更なしに多言語対応を実現する。また、日付・時刻・数値のフォーマットもロケールに応じて自動変換される。

**機能の利用シーン**：多言語サポートが必要なWebアプリケーション、エラーメッセージの地域化、フォーム入力のバリデーションメッセージ、メール本文の多言語化、日付・数値のローカライズ表示など、あらゆるテキスト出力場面で使用される。

**主要な処理内容**：
1. ロケール設定の管理（default_locale、available_locales）
2. 翻訳ファイル（YAML/Ruby）の読み込みとパース
3. 翻訳キーに基づく翻訳テキストの取得（I18n.t / t ヘルパー）
4. ローカライゼーション処理（I18n.l / l ヘルパー）
5. フォールバック処理（翻訳が見つからない場合のデフォルト値）
6. 補間変数の展開（%{name} 形式）

**関連システム・外部連携**：i18n gem（Ruby標準）と連携する。Active Model、Active Record、Action Viewなど各コンポーネントがI18n機能を利用してエラーメッセージやラベルを国際化する。

**権限による制御**：特になし。ロケール切り替えはリクエストごとに設定可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 7 | メールプレビュー画面 | 補助機能 | ロケール切り替えによる多言語プレビュー表示 |

## 機能種別

テキスト変換 / 設定管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| key | String/Symbol | Yes | 翻訳キー | ドット区切りのキーパス |
| locale | Symbol | No | 対象ロケール | available_localesに含まれること |
| default | String/Array | No | デフォルト値 | - |
| scope | String/Array | No | キーのスコープ | - |
| count | Integer | No | 複数形判定用の数値 | - |
| 補間変数 | Hash | No | %{var}形式で埋め込む変数 | - |

### 入力データソース

- 翻訳ファイル（config/locales/*.yml, *.rb）
- ロケール設定（I18n.locale）
- ビューテンプレートでのtヘルパー呼び出し

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| translated_text | String | 翻訳されたテキスト |
| localized_value | String | ローカライズされた日付・数値 |

### 出力先

- ビューテンプレート
- コンソール出力
- ログメッセージ
- メール本文

## 処理フロー

### 処理シーケンス

```
1. アプリケーション起動時
   └─ I18n::Railtie.initialize_i18n で初期化
   └─ config/locales/*.yml を読み込み
2. リクエスト処理時
   └─ I18n.locale を設定（before_action等）
3. 翻訳取得（I18n.t / t ヘルパー）
   └─ キー正規化
   └─ バックエンドから翻訳取得
   └─ 補間変数の展開
   └─ フォールバック処理
4. ローカライゼーション（I18n.l / l ヘルパー）
   └─ ロケールに応じた書式適用
```

### フローチャート

```mermaid
flowchart TD
    A[I18n.t 呼び出し] --> B[キー正規化]
    B --> C[ロケール決定]
    C --> D[バックエンドから検索]
    D --> E{翻訳あり?}
    E -->|Yes| F[補間変数展開]
    E -->|No| G{フォールバック設定?}
    G -->|Yes| H[フォールバックロケールで検索]
    G -->|No| I{default指定?}
    H --> E
    I -->|Yes| J[default値を返却]
    I -->|No| K[MissingTranslation例外/span]
    F --> L[翻訳テキスト返却]
    J --> L
    K --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-23-01 | ロケールスレッド安全性 | I18n.localeはスレッドローカル | 並行リクエスト処理時 |
| BR-23-02 | 複数形ルール | countに応じてone/other/zero等を選択 | 言語ごとの複数形ルールに従う |
| BR-23-03 | フォールバック | 翻訳未定義時にデフォルトロケールにフォールバック | fallbacks設定が有効な場合 |
| BR-23-04 | 遅延評価 | LazyスコープでViewパスから自動キー生成 | Viewテンプレート内でのt呼び出し |

### 計算ロジック

翻訳キーの解決順序：
```ruby
# Viewでの t('.title') の場合
# テンプレートパス: users/show.html.erb
# 解決キー: users.show.title
```

複数形の判定：
```ruby
# count: 0 -> :zero (定義されていれば)
# count: 1 -> :one
# count: 2以上 -> :other
```

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

### テーブル別操作詳細

本機能はデータベースを直接操作しない。翻訳データはYAMLファイルまたはRubyファイルから読み込まれる。カスタムバックエンド（ActiveRecord Backend等）を使用する場合はデータベース操作が発生する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| I18n::MissingTranslation | TranslationError | 翻訳キーが見つからない | default値を指定、または翻訳ファイルに追加 |
| I18n::InvalidLocale | ArgumentError | 無効なロケール指定 | available_localesに追加 |
| I18n::InvalidPluralizationData | ArgumentError | 複数形データが不正 | 翻訳ファイルの形式を確認 |

### リトライ仕様

翻訳取得は同期処理のためリトライ不要。ファイル読み込みエラー時はアプリケーション起動が失敗する。

## トランザクション仕様

本機能はデータベーストランザクションを使用しない。

## パフォーマンス要件

- 翻訳ファイルは起動時に一度だけ読み込み
- I18n.tの呼び出しは高速（ハッシュルックアップ）
- 開発環境では翻訳ファイルの変更を自動検出して再読み込み

## セキュリティ考慮事項

- ユーザー入力を翻訳キーとして使用しないこと
- 翻訳テキストにHTMLを含む場合はhtml_safe対応が必要
- 翻訳ファイルに機密情報を含めないこと

## 備考

- i18n gem はRuby標準ライブラリ
- Rails固有の拡張はActiveSupport::I18nRailtieで提供
- カスタムバックエンド（Redis、DB等）も利用可能

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: I18n初期化を理解する

Rails起動時のI18n設定初期化処理を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | i18n_railtie.rb | `activesupport/lib/active_support/i18n_railtie.rb` | initialize_i18nメソッド、ロードパス設定、フォールバック設定 |

**読解のコツ**: I18n::Railtieクラスがconfig.i18nの設定をi18n gemに反映する。

**主要処理フロー**:
- **36-82行目**: initialize_i18n メソッドでI18n設定を初期化
- **48-61行目**: config.i18n の各設定をI18nに適用
- **63行目**: フォールバック設定の初期化
- **68-79行目**: 開発環境でのファイル変更監視設定

#### Step 2: ActiveSupportのI18n統合を理解する

ActiveSupportが提供するI18n統合機能を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | i18n.rb | `activesupport/lib/active_support/i18n.rb` | i18n gemのrequire、デフォルトロードパス設定 |

**主要処理フロー**:
- **6-12行目**: i18n gem の require とエラーハンドリング
- **15-17行目**: ActiveSupportのロードフック実行とデフォルトロケールファイル追加

#### Step 3: ビューヘルパーを理解する

ビューテンプレートで使用するtヘルパーの実装を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | translation_helper.rb | `actionview/lib/action_view/helpers/translation_helper.rb` | t/translateヘルパー、html_safe対応、Lazyスコープ |

**読解のコツ**: tヘルパーは I18n.t のラッパーで、Viewパスからの自動スコープ解決や_html接尾辞の自動html_safe化などのRails固有機能を追加している。

### プログラム呼び出し階層図

```
アプリケーション起動
    │
    ├─ Rails::Application.initialize!
    │      │
    │      └─ I18n::Railtie.initialize_i18n (36行目)
    │             │
    │             ├─ config.i18n設定の適用 (48-61行目)
    │             │
    │             └─ I18n.load_path += [locale_files]
    │
View Template (ERBテンプレート)
    │
    └─ t('.key') / translate('.key')
           │
           └─ ActionView::Helpers::TranslationHelper#translate
                  │
                  ├─ scope解決（Viewパスから）
                  │
                  └─ I18n.t(key, options)
                         │
                         └─ I18n::Backend::Simple#translate
                                │
                                ├─ 翻訳ルックアップ
                                │
                                └─ 補間処理
```

### データフロー図

```
[入力]                      [処理]                           [出力]

config/locales/*.yml ───▶ I18n.load_path ───▶ 翻訳データ（メモリ）
                                │
                                ▼
Viewテンプレート ───▶ t('key') ヘルパー ───▶ 翻訳テキスト
      │                        │
      │                        ▼
I18n.locale設定 ───▶ ロケール判定
                                │
                                ▼
                        ┌─────────────────┐
                        │ I18n Backend    │
                        │ (Simple/Chain) │───▶ 翻訳済みテキスト
                        └─────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| i18n_railtie.rb | `activesupport/lib/active_support/i18n_railtie.rb` | ソース | I18n初期化、Railtie統合 |
| i18n.rb | `activesupport/lib/active_support/i18n.rb` | ソース | i18n gem のrequireとロードパス設定 |
| translation_helper.rb | `actionview/lib/action_view/helpers/translation_helper.rb` | ソース | ビュー用t/lヘルパー |
| translation.rb | `activemodel/lib/active_model/translation.rb` | ソース | モデル属性名の翻訳 |
| translation.rb | `activerecord/lib/active_record/translation.rb` | ソース | ARモデル属性名の翻訳 |
| en.yml | `activesupport/lib/active_support/locale/en.yml` | 設定 | ActiveSupportデフォルト翻訳 |
| en.yml | `activemodel/lib/active_model/locale/en.yml` | 設定 | ActiveModelデフォルト翻訳 |
| en.yml | `activerecord/lib/active_record/locale/en.yml` | 設定 | ActiveRecordデフォルト翻訳 |
