# バッチ設計書 5-check-translations.sh

## 概要

本ドキュメントは、翻訳ファイル（POファイル）の整合性をチェックするCI/CDスクリプト `check-translations.sh` の設計仕様を記載する。

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

本バッチは、Ghosttyの国際化（i18n）対応における翻訳ファイルの整合性を検証するスクリプトである。

**業務上の目的・背景**：Ghosttyは多言語対応を行っており、翻訳可能な文字列はPOT（Portable Object Template）ファイルで管理され、各言語の翻訳はPOファイルに格納されている。ソースコードの変更により翻訳対象文字列が追加・削除・変更された場合、POTファイルと各言語のPOファイルの間に不整合が生じる可能性がある。本スクリプトは、CIパイプラインで翻訳ファイルの整合性を自動検証し、翻訳漏れや陳腐化した翻訳を検出する。

**バッチの実行タイミング**：CI/CD パイプライン実行時（push/PR時）

**主要な処理内容**：
1. 現在のPOTファイルをバックアップ
2. zig build update-translations でPOTファイルを再生成
3. msgcmp で旧POTと新POTを比較し差分がないことを確認
4. msgcmp で各言語のPOファイルとPOTの整合性を検証

**前後の処理との関連**：翻訳対象となるソースコードの変更後に実行される。POTファイルの更新が必要な場合は、開発者が`zig build update-translations`を手動実行してコミットする。

**影響範囲**：翻訳ファイルの検証のみ、本スクリプト自体はファイルを永続的に変更しない

## バッチ種別

データ整合性チェック / 国際化検証

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（CIトリガー） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | push/PR |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| zig | zigコマンドが利用可能であること |
| msgcmp | gettextのmsgcmpコマンドが利用可能であること |
| mktemp | 一時ファイル作成コマンドが利用可能であること |
| po/ | poディレクトリとPOT/POファイルが存在すること |

### 実行可否判定

- 常に実行可能（前提条件を満たす場合）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 入力パラメータなし |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| po/com.mitchellh.ghostty.pot | POT | 翻訳テンプレートファイル |
| po/*.po | PO | 各言語の翻訳ファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | 実行コマンドのログ |
| 標準エラー | テキスト | msgcmpのエラー出力（不整合がある場合） |

### 出力ファイル仕様

本バッチは永続的なファイル出力を行わない（一時ファイルは処理後に削除）。

## 処理フロー

### 処理シーケンス

```
1. シェルオプション設定
   └─ set -euxo pipefail で厳格モード・デバッグ出力有効化
2. POTファイルのバックアップ
   └─ mktemp で一時ファイル作成
   └─ cp で現在のPOTファイルをコピー
3. POTファイルの再生成
   └─ zig build update-translations で最新のPOTを生成
4. 旧POTと新POTの比較
   └─ msgcmp --use-untranslated で差分チェック
5. 各言語POファイルの検証
   └─ forループで po/*.po を走査
   └─ msgcmp --use-untranslated で各POとPOTの整合性を確認
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[POTファイルをバックアップ]
    B --> C[zig build update-translations]
    C --> D[msgcmp: 旧POT vs 新POT]
    D --> E{差分あり?}
    E -->|あり| F[エラー終了]
    E -->|なし| G[各言語POファイル走査]
    G --> H{次のPOあり?}
    H -->|あり| I[msgcmp: PO vs POT]
    I --> J{整合性OK?}
    J -->|OK| H
    J -->|NG| F
    H -->|なし| K[正常終了]
```

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

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

本バッチはデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 非0 | POT差分検出 | ソースコード変更後POT未更新 | zig build update-translations を実行しコミット |
| 非0 | PO不整合 | POファイルにPOTの文字列が不足 | POファイルを更新 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

1. エラーメッセージを確認し、不整合の原因を特定
2. `zig build update-translations` を実行してPOTを更新
3. 必要に応じてPOファイルの翻訳を更新
4. 変更をコミットしてプッシュ

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | - |
| ロールバック条件 | - |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数十の言語ファイル |
| 目標処理時間 | 60秒以内 |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

特になし。CIでは単一ジョブとして実行される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | なし | - |
| 進捗ログ | 各コマンド実行時 | set -x により全コマンドが出力 |
| 終了ログ | なし | - |
| エラーログ | 不整合検出時 | msgcmpのエラー詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | != 0 | CI失敗通知 |

## 備考

- `set -e`: コマンド失敗時に即座に終了
- `set -u`: 未定義変数の使用でエラー
- `set -x`: 実行コマンドを標準エラーに出力
- `set -o pipefail`: パイプラインのいずれかのコマンドが失敗した場合にエラー
- `--use-untranslated`: 未翻訳のエントリを考慮して比較（厳密なチェック）
- POTファイルは `com.mitchellh.ghostty.pot` という命名規則に従う
