# バッチ設計書 43-ConvertTo-PseudoLocalization

## 概要

リソースファイル（.resw/.xml）内の文字列を擬似ローカライズ（Pseudo-Localization）に変換するPowerShellスクリプトの設計書である。

### 本バッチの処理概要

本バッチは、指定されたリソースファイル内のテキスト文字列を、各ASCII文字をUnicode類似文字に置換することで擬似ローカライズされたテキストに変換する。LocStudioのPseudoReplacementDefs.xmlに準拠した文字マッピングを使用し、ロック対象文字列の保護、SHA1ベースの決定論的乱数による文字選択、40%のパディング追加を行う。

**業務上の目的・背景**：擬似ローカライズ（Pseudo-Localization、qps-ploc）は、国際化（i18n）テストの手法である。実際の翻訳を行わずに、文字列が正しくレンダリングされるか、UIレイアウトが長い文字列に対応できるか、ハードコードされた文字列が残っていないかを検出するために使用される。これにより、リリース前にローカライズ関連の問題を早期発見できる。

**バッチの実行タイミング**：ビルドプロセスの一部として、またはGenerate-PseudoLocalizations.ps1（No.44）から呼び出されて実行される。

**主要な処理内容**：
1. ASCII文字からUnicode類似文字へのマッピングテーブルの定義（a-z、A-Zの52文字分）
2. リソースファイル（.resw または .xml）の読み込みとパース
3. `{Locked=...}`コメントで保護された文字列のプレースホルダー置換
4. SHA1ハッシュベースの決定論的乱数による文字マッピング適用
5. 変換後文字列への40%パディング追加
6. .xml形式の場合、`_locID`属性と`_locComment_text`コメントの除去

**前後の処理との関連**：Generate-PseudoLocalizations.ps1（No.44）から呼び出される。en-USリソースファイルを入力とし、qps-plocディレクトリに出力される。

**影響範囲**：擬似ローカライズされたリソースファイルが生成され、qps-plocロケールでのUI表示に影響する。

## バッチ種別

データ変換（擬似ローカライズ生成）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（ビルド時） |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | ビルドプロセス / Generate-PseudoLocalizations.ps1からの呼び出し |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| リソースファイルの存在 | Pathパラメータで指定された.reswまたは.xmlファイルが存在すること |
| ファイル形式 | 入力ファイルが.reswまたは.xml形式であること |
| PowerShell実行環境 | PowerShellが利用可能であること |

### 実行可否判定

必須パラメータ（Path）が指定されており、かつファイルが.reswまたは.xml拡張子であること。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| Path | string | Yes | なし | 変換対象のリソースファイルパス（.reswまたは.xml） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| リソースファイル | .resw（XML） | `/root/data`要素に`name`、`value`、`comment`を持つリソースファイル |
| リソースファイル | .xml | `_locID`属性を持つ要素と`_locComment_text`コメントを含むXMLファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 戻り値（XmlDocument） | XMLオブジェクト | 擬似ローカライズ変換後のXMLDocumentオブジェクト |

### 出力ファイル仕様

本バッチはXmlDocumentオブジェクトを返却する。ファイルへの保存は呼び出し元が行う。

| 項目 | 内容 |
|-----|------|
| ファイル名 | 呼び出し元で決定 |
| 出力先 | 呼び出し元で決定 |
| 文字コード | 呼び出し元で決定（通常UTF-8 BOMなし） |
| 区切り文字 | N/A（XML形式） |

## 処理フロー

### 処理シーケンス

```
1. 文字マッピングテーブルの初期化
   └─ a-z、A-Z各文字に対応するUnicode類似文字群を定義
2. XMLファイルの読み込み
   └─ XmlDocument.Load()でPreserveWhitespace=trueとして読み込み
3. ファイル拡張子による分岐
   ├─ .reswの場合: /root/data要素を反復処理
   │   └─ 各data要素のvalueをGetPseudoLocalization関数で変換
   └─ .xmlの場合: //*[@_locID]要素を反復処理
       ├─ 各テキストノードをGetPseudoLocalization関数で変換
       ├─ _locComment_textコメントを除去
       └─ _locID属性を除去
4. GetPseudoLocalization関数の処理詳細
   └─ 4a. {Locked=...}コメントのパース
       └─ {Locked}またはqps-plocを含む場合は元の値をそのまま返却
   └─ 4b. ロック対象文字列をUnicode私用領域文字に置換
   └─ 4c. SHA1ハッシュベースの決定論的乱数生成器を初期化
   └─ 4d. 各文字をマッピングテーブルに基づいて変換
   └─ 4e. プレースホルダーを元の文字列に復元
   └─ 4f. 文字列長の40%分のパディング（" !!!"繰り返し）を追加
5. 変換済みXmlDocumentオブジェクトを返却
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[文字マッピングテーブル初期化]
    B --> C[XMLファイル読み込み]
    C --> D{拡張子判定}
    D -->|.resw| E[/root/dataノード反復]
    D -->|.xml| F[//*[@_locID]ノード反復]
    E --> G[GetPseudoLocalization呼び出し]
    F --> H[テキストノード変換]
    H --> I[_locComment_text除去]
    I --> J[_locID属性除去]
    G --> K[変換済みXmlDocument返却]
    J --> K
    K --> L[バッチ終了]
```

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

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

本バッチではデータベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | ファイル未検出 | Pathで指定されたファイルが存在しない | パスを確認 |
| N/A | XMLパースエラー | 入力ファイルが不正なXML | 入力ファイルの構文を確認 |
| N/A | 未対応拡張子 | .resw/.xml以外のファイル | 対応するファイル形式を使用 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（リトライ機構なし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

入力リソースファイルの内容と形式を確認し、再実行する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A |
| コミットタイミング | N/A（メモリ上のXmlDocumentを返却） |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1ファイルあたり数十〜数百のリソースエントリ |
| 目標処理時間 | 数秒以内 |
| メモリ使用量上限 | 特に制約なし |

## 排他制御

ファイル出力は呼び出し元が行うため、本バッチ自体の排他制御は不要。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 標準出力 | N/A | 明示的なログ出力なし |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ビルド失敗 | N/A | ビルドシステム |

## 備考

- 文字マッピングはLocStudioのPseudoReplacementDefs.xmlに準拠している。
- SHA1ハッシュを乱数シードに使用することで、同一キーに対して常に同じ擬似ローカライズ結果が得られる（決定論的）。将来的にPowerShellがUseRandomizedStringHashAlgorithmを有効にしても影響を受けない設計。
- `{Locked}`または`{Locked=qps-ploc}`が指定された文字列は変換されずそのまま返却される。
- 40%パディングは、文字列が長くなった場合のUIレイアウト問題を検出するためのもの。
- Unicode私用領域（U+E000〜）をプレースホルダーとして使用し、ロック対象文字列を保護する。
- ソースファイルパス: `tools/ConvertTo-PseudoLocalization.ps1`
