# HD2 Chat Translator — 受信翻訳 v19

Steam版 HELLDIVERS 2 の右下チャット欄をWindows内蔵OCRで読み取り、英語・中国語などのプレイヤー発言をOpenAI APIで日本語に翻訳して表示します。

ゲームへのDLL注入、HOOK、メモリ読取り、ゲームファイル変更、キー自動入力は行いません。画面の指定範囲を外部から読み取るだけです。

初めて使う場合は、先に `FIRST_SETUP_JA.txt` を開いてください。ZIPの展開、APIキー、OCR言語、モニター設定を順番に案内しています。

## v19の変更点

- 待機中アイコンを左ドラッグで移動し、マウスを離した位置を自動保存
- 元のイラストに描かれた涙の滴を使い、8フレームの落下・フェードアニメーションで表示
- 待機中アイコンはクリック可能になったため、その矩形内ではゲームのクリック操作を受けません。ドラッグできない場合は `Ctrl + Shift + Alt + 矢印` を使います。

## v18の変更点

- Windowsに実際に入っているOCR言語へ、地域コードの違いを吸収して自動照合
- 起動ログへ実際に使うOCR言語タグと照合元を表示し、未解決設定をまとめて警告
- チャット入力欄の除外幅を調整し、最下段の短いチャットを取りこぼしにくく改善

## v17の変更点

- 初回設定ガイドへ、OpenAI Platformの専用プロジェクト作成、API課金、利用上限、APIキー作成手順を追加
- APIのShare設定を追加し、OFFのまま使う場合と専用プロジェクトだけONにする場合を説明
- Shareの無料トークン特典は対象者限定であること、プレイヤー名・本文・訳文等が共有対象になり得ることを明記
- `store: false`とShare設定は別の仕組みであることを明記

## v16の修正点

- 翻訳オーバーレイをOCRが再読して、訳文と発言者名が連鎖的に増えるフィードバックループを遮断
- 自動追従時は翻訳パネル全体をOCR監視範囲の左外へ配置
- 履歴最大6件の走査をやめ、入力欄に最も近い最新1発言だけを採用
- `trackbuilder2015`／`trackbuilder201 5`のようなOCR揺れと、十分に長い先頭・末尾欠けを同一話者へ統一
- 重複判定は引き続き`発言者名＋本文`。別の発言者による同じ本文は残す

## 現在の対応範囲

- 初期値は2560×1440用。設定画面から別モニター・別解像度向けの座標を自動計算可能
- チャット入力欄に最も近い最新1件の `名前: 本文` だけを比較し、新しい発言だけを抽出
- 折り返された本文は、次のプレイヤー名が始まるまで最大3行を同じ発言として結合
- 日本語のゲーム内システム通知は原則として除外
- 英語・簡体字中国語・韓国語・ロシア語・中南米スペイン語・日本語のWindows OCRを使用
- 通常時は白縁の泣き顔アイコンを画面右上端へ表示し、ゆっくり上下させる
- 短時間の連投は最大3件まで、発言順を保った小さな通知として展開
- 発言者ごとにヒロイン素材からランダムなアイコンをセッション中固定で割り当て
- 発言者アイコンの縁と通知左端を、画面左下のプレイヤー名と同じ部隊色に合わせる
- OCR監視範囲へ重ならない元チャット左側へ自動配置
- ゲーム側のチャットが消えると約3秒以内に翻訳表示も隠す
- 元チャットから発言者色を読み取り、名前を小さく、訳文を大きく表示
- 新着は `NEW`、確認済みは `✓` と薄い文字で表示
- `発言者名＋本文`を既読キーとして保持し、通知などで画面が変化しても同じ発言を再翻訳しない
- 別の発言者による同じ本文は別発言として翻訳
- 翻訳パネルと待機アイコンをWindowsの画面キャプチャ対象から除外し、自分の訳文を再OCRするループを防止
- Windows側の除外が使えない場合も、自前UIと重なったOCR行を座標で破棄
- 複数OCR言語の候補を一致数と文字種で比較し、発言者名と本文を同じブロックから採用
- 直近の会話と `glossary.txt` を参照して、ネットスラング・略語・HD2用語を文脈翻訳
- API通信はバックグラウンドで行い、応答待ちでも画面監視とUI操作を継続
- 一時的な通信エラーは1秒、2秒、4秒間隔で自動再試行
- API出力をJSON Schemaで固定し、壊れた翻訳データによる停止を抑制
- チャット監視範囲に変化がない間は重いOCR処理を省略
- Windows OCRが応答しない場合はタイムアウトし、問題のあるOCR言語を30秒休止して監視を継続
- `startup-error.log` に通常動作・警告・30秒ごとの生存記録を保存
- 待機アイコンのバッジと動きで、待機・翻訳中・エラー・一時停止を区別
- 通知領域アイコンの右クリックから、一時停止・設定・用語集・終了を操作
- 長文は通知パネルの高さを自動的に広げて見切れを軽減
- 複数モニター環境では、検出したチャットがあるモニター内へ通知を配置
- APIへ送るのはOCR後の文字列だけ。スクリーンショットは送信しない
- OpenAI Responses APIで `store: false` を指定

