# 画面設計書 187-翻訳一覧画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における翻訳一覧画面の設計仕様を定義する。

### 本画面の処理概要

翻訳一覧画面は、システムの多言語対応を管理するためのメイン画面である。翻訳可能なエンティティ（商品、カテゴリなど）の一覧と、各エンティティの翻訳完了状況を表示する。

**業務上の目的・背景**：
グローバルなEC運営において、商品情報やカテゴリ名などを複数の言語で提供することは顧客体験の向上に不可欠である。本画面では、どのエンティティに対してどの言語の翻訳が完了しているかを一元管理し、翻訳作業の進捗を把握できる。また、ロケールの追加や翻訳対象エンティティの設定変更への導線を提供し、多言語対応の効率的な運用を支援する。

**画面へのアクセス方法**：
設定画面 > 「翻訳」メニューをクリックすることでアクセスする。URLに直接アクセスすることも可能。

**主要な操作・処理内容**：
1. 翻訳可能なエンティティ一覧の閲覧 - 各エンティティの翻訳進捗を確認
2. エンティティ設定の管理 - 「Manage translatable entities」ボタンで設定画面へ
3. ロケールの管理 - サイドバーでアクティブなロケール一覧を確認
4. 翻訳編集画面への遷移 - 各エンティティの「Edit」ボタンで編集画面へ
5. ロケールの追加 - ロケールが未設定の場合は設定を促す

**画面遷移**：
- 遷移元：設定画面
- 遷移先：翻訳設定画面、翻訳編集画面、ロケール追加画面

**権限による表示制御**：
管理者権限を持つユーザーのみがアクセス可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 85 | 翻訳CRUD | 主機能 | 翻訳一覧の取得・表示 |

## 画面種別

一覧（2カラムレイアウト）

## URL/ルーティング

`/settings/translations`

## 入出力項目

本画面は一覧表示が主目的のため、入力項目はない。

## 表示項目

### メインエリア

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| タイトル | テキスト | "Manage Translations" |
| サブタイトル | テキスト | 翻訳管理の説明文 |
| エンティティ管理ボタン | ボタン | 翻訳設定画面への遷移 |
| ロケール未設定アラート | Alert | ロケールが未設定時に表示 |
| エンティティ一覧 | リスト | 翻訳可能エンティティの一覧 |

### エンティティ一覧項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| エンティティ名 | テキスト | エンティティのラベル（例：Product） |
| 翻訳状況 | テキスト | 翻訳済み/全体の件数 |
| 編集ボタン | ボタン | 翻訳編集画面への遷移 |

### サイドバー

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| アクティブロケール | リスト | 有効なロケールの一覧 |
| 翻訳完了状況 | プログレス/統計 | 言語別の翻訳完了率 |

## イベント仕様

### 1-画面初期表示

1. `useStore` でストア情報（サポートされているロケール）を取得
2. `useTranslationSettings` で翻訳設定を取得
3. `useTranslationStatistics` で翻訳統計情報を取得
4. データを統合して画面に表示

### 2-エンティティ管理ボタン押下

`/settings/translations/settings` へ遷移し、翻訳設定画面を表示する。

### 3-ロケール設定ボタン押下（アラート内）

`/settings/translations/add-locales` へ遷移し、ロケール追加画面を表示する。

### 4-エンティティの編集ボタン押下

`/settings/translations/edit?reference={エンティティ参照名}` へ遷移し、翻訳編集画面を表示する。

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面初期表示 | store | SELECT | ストア情報の取得 |
| 画面初期表示 | translation_setting | SELECT | 翻訳設定の取得 |
| 画面初期表示 | translation | SELECT | 翻訳統計の取得 |

### テーブル別更新項目詳細

本画面は参照のみのため、データベース更新は発生しない。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| translations.activeLocales.noLocalesTip | 情報 | ロケール未設定のヒント | supported_localesが空の場合 |
| translations.activeLocales.noLocalesTipConfigureAction | アクション | 設定を促すボタンラベル | supported_localesが空の場合 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|----------|
| API通信エラー | エラーをスローし、エラーバウンダリでキャッチ |
| データ取得中 | TwoColumnPageSkeletonを表示 |

## 備考

