# 画面設計書 70-翻訳リソース

## 概要

本ドキュメントは、serve-d LSPサーバーの翻訳リソース機能の画面設計書である。エディタ上に表示されるメッセージの多言語翻訳リソースを管理し、en（英語）、de（ドイツ語）、fr（フランス語）、ja（日本語）、ru（ロシア語）の5言語に対応する。

### 本画面の処理概要

本機能は、serve-dおよび関連するエディタ拡張（code-d等）が表示するユーザー向けメッセージの翻訳機能を提供する。

**業務上の目的・背景**：serve-dはD言語の国際的な開発コミュニティで使用されるLSPサーバーであり、ダイアログメッセージ・エラー通知・UI要素のテキストを多言語で提供する必要がある。翻訳リソースは静的ファイルとして管理され、コンパイル時にバイナリに埋め込まれる。ランタイムではユーザーの言語設定に基づいて適切な翻訳が選択される。翻訳が見つからない場合は英語にフォールバックする。

**画面へのアクセス方法**：翻訳機能は内部的に使用される。エラーメッセージ、ダイアログメッセージ、設定の説明文等の表示時に自動的に呼び出される。`translate` テンプレート関数にメッセージキーを指定することで翻訳テキストが取得される。

**主要な操作・処理内容**：
1. コンパイル時にviews/ディレクトリの各言語ファイル（en.txt, de.txt, fr.txt, ja.txt, ru.txt）をインポートする
2. 共有静的コンストラクタで各言語の翻訳辞書をパースして登録する
3. ランタイムで `translate` 関数が呼ばれると、現在の言語設定に基づいて翻訳テキストを返却する
4. プレースホルダ（{0}, {1}等）や複数形（{plural ...}）の動的フォーマットを実行する

**画面遷移**：
- 遷移元：serve-d内の各機能（ダイアログ表示、エラー通知等）
- 遷移先：なし（テキスト変換のみ）

**権限による表示制御**：特になし。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 81 | 翻訳・多言語対応 | 主機能 | エディタ上に表示されるメッセージの翻訳リソースをen, de, fr, ja, ruの各言語で提供する |

## 画面種別

内部ユーティリティ（翻訳リソース管理）

## URL/ルーティング

本機能はLSPリクエスト/通知ではなく、内部ユーティリティとして機能する。

## 入出力項目

### translate関数

| 項目名 | 型 | 説明 |
|--------|------|------|
| s（コンパイル時引数） | string | メッセージキー（例: "d.ext.dcdFail"） |
| args（ランタイム引数） | 可変長 | プレースホルダに代入する値 |
| (戻り値) | string | 翻訳済みメッセージテキスト |

## 表示項目

### 翻訳リソースのカテゴリ一覧

翻訳リソースは以下のカテゴリに分類される：

| カテゴリ | キープレフィックス | 説明 |
|---------|-----------------|------|
| コマンド | d.switchConfiguration, d.killServer 等 | エディタコマンドの名称 |
| 設定説明 | d.config.* | 設定項目の説明文 |
| 拡張メッセージ | d.ext.* | エラー・警告・情報メッセージ |
| プロジェクト | d.projects.* | プロジェクト作成関連メッセージ |
| インストーラ | d.installer.* | コンポーネントインストール関連メッセージ |
| DUB | d.dub.* | DUBパッケージ管理関連メッセージ |
| カバレッジ | d.coverage.* | コードカバレッジ関連メッセージ |
| serve-d | d.served.* | serve-d固有のメッセージ |

### 対応言語

| 言語コード | ファイル | 説明 |
|-----------|---------|------|
| en | views/en.txt | 英語（デフォルト・フォールバック） |
| de | views/de.txt | ドイツ語 |
| fr | views/fr.txt | フランス語 |
| ja | views/ja.txt | 日本語 |
| ru | views/ru.txt | ロシア語 |

## イベント仕様

### 1-翻訳辞書の初期化（shared static this）

1. コンパイル時に `import("en.txt")` 等でviews/ディレクトリの各言語ファイルをインポートする
2. `parseTranslation` でコンパイル時に各ファイルをパースする
3. 翻訳辞書は `Translation[string]` 型（`string[string][string]`、外側が言語コード・内側がメッセージキー）で管理される

### 2-翻訳テキスト取得（translate関数）

1. `currentLanguage` 設定値に基づいて翻訳辞書を検索する
2. 現在の言語で翻訳が見つかった場合はそのテキストを使用する
3. 見つからない場合は英語（en）のテキストにフォールバックする
4. 英語にも見つからない場合はメッセージキーをそのまま返却し、warningログを出力する
5. `formatTranslation` でプレースホルダの置換を実行する

### 3-プレースホルダフォーマット（formatTranslation関数）

1. テキスト内の `{N}` パターン（Nは数字）を対応する引数の値に置換する
2. `{plural #form {argIndex} {singular} {plural}}` パターンでMozillaの複数形ルールに基づく複数形処理を実行する
3. エスケープシーケンス（`\n`, `\t`, `\r`, `\\`）を処理する

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

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

