# コード生成プロンプト：ローカル翻訳エンジンと試用 GUI（日本語・英語・中国語（簡体字）・インドネシア語）

## ビジョン
日本語・英語・中国語（簡体字）・インドネシア語の 4 言語を、手元の PC だけで高い品質で相互に翻訳するエンジンを作る。

使う人が「この翻訳なら安心して使える」と感じることを目指す。速くて正確で、訳文の数値・URL・改行が崩れない。さらに、エンジンが自信の無い箇所を正直に示す。大学などの教育現場で、教職員と留学生が授業の連絡や会話、文書をやり取りする場面を主な用途とする。

このコードは 2 通りに使う。1 つは、音声認識アプリなど他の Python プログラムから import して使う翻訳モジュールである。もう 1 つは、直接実行すると起動する試用 GUI である。中心は翻訳モジュールであり、GUI はモデルの選択と翻訳の品質を確かめるための手段である。GUI で得られる訳文と、モジュールとして呼び出したときの訳文は一致させる。

## 用語の定義
このプロンプトでは、次の用語を以下の意味だけで使う。

- 対応言語：日本語（ja）・英語（en）・中国語（簡体字、zh）・インドネシア語（id）の 4 言語
- 翻訳方向：翻訳元と翻訳先の組み合わせ。対応言語どうしで全 12 方向ある
- モデル：Hugging Face で公開されている、ローカルで動く翻訳用の言語モデル
- モデルカタログ：選べるモデルとその仕様、品質の根拠（出典と数値）をまとめた一覧
- 推奨：使用デバイス・GPU のメモリ容量・翻訳方向から、どのモデルが適するかを根拠付きで示すこと。モデルを選ぶのは利用者である
- 文：翻訳の単位。入力を改行・句点などで分割したもの
- 背景情報：ある文を訳すときに参考として渡す、直前の文や直前の発話
- 訳文の確認：訳文の問題（数値の欠落、URL の欠落、英字の語・略語・型番の欠落、文体の不一致、言語の取り違え、繰り返し、長さの異常など）を規則で検出すること
- 問題の重み：検出した問題ごとに、深刻さに応じて与える整数の点数
- 信頼度スコア：言語判定の確からしさを 0〜1 で表す経験的な値（確率として較正していない）
- セッション：音声認識のように短い発話が続けて届く場面で、背景情報と直前の言語を保持して翻訳する仕組み
- 目標値：完成の基準で数値によって示す、達成を目指す水準。コード冒頭の設定値で変更できるようにする

## ゴール
次の 4 つの柱を高い水準で実現する。

1. **完全にローカルで動く高品質な翻訳**
   翻訳はすべてこの PC 上で実行する。ネットワークを使うのは、モデルを初めてダウンロードするときだけとする。4 言語の全 12 方向に対応する。
2. **根拠に基づくモデル選択（選ぶのは利用者）**
   最新の公開モデルを調査し、条件を満たすものだけをモデルカタログに載せる。品質の根拠は出典（論文の識別子など）と数値で示す。推奨は理由とともに示し、コードがモデルを自動で切り替えることはしない。
3. **正直で頑健な翻訳結果**
   言語判定の信頼度、翻訳先の切り替え、数値の欠落などの問題を隠さずに結果に含める。問題が見つかった文は候補を生成し直し、問題の重みの合計が最小の訳を選ぶ。改行・箇条書き・URL・メールアドレス・数値を保つ。
4. **他のプログラムから安全に使えるモジュール**
   import しただけでは GUI を起動せず、モデルも読み込まない。複数のスレッドから安全に呼べるようにし、不要になった翻訳は生成の途中で止められるようにする。音声認識との連携に必要な API をそろえる。

4 つの柱と試用 GUI に必要な機能は省略しない。4 つの柱に関係しない機能（オンライン翻訳 API の利用、音声認識そのもの、ファイル形式の変換、利用者の履歴の保存・送信など）は加えない。

## モデルの調査と選定
- コードを作る時点で公開されている翻訳用モデルを調べ、次の条件で選ぶ。
  - 対応言語のうち複数の方向に対応し、少なくとも日本語が翻訳元か翻訳先に含まれる
  - 商用利用できるライセンス（Apache License 2.0、MIT License など）で公開されている
  - GPU のメモリ 8GB 程度の PC か、CPU だけの PC で実用的に動く
  - 開発元の論文や公式の評価に、品質の根拠となる数値がある