日本語から英語へ変換して送信する機能は次段階です。v19でも受信翻訳だけを扱います。

## 必要なもの

- Windows 11
- HELLDIVERS 2（初期設定は2560×1440。ほかの解像度は設定画面で調整）
- OpenAI PlatformのAPIキー
- インターネット接続

追加のPython、Node.js、OCRソフトなどは不要です。

## OpenAI APIの初回準備

APIの準備から行う場合は、`FIRST_SETUP_JA.txt` の「3. OpenAI APIを準備する」以降を順番に進めてください。次の内容をまとめて説明しています。

- HD2ChatTranslator専用プロジェクトの作成
- ChatGPTとは別のAPI課金と前払いクレジット
- Auto recharge（自動追加購入）とHard spend limit
- API入力・出力のShare設定
- 専用プロジェクト用APIキーの作成と暗号化保存

Shareは任意で、初期状態はOFFです。翻訳機能を使うためにONにする必要はありません。無料トークン特典の対象者がShareを使う場合も、個人情報や機密情報が混ざり得るチャットではOFFのまま使うほうが安全です。詳細と設定ページへのURLは初回設定ガイドに記載しています。

## 起動方法

1. ダウンロードしたZIPを右クリックし、`すべて展開` を実行します。ZIPの中から直接起動しないでください。
2. 展開先の `HD2ChatTranslator` フォルダーにある `Start-HD2ChatTranslator.cmd` をダブルクリックします。
3. `OPENAI_API_KEY` がWindowsに設定されていない場合、黒い画面でAPIキーを尋ねられます。
4. APIキーを貼り付けてEnterを押します。入力内容は画面に表示されず、ファイルにも保存されません。
5. HELLDIVERS 2を起動します。
6. 他プレイヤーの `名前: 本文` 形式のチャットがOCRされると、元チャットの左側に日本語訳が出ます。

APIキーを環境変数へ設定済みなら入力確認は省略されます。公式OpenAIドキュメントと同じ変数名 `OPENAI_API_KEY` を使用します。

### APIキーを暗号化して保存する

毎回入力したくない場合は、最初に `Save-APIKey.cmd` をダブルクリックし、APIキーを貼り付けてください。`openai-api-key.dpapi` という暗号化ファイルが作成され、次回から自動的に読み込まれます。

これはWindowsのDPAPIで現在のWindowsユーザーに紐づけて暗号化されます。別のPCや別のWindowsユーザーへファイルだけコピーしても復号できません。保存を解除する場合は、翻訳ツールを終了してから `openai-api-key.dpapi` を削除してください。

読込みの優先順位は次のとおりです。

1. 環境変数 `OPENAI_API_KEY`
2. 暗号化ファイル `openai-api-key.dpapi`
3. 起動時の一時入力

## フルスクリーンについて

まずは現在のフルスクリーン設定のまま試してください。

次のどちらかが起きる場合は、ゲームの「ディスプレイモード」を「ボーダーレスウィンドウ」に変更してください。

- 翻訳処理は動いているのにオーバーレイだけ見えない
- OCR画像が黒くなり、チャットを認識しない

排他的フルスクリーンは通常のWindowsウィンドウをゲームの上へ合成できません。ボーダーレスは見た目が全画面のままで、オーバーレイを安全に表示できます。