本機能はデータベースへの更新を行わない。翻訳辞書はコンパイル時に構築され、ランタイムでは読み取り専用。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 翻訳テキスト取得 | translations（インメモリ） | SELECT（読み取り） | 翻訳辞書からメッセージを検索 |

## メッセージ仕様

| メッセージID | 種別 | 表示条件 | メッセージ内容 |
|-------------|------|---------|--------------|
| なし（ログ） | 警告 | 翻訳が見つからない場合 | "No translation for string '{s}' for neither english nor selected language {currentLanguage}!" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 翻訳キーが見つからない（英語含む） | キー文字列をそのまま返却し、warningログを出力 |
| 不正な複数形フォーマット | Exception送出（"Malformed plural argument"） |
| 不正なプレースホルダインデックス | 空文字列に置換 |

## 備考

- 翻訳ファイルは `key: value` 形式のテキストファイル。`#` で始まる行はコメントとして無視される
- `currentLanguage` 変数のデフォルト値は "en"（英語）
- 複数形処理はMozillaのplural formsルール（https://developer.mozilla.org/en-US/docs/Mozilla/Localization/Localization_and_Plurals ）に基づき、19種類のフォーム（0-18, 19）をサポートする
- D言語のコンパイル時機能（`import()` 式、CTFEによるパース）を活用して翻訳辞書をコンパイル時に構築している
- views/ddocs.txt は翻訳リソースではなく、DDocコメント補完用のデータファイル

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | translate.d | `source/served/utils/translate.d` | 行10-12のTranslation型エイリアスとtranslations辞書 |

**読解のコツ**: `Translation` は `string[string]` のエイリアス。`translations` は `Translation[string]` 型で、外側のキーが言語コード（"en", "ja"等）、内側のキーがメッセージキー。

#### Step 2: 初期化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | translate.d | `source/served/utils/translate.d` | 行14-23の`shared static this`で翻訳辞書を初期化 |
| 2-2 | translate.d | `source/served/utils/translate.d` | 行25-37の`parseTranslation`でキー:値形式をパース |

**主要処理フロー**:
1. **行16-22**: `import("en.txt")` 等のD言語コンパイル時インポートで各言語ファイルを読み込み
2. **行25-37**: `parseTranslation` がCTFEでファイル内容をパースし、`#` コメント行を除外、`:` でキーと値を分割

#### Step 3: 翻訳関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | translate.d | `source/served/utils/translate.d` | 行41-57の`translate`テンプレート関数 |
| 3-2 | translate.d | `source/served/utils/translate.d` | 行59-226の`formatTranslation`関数 |

**主要処理フロー**:
- **行44-45**: 現在の言語で翻訳を検索
- **行47-48**: 見つからなければ英語にフォールバック
- **行50-55**: 英語にも見つからなければwarning出力してキーを返却
- **行56**: `formatTranslation` でプレースホルダ置換

#### Step 4: 複数形処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | translate.d | `source/served/utils/translate.d` | 行248-426の`resolvePlural`関数 |

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

```
serve-d 各機能（ダイアログ、エラー通知等）
    |
    +-- translate!"d.ext.dcdFail"(arg0, arg1)     [translate.d:41]
           |
           +-- translations[currentLanguage]       [言語辞書検索]
           |
           +-- translations["en"]                  [フォールバック]
           |
           +-- formatTranslation()                 [translate.d:59]
                  |
                  +-- {N} プレースホルダ置換
                  +-- {plural ...} 複数形処理
                  |      +-- resolvePlural()        [translate.d:248]
                  +-- エスケープシーケンス処理
```

### データフロー図

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

views/en.txt ─┐
views/de.txt ─┤
views/fr.txt ─┼─(コンパイル時)──> parseTranslation()   --> translations辞書
views/ja.txt ─┤                                            (インメモリ)
views/ru.txt ─┘

メッセージキー ──(ランタイム)──> translate()            --> 翻訳済みテキスト
+ フォーマット引数              |
                               +-- 辞書検索
                               +-- フォールバック
                               +-- formatTranslation()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| translate.d | `source/served/utils/translate.d` | ソース | 翻訳エンジン（translate, formatTranslation, resolvePlural関数） |
| en.txt | `views/en.txt` | リソース | 英語翻訳リソース（デフォルト/フォールバック） |
| de.txt | `views/de.txt` | リソース | ドイツ語翻訳リソース |
| fr.txt | `views/fr.txt` | リソース | フランス語翻訳リソース |
| ja.txt | `views/ja.txt` | リソース | 日本語翻訳リソース |
| ru.txt | `views/ru.txt` | リソース | ロシア語翻訳リソース |
| ddocs.txt | `views/ddocs.txt` | リソース | DDocコメント補完用データ（翻訳リソースではない） |