- 候補は、全 12 方向に対応する tencent/Hy-MT2（1.8B・7B）と、日英・英日に特化した cyberagent/CAT-Translate（1.4b・3.3b・7b）である。これより新しいモデルが出ていないかを改めて調べる。採用しなかった主なモデルについても、採用しなかった理由を数値（重みの大きさ、対応方向、ベンチマークの値）で冒頭のコメントに記す。
- 各モデルについて、次の情報をモデルカタログに記録する：リポジトリ名、プロンプト形式の系統、公称のパラメータ数、bfloat16 の重みの大きさの概算、対応する翻訳方向、用語指定・文体指定・背景情報指定のプロンプト形式が公開されているか、trust_remote_code の要否、公式が推奨する生成パラメータ、品質の根拠。
- プロンプトは各モデルの公式の形式に厳密に従う。公式の形式が中国語のプロンプトと英語のプロンプトを使い分けるよう指定している場合は、それに従う。
- 論文の比較に含まれない組み合わせ（新旧モデルの直接比較など）は「比較に含まれない」と明記し、推測で優劣を書かない。

## 機能要件

### モデルの推奨と読み込み
- 推奨の関数は、使用デバイス（GPU／CPU）・GPU のメモリ容量（CPU では PC のメモリ容量）・翻訳方向（翻訳元が未定の場合を含む）を受け取り、モデルごとに「使えるか」「推奨するか」「その理由」を返す。推奨するモデルは高々 1 つとする。
- 推奨の規則は根拠と一緒にコメントに記す。例えば、日英・英日では日英・英日の評価で前版を上回った特化モデルを候補にし、それ以外の方向では全方向に対応するモデルを候補にする。そのうえで、GPU ではメモリに収まる中で最も大きいモデル、CPU では最も小さいモデルを推奨する。
- モデルは初回の読み込み時にダウンロードする。説明用の画像・評価データ・学習用スクリプトなど不要なファイルはダウンロードしない。ダウンロードの進捗（GB 単位と割合）を、コールバックで呼び出し側に知らせる。
- bfloat16 で読み込む。量子化は実施しない
- 読み込みの後に短い文を 1 回生成して、最初の翻訳の待ち時間を減らす。モデルをメモリから解放する機能も設ける。

### 言語判定
- モデルを使わずに判定し、モデルの読み込み前でも使えるようにする。
- 漢字だけの文は、日本語専用の字と簡体字専用の字で日本語と中国語を区別する。これらの字の集合は JIS X 0208 と GB 2312 の差から求め、手作業の一覧に頼らない。あわせて、日本語・中国語に特有の語の手がかりも使う。
- 英語とインドネシア語は、機能語・接辞の規則と、既存の言語判定ライブラリの出力を組み合わせて区別する。
- 根拠が少ない場合（短い文、1 語だけの英単語、混ざった外来語など）は信頼度スコアの上限を下げる。結果には、判定した言語、信頼度スコア、4 言語それぞれのスコア、言語が混ざっているか、判定に使った文字の数、判定の根拠と注意点を含める。
- 対応言語以外の文字が主体の場合と、文字を含まない場合は、言語を判定できないことを返す。

### 翻訳
- 入力を行に分け、行頭の記号（箇条書きの記号・番号・字下げ）を取り出したうえで文に分割する。分割では、かぎかっこの内側・URL・小数点・時刻・略語・頭文字の後では区切らない。句点の無い長い文は、読点・カンマ・空白の位置で区切る。
- 各文には直前の文を背景情報として渡し、訳した後に行頭の記号・改行・空行を元どおりに戻して結合する。
- 翻訳元と翻訳先が同じ言語になった場合は、決めておいた別の言語に翻訳先を切り替え、切り替えたことを結果に含める。
- 日本語の文体（です・ます体／だ・である体／自動）・背景情報を、モデルが公開しているプロンプト形式で指定する。複数の指定を同時に使う場合は、公式の複合指定の形式を使う。公開されていない指定は使わない。
- 複数の文をまとめて生成する。プロンプトを長さ順に並べて埋め草を減らし、生成トークン数の上限は原文のトークン数から文ごとに決める。