## ホットキー

- `Ctrl + Shift + F10`：監視の一時停止／再開
- `Ctrl + Shift + F12`：終了
- `Ctrl + Shift + F8`：チャット位置への自動追従をON／OFF
- `Ctrl + Shift + 矢印`：翻訳表示を25ピクセルずつ移動（位置は自動保存）
- `Ctrl + Shift + PageUp`：背景を濃くする
- `Ctrl + Shift + PageDown`：背景を透明にする
- `Ctrl + Shift + Alt + 矢印`：待機アイコンを10ピクセルずつ移動
- 待機中アイコンの左ドラッグ：位置を移動して自動保存

## 通知領域メニューと設定画面

タスクバー右端の通知領域にあるHD2 Chat Translatorアイコンを右クリックすると、次の操作ができます。アイコンのダブルクリックでも一時停止／再開できます。

- 一時停止／再開
- 設定を開く
- 用語集を開く
- 終了

`Settings-HD2ChatTranslator.cmd` を直接ダブルクリックしても設定画面を開けます。使用モニター、ゲーム画面の座標と解像度、表示位置・大きさ・透明度、待機アイコン、既読発言の保持時間、API再試行、OCR範囲と負荷設定を編集できます。保存内容は翻訳ツールの再起動後に反映されます。

「検出したモニター」を選び、「この画面設定からOCR範囲と待機位置を自動計算」を押すと、現在の2560×1440設定を基準に座標を比例計算します。ゲームがモニター全面ではない場合は、ゲーム画面の左上座標と解像度を手入力してから計算してください。計算後は必ず「保存」を押します。

待機アイコン右下の表示は次の意味です。

- バッジなし：監視中
- 水色の `…`：翻訳中または再試行待ち
- 赤い `!`：OCR／通信エラー。通常は8秒後に監視へ復帰
- 灰色の `Z`：一時停止中

## OCRが動かない場合

Windowsの「設定」→「時刻と言語」→「言語と地域」で、次の言語機能を確認してください。

1. 日本語
2. 英語（米国）
3. 中国語（簡体字、中国）
4. 韓国語
5. ロシア語
6. スペイン語（メキシコ）

対象言語の読取り精度を上げたい場合は、Windowsの「言語のオプション」から言語機能を追加してください。スペイン語は中南米表現を優先するため `es-MX`（スペイン語・メキシコ）を使用します。アプリはインストール済みのOCR言語だけを自動使用し、1つもなければWindowsのユーザープロファイル言語へフォールバックします。

起動時のPowerShell画面に、利用できる言語の `OCR: 実際の言語タグ` が表示されることを確認してください。複数のOCR言語が入っている環境では複数表示されます。設定タグは実際に利用可能なOCRタグへ大文字小文字を無視した完全一致、または同じ言語族（中国語は簡体字／繁体字の文字体系を維持）で自動照合され、解決できない設定はまとめて警告されます。

処理負荷を抑えるため、インストール済みOCR言語を1回につき3言語ずつ順番に処理します。また、監視範囲の見た目が変化していない間はOCR自体を省略し、`OcrMaxIdleMs` ごとに取りこぼし確認を行います。`OcrEnginesPerScan` を増やすと検出は速くなりますが、CPU負荷も上がります。

## 読取り位置を確認する

`config.json` の `SaveDebugCapture` を `true` にして起動すると、監視範囲が `last-capture.png` として上書き保存されます。

2560×1440で、ミッション中と艦内の両方のチャット位置を含むよう縦長に設定しています。

```json
"Capture": {
  "X": 2000,
  "Y": 470,
  "Width": 550,
  "Height": 850
}
```

チャット文字が `last-capture.png` に入っていなければ、この4値を調整します。

## 翻訳位置を動かす

`config.json` の `Overlay` を編集します。

```json
"Overlay": {
  "X": 1640,
  "Y": 760,
  "Width": 520,
  "Height": 78,
  "Opacity": 0.68
}
```