- TwoColumnPageレイアウトを使用
- 翻訳機能はFeature Flagで制御されている（translation）
- product_option, product_option_valueはエンティティ一覧から除外
- エンティティ名はsnake_caseからTitle Caseに変換して表示
- ロケールが未設定の場合、編集ボタンは無効化される

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、翻訳関連のデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | translation-list.tsx | `packages/admin/dashboard/src/routes/translations/translation-list/translation-list.tsx` | 17-23行目: TranslatableEntity型の定義 |

**読解のコツ**: TranslatableEntityはlabel, reference, translatableFields, translatedCount, totalCountを持つ。

#### Step 2: エントリーポイントを理解する

画面のメインコンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | translation-list.tsx | `packages/admin/dashboard/src/routes/translations/translation-list/translation-list.tsx` | 全体構造とデータ取得 |

**主要処理フロー**:
1. **29行目**: useStoreでストア情報を取得
2. **31-37行目**: useTranslationSettingsで翻訳設定を取得（is_active: true）
3. **39-57行目**: useTranslationStatisticsで翻訳統計を取得
4. **65-96行目**: translatableEntitiesを計算（product_option等を除外、Title Case変換）
5. **117-186行目**: TwoColumnPageでレイアウト構築

#### Step 3: サブコンポーネントを理解する

各セクションの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | translation-list-section.tsx | `.../components/translation-list-section/translation-list-section.tsx` | エンティティ一覧の表示 |
| 3-2 | active-locales-section.tsx | `.../components/active-locales-section/active-locales-section.tsx` | アクティブロケール表示 |
| 3-3 | translations-completion-section.tsx | `.../components/translations-completion-section/translations-completion-section.tsx` | 翻訳完了状況表示 |

**主要処理フロー（translation-list-section）**:
- **19-46行目**: entitiesをマップしてリスト表示
- **33-43行目**: Linkで翻訳編集画面へ遷移（hasLocalesとtotalCountで有効/無効制御）

#### Step 4: API連携を理解する

APIフックの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | translations.tsx | `packages/admin/dashboard/src/hooks/api/translations.tsx` | 翻訳関連のAPIフック |

**主要処理フロー**:
- **157-176行目**: useTranslationSettingsで設定取得
- **222-241行目**: useTranslationStatisticsで統計取得

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

```
TranslationList (translation-list.tsx)
    │
    ├─ useStore() - ストア情報取得
    │      └─ sdk.admin.store.retrieve()
    │
    ├─ useTranslationSettings() - 翻訳設定取得
    │      └─ sdk.admin.translation.settings()
    │
    ├─ useTranslationStatistics() - 翻訳統計取得
    │      └─ sdk.admin.translation.statistics()
    │
    ├─ TwoColumnPage.Main
    │      │
    │      ├─ エンティティ管理ボタン - /settings/translations/settings
    │      │
    │      ├─ Alert（ロケール未設定時）- /settings/translations/add-locales
    │      │
    │      └─ TranslationListSection
    │             └─ 各エンティティ - /settings/translations/edit?reference=xxx
    │
    └─ TwoColumnPage.Sidebar
           ├─ ActiveLocalesSection
           └─ TranslationsCompletionSection
```

### データフロー図

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

ストア情報 ───▶ ロケール抽出 ───▶ サイドバー表示
                                  アラート表示判定

翻訳設定 ───▶ エンティティ変換 ───▶ エンティティ一覧
              (Title Case変換)

翻訳統計 ───▶ 進捗計算 ───▶ 翻訳完了状況表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| translation-list.tsx | `packages/admin/dashboard/src/routes/translations/translation-list/translation-list.tsx` | ソース | 一覧画面のメインコンポーネント |
| translation-list-section.tsx | `.../components/translation-list-section/translation-list-section.tsx` | ソース | エンティティ一覧セクション |
| active-locales-section.tsx | `.../components/active-locales-section/active-locales-section.tsx` | ソース | アクティブロケールセクション |
| translations-completion-section.tsx | `.../components/translations-completion-section/translations-completion-section.tsx` | ソース | 翻訳完了状況セクション |
| translations.tsx | `packages/admin/dashboard/src/hooks/api/translations.tsx` | ソース | 翻訳APIフック |
| TwoColumnPage | `packages/admin/dashboard/src/components/layout/pages` | ソース | 2カラムレイアウト |