### 訳文の確認と生成し直し
- 次の問題を検出し、深刻さに応じた重みを与える：空の訳文、繰り返し、訳文の言語の取り違え、URL・メールアドレスの欠落、長さの異常、数値の欠落、日本語の文体の不一致、英字の語・略語・型番の欠落。
- 数値の確認では、桁区切りと小数点の書き方の違い、単位（万・億・juta など）、月名、漢数字、英語・インドネシア語の数詞、12 時間制への言い換えを同じ値とみなす。
- URL・メールアドレスが訳文で崩れた場合は、似た文字列を元の表記に置き換えて直す。
- 問題の重みの合計が基準値以上の文は、公式推奨のサンプリング設定（公式の推奨が無いモデルでは経験的に決めた設定）で候補を生成し直す。背景情報を誤って訳してしまった可能性に備えて、背景情報を除いた候補も作る。そのうえで、合計が最小の訳を選ぶ。
- 文体を「自動」にして敬体と常体が混ざった場合は、少ない方の文を多い方の文体で訳し直し、問題が増えない場合に限って置き換える。
- 最終的に残った問題は、利用者への注意として結果に含める。

### モジュールとしての API
- 翻訳エンジンのクラスは、インスタンスを作っただけではモデルを読み込まない。最初の翻訳のときか、明示的に読み込むときに 1 回だけ読み込む。
- 公開メソッドは複数のスレッドから呼べるようにし、読み込みと翻訳は 1 つのロックで順に実行する。
- 単一の翻訳と複数の文字列の一括翻訳を用意する。どちらも cancel_event（threading.Event）を受け取り、セットされたら生成を途中で止めて専用の例外を送出する。
- 音声認識との連携用にセッションのクラスを用意する。セッションは直前の発話を背景情報として渡す。短い発話で言語判定が不確かな場合は直前の言語を使う。話題や話者が変わったときのためにリセットのメソッドを設ける。
- 結果のデータ型には、原文、訳文、実際の翻訳元と翻訳先、指定された翻訳先、言語判定の結果、処理時間、文の数、使用デバイス、使用モデル、翻訳先を切り替えたか、注意の一覧を含める。
- 例外は共通の基底クラスから派生させ、不正な入力、対応していない言語・翻訳方向、デバイスを使えない、中止された、を区別する。
- 公開する関数・クラス・データ型には、引数・戻り値・送出する例外を日本語の docstring で記す。

### 試用 GUI
- tkinter で作る。Windows では DPI 対応を有効にし、高解像度の画面で文字がぼやけないようにする。
- 翻訳の画面と操作方法の画面をタブで分ける。翻訳の画面には次のものを置く：原文と訳文を左右に並べた欄、翻訳元（自動判定を含む）と翻訳先の選択、翻訳元と翻訳先の入れ替え、日本語の文体の選択（翻訳先が日本語でないときは無効にする）、訳文のコピー。
- モデルの選択とデバイスの選択を設ける。推奨の結果と理由を表示し、推奨のモデルを 1 回の操作で選べるようにする。
- 読み込みの進捗を進捗バーで示す。割合を算出できない段階では、割合を示さない表示に切り替える。
- 入力が止まってから一定時間後に自動で翻訳する機能を、切り替えられるように設ける。新しい翻訳を始めたら、前の翻訳を cancel_event で止める。古い要求の結果が新しい結果を上書きしないようにする。
- 言語判定の結果と信頼度スコアを表示する。信頼度が低い場合は目立つ色で示し、2 番目の候補の言語として訳し直せるようにする。
- 注意（数値の欠落など）、使用したデバイスとモデル、処理時間を表示する。エラーは状態表示に例外の種類と内容を示し、読み込みの失敗はダイアログでも知らせる。
- 読み込みと翻訳は別のスレッドで実行し、キューを通じて GUI のスレッドに結果を渡す。GUI は固まらないようにする。

## 完成の基準
次のすべてを満たしたとき、完成とする。数値で示す項目は目標値であり、実測した結果をコード冒頭のコメントに記す。