`AutoFollowChat` が `true` の場合、`X` と `Y` は予備位置として扱われ、翻訳通知はOCR監視範囲へ重ならない元チャット左側へ自動配置されます。手動移動ホットキーを押すと自動追従がOFFになり、その位置が保存されます。オーバーレイはクリックを透過するため、ゲーム操作を邪魔しません。手動配置で監視範囲に重ねても自前UI由来のOCR行は破棄されるため再翻訳ループには入りませんが、背後のゲームチャットが隠れるので監視範囲の外へ置いてください。

翻訳がない間は翻訳パネルを非表示にし、`assets/idle.png` を小さな待機アイコンとして表示します。翻訳を表示している間、待機アイコンは隠れます。待機中アイコンは左ドラッグで移動でき、マウスを離すと位置が `config.json` に自動保存されます。アイコンの矩形内はゲームのクリック操作を受けないため、キーボードで移動する場合は `Ctrl + Shift + Alt + 矢印` を使ってください。待機位置・サイズ・透明度・アニメーション速度は `config.json` の `IdleIcon` で変更できます。ツールの稼働状態はWindowsの通知領域からも確認できます。

発言者画像は `assets/heroines` 内のPNGからランダムに選びます。同じプレイヤー名には起動中ずっと同じ画像が割り当てられます。OCRが名前を1文字程度読み違えた場合や、境界で名前の先頭／末尾だけが欠けた場合も、十分に長い一致があれば既知のフルネームへ統一します。次回起動時には再抽選されます。画像を増減したい場合は、このフォルダー内のPNGを編集してください。

`glossary.txt` はメモ帳で編集できます。v17では、一般的なネトゲ略語・定型文・協力プレイ用語に加え、勢力、敵、任務、装備略称、資源、現行の HELLDIVERS 2 固有語をカテゴリ別に収録しています。よく使うコミュニティ用語や好みの訳は `原文 = 日本語` の形式で追加してください。自動的な再学習は誤訳まで固定してしまうため行わず、直近会話と明示的な用語集で翻訳を安定させています。

## 終了方法

`Ctrl + Shift + F12` を押します。反応しない場合は、起動時のPowerShell画面を閉じてください。

## 画面・新着判定・安定化設定

通常は設定画面から変更できます。直接編集する場合の主な値は次のとおりです。

- `SeenMessageResetSeconds`：発言者名＋本文の既読記憶を、画面から見えなくなったあと保持する時間。既定90秒
- `ChatInputGuardPixels`：チャット入力欄としてOCR対象から除外する画面下端の幅。既定40px
- `OcrOperationTimeoutMs`：Windows OCR 1処理の待機上限。既定6500ms
- `ApiTimeoutSeconds`：API通信のタイムアウト。既定20秒
- `ApiMaxRetries`：通信失敗後の再試行回数。既定3回
- `OcrChangeThreshold`：OCRを再実行する画面変化量。小さいほど敏感
- `OcrMaxIdleMs`：画面変化がなくてもOCRする最大間隔。既定4500ms

## 共有・再配布時の注意

配布用ZIPへ次のファイルを入れないでください。

- `openai-api-key.dpapi`：現在のWindowsユーザー用に暗号化されたAPIキー
- `startup-error.log`：パスは原則匿名化されるが、時刻や動作状況を含む
- `last-capture.png`：ゲーム画面、プレイヤー名、チャット内容を含む可能性がある

本配布版には上記ファイルを含めていません。各利用者が自分のPCで作成したZIPを再共有する場合も、改めて除外してください。

`assets`内の画像素材については、このツールのコードとは別に、入手元の利用規約・再配布条件が適用されます。本パッケージには素材の再配布許諾を証明する文書は含まれていません。友人への共有や一般公開の前に、各素材の配布元で再配布可否を確認してください。

## 注意

- OCR誤認識は起こり得ます。
- UI倍率や解像度を変えた場合は、読取り範囲の再調整が必要です。
- GameGuardによる公式な動作保証はありません。ただし本ツールはゲームプロセスへ接続せず、一般的な画面キャプチャと外部表示だけを使用します。
- OpenAI APIの利用料金はChatGPTの契約とは別に発生します。
- APIのShare設定は任意です。ONにした場合、プレイヤー名、チャット、訳文、直近文脈、用語集が共有対象になり得ます。
- `store: false`を指定していても、組織／プロジェクト側でShareをONにした通信は共有対象になります。