- import しただけでは、GUI の起動もモデルの読み込みも PyTorch の読み込みも起こらない。直接実行すると試用 GUI が起動する。
- モデルカタログのすべてのモデルが、対応するすべての翻訳方向で、例外を生じずに訳文を返す。
- 4 言語の典型的な文（短い挨拶、漢字だけの短い文、英語とインドネシア語の短い文、言語が混ざった文を含む）で言語判定の正解率を測り、目標値以上になる。信頼度スコアが基準値を下回る判定は「信頼度が低い」と示される。
- 改行・空行・箇条書きの記号・番号、URL・メールアドレスが訳文で保たれる。原文の数値が訳文に見当たらない場合は注意が示される。
- 翻訳先が日本語のとき、指定した文体で訳文がそろう。
- cancel_event をセットしてから目標時間以内に生成が止まる。複数のスレッドから同時に呼び出しても例外や結果の取り違えが起こらない。
- GPU（bfloat16）と CPU（bfloat16）のそれぞれで、短い文 1 文の翻訳時間を測り、目標値以内になる。
- GUI は読み込み中も翻訳中も操作に応答し、高解像度の画面でも文字がぼやけない。

## 制約
- プログラムは Python の単一ファイルで完結させる。
- 対象環境は Windows 11、Python とする。
- 主なライブラリは PyTorch、transformers、accelerate、英語とインドネシア語の判定用の言語判定ライブラリとし、GUI には Python 標準の tkinter を使う。その他のライブラリを使ってよいが、必要最小限にする。
- 必要なライブラリと版の指定、その版にする理由（非推奨の API の削除予定、モデルの要件など）、CPU 版と GPU 版のインストール手順、GPU の世代とドライバの要件を、コード冒頭のコメントに記す。
- モデルカタログ、プロンプトの形式、生成パラメータ、信頼度の基準値、文の分割の文字数、一括生成の文の数、生成し直しの設定、自動翻訳の待ち時間、完成の基準の目標値に関わる数値は、コード冒頭の 1 か所にまとめ、後から調整できるようにする。モデルを追加・差し替えるときは、モデルカタログの節だけを変更すれば済むようにする。
- コメントと docstring は日本語で書く。数値・出典・根拠を明記し、根拠の無い主張や誇張を書かない。経験的に決めた値は、経験的に決めたことを明記する。

## 思考の方針
- 実装の方法は自分で決める。何かを決めるときは、ゴールと完成の基準に照らして、段階的に深く考える。
- 次の立場の人が議論する場面を思考の中で想定し、4 つの柱の範囲で、使う人の安心感と翻訳の品質を極限まで高める方法を考える。
  - 日本語・英語・中国語・インドネシア語の実務翻訳者・通訳者
  - 言語判定と機械翻訳の評価に詳しい計算言語学の研究者
  - 言語モデルの推論の高速化と量子化を専門とする機械学習エンジニア
  - この翻訳モジュールを音声認識アプリに組み込む開発者
  - 翻訳ツールを初めて使う教職員と留学生
- モデルの品質は、開発元の主張と独立した評価を区別し、評価の条件（ベンチマークの種類、評価尺度）を確かめてから判断する。評価尺度によって順位が変わる場合は、両方を記す。
- 失敗の仕方を設計する。判定や翻訳に自信が無い場合は、黙ってそれらしい結果を返すのではなく、その旨を結果に含める。
- 完成の基準を満たした後も、改善の余地を探して改善を繰り返す。全モデル・全翻訳方向の翻訳、典型的な入力と境界的な入力（空文字列、記号だけの文、非常に長い文、URL だけの文、言語が混ざった文）での確認、中止とスレッドの確認を行っても改善の余地が見つからなくなったら終了する。

## 出力
- 出力する前に、コード全体を見直し、エラー（未定義の名前、型の不一致、スレッド間の競合、例外の取りこぼしなど）、未実装の箇所、使われていない処理がないことを確認する。
- コードが長くなっても、全体を省略せずに出力する。
- 出力するのはコードだけである。コード冒頭の説明とインストール手順のコメントはコードの一部として含め、それ以外の説明文は出力しない。
