Screenshot Translator (Gemma-4-26B-A4B-It)

このリポジトリには3つの使い方があります。

1. Web UI: クリップボード貼り付け画像を OCR + 英→日翻訳して Markdown 表示
2. Windows 常駐クライアント: 画面上の範囲選択 → スクショ → OCR + 翻訳をオーバーレイ表示
3. Ubuntu Gnome Extension: 画面上の範囲選択 → スクショ → OCR + 翻訳（TTS Once / Monitor で読み上げ対応）

※ Windows 常駐クライアントは Windows + WSL2 と Windows 単体（WSL2 不要） のどちらでも動きます。

※ Ubuntu Gnome Extension は Ubuntu (Gnome Shell) 環境用です。

Windows で使う場合（WSL2 不要）

Windows 単体でクローンから起動まで完結します。NVIDIA (CUDA) / AMD / Intel / CPU のみ、 いずれにも対応しています。MSVC や CUDA Toolkit のインストールは不要です。

git clone <このリポジトリの URL>
cd ScreenshotTranslator2

# 1. llama.cpp のビルド済みバイナリを取得（環境に合わせて選択）
.\app\scripts\fetch_llama_win.ps1                    # AMD / Intel / 汎用 (Vulkan)
.\app\scripts\fetch_llama_win.ps1 -Flavor cuda-13.3  # NVIDIA (Blackwell はこちら)
.\app\scripts\fetch_llama_win.ps1 -Flavor cuda-12.4  # NVIDIA (Ada 以前)

# 2. モデルを models\ に配置（下記「要件」参照）

# 3. 起動（uv sync も自動実行されます）
.\start.ps1

詳細（llama-server.exe の配置、ビルド済みが使えない場合のソースビルド手順、 トラブルシュート、AMD APU 固有の設定）は docs/windows.md を参照してください。

Blackwell 世代 (RTX 50 シリーズ / RTX PRO Blackwell) は CUDA 12.8 以降が必要なため、 cuda-12.4 ビルドでは動作しません。cuda-13.3 を選んでください。

要件

• GPU: NVIDIA (CUDA) / AMD (Vulkan・ROCm) / CPU のいずれか
  • app/scripts/build_llama.sh の GPU_BACKEND で切り替えます（既定: cuda）
  • AMD APU (Ryzen AI Max+ 395 / Strix Halo など) は vulkan を使ってください
• uv (Python パッケージマネージャ) がホストにインストール済み
• 下の2つのモデルファイルをローカル models/ に配置
  • models/gemma-4-26B_q4_0-it.gguf（既定）
  • models/gemma-4-26B-it-mmproj.gguf（26B-A4B 用、既定）
• 配布元: google/gemma-4-26B-A4B-it-qat-q4_0-gguf
  • Google 公式の QAT (quantization-aware training) 版です。約 14.4GB
• 任意: models/mtp-gemma-4-26B-A4B-it.gguf を置くと投機的デコードで高速化します → docs/mtp.md
• 音声読み上げ (TTS):
  • 既定のエンジンは Supertonic 3 (ONNX / CPU 実行) です。バックエンド起動時にモデル (約386MB) が自動でダウンロードされます。
  • 声は F2（日本語女性）、言語は文字種から自動判定されます。日本語の中に英語が混じっていても、1つの声で続けて読み上げます。
  • 音声再生のために、ホスト側に libportaudio2 や aplay (ALSA) が必要です（Ubuntu Desktopなら通常は入っています）。
  • 音声の調整は環境変数で行えます: SUPERTONIC_VOICE (M1〜M5 / F1〜F5、既定 F2)、SUPERTONIC_SPEED (0.7〜2.0、既定 1.05)、SUPERTONIC_STEPS (5〜12、既定 8)、SUPERTONIC_LANGUAGE (既定 en)。
  • SUPERTONIC_LANGUAGE は Supertonic に渡す言語タグです。Supertonic はパッセージ全体を 1 つのタグで条件付けし、語ごとの言語判定は行いません。ja を渡すと、日本語訳に残った英字（製品名・略語など）まで日本語として読まれて発音が崩れるため、既定を en にしています。日本語の読み上げ品質は en でも損なわれません（英字を含まない文でも確認済み）。ja に戻す場合は SUPERTONIC_LANGUAGE=ja、文字種による自動判定（v7.6.0 以前の挙動）に戻す場合は SUPERTONIC_LANGUAGE=auto を指定してください。
  • 従来の Kokoro-82M に戻す場合は TTS_ENGINE=kokoro を指定してください。この場合のみ日本語 G2P (misaki[ja]) が必要で、Windows では既定から外れます（pyopenjtalk に wheel が無く MSVC が必要なため）。有効化する場合は uv sync --extra ja-tts。
  • ライセンス注意: supertonic パッケージ本体は MIT ですが、モデルの重みは BigScience Open RAIL-M ライセンスで配布されています（Kokoro の Apache-2.0 とは条件が異なります）。
    • 本リポジトリはモデルの重みを再配布していません。初回起動時に Supertone/supertonic-3 から利用者の環境へ直接ダウンロードされます。本アプリのコード自体は MIT です。
    • このモデルには用途に基づく制限（Open RAIL-M ライセンス Attachment A）があり、利用者はこれに従う必要があります。違法行為、未成年者の搾取、有害な虚偽情報の生成・拡散、なりすまし（ディープフェイク）、ハラスメント、医療上の助言・診断結果の解釈、法執行や司法判断への利用などが禁止されています。
    • 生成した音声を公開・配布する場合は、機械生成である旨の明示が求められます（同 Attachment A (e)）。
    • 全文は上記モデルページ、またはダウンロード先の LICENSE ファイルを参照してください。

使い方

1. llama.cpp をビルド

   ./app/scripts/build_llama.sh              # NVIDIA (CUDA)
   GPU_BACKEND=vulkan ./app/scripts/build_llama.sh   # AMD / 汎用

   • LLAMA_CURL=OFF でlibcurl未インストール環境でも通るようにしています。
   • 並列ビルドは JOBS 環境変数で上書き可能（既定は nproc があればその値、なければ4）。
   • 必要に応じて LLAMA_REPO / LLAMA_DIR を上書きしてください。
   • Windows ネイティブではビルド不要です（app/scripts/fetch_llama_win.ps1 で公式ビルド済みバイナリを取得）。
2. モデルを models/ 配下へ配置 (パスは環境変数で変更可)。
3. サーバー起動

   ./start.sh          # Linux / WSL2

   .\start.ps1         # Windows ネイティブ

   • デフォルト: Gemma 4 26B-A4B (Google QAT q4_0) + 同梱 mmproj, llama-server 8009, Web UI 8012, ctx=8192, parallel=1。
   • models/mtp-gemma-4-26B-A4B-it.gguf があれば投機的デコードが自動で有効になります（無ければ無効のまま通常動作）。
   • VRAMが少ない場合は起動時に LLAMA_CTX を下げて起動できます（例: LLAMA_CTX=4096 ./start.sh）。
   • 既存の llama-server を使う場合: SKIP_LLAMACPP=1 LLAMA_SERVER_URL=http://127.0.0.1:8009 ./start.sh
   • Gemma 4 既定時は LLAMA_THINK_BUDGET=0 と --reasoning off が自動適用されます。
   • E4B を併用する場合は、26B-A4B 用の models/mmproj-F16.gguf と名前が衝突しないよう、E4B 用 projector を任意の別名にして保存してください。例: models/mmproj-F16_gemma4E4B.gguf
   • E4B を使う場合は LLAMA_MODEL=models/gemma-4-E4B-it-UD-Q4_K_XL.gguf LLAMA_MMPROJ=models/mmproj-F16_gemma4E4B.gguf LLAMA_MODEL_NAME=Gemma-4-E4B-It ./start.sh のように明示指定してください。
   • Qwen3.5 を使う場合は LLAMA_MODEL=models/Qwen3.5-35B-A3B-UD-Q4_K_XL.gguf LLAMA_MMPROJ=models/mmproj-F32.gguf ./start.sh のように明示指定してください。
   • Qwen3.5 では Qwen3.5 用の mmproj を指定してください。Gemma 4 用の mmproj とは共用できません。ファイル名が衝突する場合は任意の別名で保存し、LLAMA_MMPROJ にそのパスを指定してください。

詳細ドキュメント

• docs/mtp.md — MTP（投機的デコード）による高速化。任意機能・GGUF の作り方付き
• docs/windows.md — WSL2 を使わない Windows 単体構成（CUDA / 非CUDA 両対応）/ AMD APU 設定

主な環境変数

• WEB_PORT (既定: 8012)
• LLAMA_PORT (既定: 8009)
• LLAMA_MODEL (既定: models/gemma-4-26B_q4_0-it.gguf)
• LLAMA_MMPROJ (既定: models/gemma-4-26B-it-mmproj.gguf)
• LLAMA_MODEL_NAME (既定: Gemma-4-26B-A4B-It-QAT)
• LLAMA_SPEC_DRAFT_MODEL (MTP ヘッドのパス。既定モデル使用時は models/mtp-gemma-4-26B-A4B-it.gguf が存在すれば自動設定)
• LLAMA_SPEC_TYPE (既定: draft-mtp。--spec-type に渡す値)
• GPU_BACKEND (build_llama.sh 用。cuda / vulkan / hip / cpu。既定: cuda)
• LLAMA_CTX (既定: 8192)
• LLAMA_PARALLEL (既定: 1)
• LLAMA_BIN (既定: ./llama.cpp/build/bin/llama-server)
• LLAMA_CHAT_TEMPLATE_FILE (--chat-template-file に渡すテンプレートパス)
• LLAMA_REASONING (--reasoning に渡す値。Gemma 4 系モデルでは未指定時に off)
• LLAMA_THINK_BUDGET (--reasoning-budget に渡す値。Gemma 4 / Qwen3.5 既定時は自動で 0)
• LLAMA_ARG_CHAT_TEMPLATE_FILE / LLAMA_ARG_THINK_BUDGET も互換入力として受け付け
• SKIP_LLAMACPP=1 で llama-server 起動をスキップ

Gemma 4 既定構成

• 既定構成は Google 公式 QAT 版の gemma-4-26B_q4_0-it.gguf と gemma-4-26B-it-mmproj.gguf です（v7.3.0 で unsloth UD-Q4_K_XL から変更）。
  • サイズが 17.1GB → 14.4GB に減り、メモリ帯域律速の環境では約 1.26 倍高速になります。
  • 従来構成に戻す場合: LLAMA_MODEL=models/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf LLAMA_MMPROJ=models/mmproj-F16.gguf ./start.sh
• projector の型式は gemma4v で、旧来の llama.cpp でもそのまま読めます。llama.cpp の更新が必須なのは MTP を使う場合だけです。
• E4B を同居させる場合は、E4B 用 projector を別名で保存し、LLAMA_MMPROJ で明示指定してください。
• chat template は Gemma 4 のモデル内蔵 template をそのまま使います。
• 単一ユーザー前提で --parallel 1 を既定にしています。
• thinking を抑制するため、Gemma 4 系モデルでは LLAMA_THINK_BUDGET 未指定時は 0、LLAMA_REASONING 未指定時は off を自動適用します。

Qwen3.5 テンプレート運用（互換）

• 追跡対象テンプレートは app/chat_templates/qwen3.5-35b-a3b.chat_template.jinja です。
• 元テンプレートは Qwen 公式 chat_template.jinja（Apache-2.0）で、このリポジトリでは enable_thinking=false を加えています。
• models/ は .gitignore 対象のため、テンプレートは models/ ではなく app/chat_templates/ に置いて管理します。
• Qwen3.5 に切り替えたときだけ、このテンプレートが自動適用されます。
• 実行時に LAMA_ARG_THINK_BUDGET（typo）が与えられた場合も互換で受け付けますが、LLAMA_THINK_BUDGET の利用を推奨します。

LLAMA_CTX について（VRAM調整）

• LLAMA_CTX は llama.cpp の llama-server を起動する際の -c に渡され、主に KV cache のサイズに効くため VRAM 使用量に影響します。
• LLAMA_CTX を変更してVRAM使用量を変えたい場合は、llama-server を起動し直す必要があります（FastAPI側の環境変数だけ変えてもVRAMは変わりません）。
• SKIP_LLAMACPP=1 で既存の llama-server を使う場合、その既存プロセスが -c で起動された値が有効になります。

おまけ：vLLM / DiffusionGemma バックエンド（実験的）

既定では Gemma-4-26B-A4B-It を llama.cpp (GGUF) で動かします（幅広い GPU・CPU で動作）。 ハイエンドな NVIDIA GPU をお持ちの場合は、同じベースモデルの拡散版 nvidia/diffusiongemma-26B-A4B-it-NVFP4 を vLLM 経由で使う、より高速な選択肢があります。 拡散モデルは 256 トークンのブロックを並列生成するため、OCR＋翻訳がおおむね 1 秒未満で完了します。

⚠ 実験的です。 この経路は公開前イメージ vllm/vllm-openai:gemma に依存します。NVIDIA/vLLM は 「supporting vLLM image が正式公開されるまで暫定であり変更されうる」 と明記しています。NVFP4 形式も experimental 扱いです。再現性のためイメージは digest で固定しています（スクリプト参照）。新しい イメージが出たら digest を更新してください。将来 mainline の vLLM が diffusion_gemma を取り込めば、 この特別イメージは不要になる見込みです。

要件

• NVIDIA Blackwell または Hopper GPU（NVFP4 には FP4 対応ハードが必要）、空き VRAM 約 30 GB
• Docker ＋ NVIDIA Container Toolkit（--gpus all が機能すること）
• モデル重み用に約 13 GB のディスク（初回のみ ~/.cache/huggingface に取得）

かんたん起動（ワンコマンド）

BACKEND=vllm ./start.sh

これだけで、vLLM コンテナの起動（初回のDL・ロード＋自動ウォームアップ）→ アプリ (FastAPI, :8012) の起動までを一括で行います。起動後はブラウザで http://localhost:8012 を開いてください。停止は Ctrl + C（既定では vLLM コンテナは起動したまま＝次回が速い。終了時にコンテナも止めたい場合は STOP_BACKEND_ON_EXIT=1 BACKEND=vllm ./start.sh）。

主な調整用環境変数（任意）：

変数	既定	用途
VLLM_PORT	8000	待受ポート
VLLM_GPU_MEM_UTIL	0.75	VRAM 使用率上限（OOM 時は下げる）
VLLM_MAX_MODEL_LEN	8192	最大コンテキスト長
VLLM_IMAGE	digest 固定	別イメージを使う場合
STOP_BACKEND_ON_EXIT	0	終了時に vLLM コンテナも停止する

手動で個別に制御する場合

バックエンド（vLLM コンテナ）だけを起動・停止・確認：

./app/scripts/run_vllm_backend.sh start     # 冪等。起動の最後に自動ウォームアップ
./app/scripts/run_vllm_backend.sh stop
./app/scripts/run_vllm_backend.sh status

初回は重みのダウンロードとモデル読み込みで数分かかります。起動直後の最初の 1 リクエストは 一度きりの CUDA/コンパイル処理のため遅く（約 4〜5 秒）品質も落ちるので、スクリプトは最後に小さな ウォームアップを自動実行します。

すでに起動済みの外部サーバにアプリを向けるだけなら（BACKEND を使わない従来の方法）：

SKIP_LLAMACPP=1 \
LLAMA_SERVER_URL=http://127.0.0.1:8000 \
LLAMA_MODEL_NAME=nvidia/diffusiongemma-26B-A4B-it-NVFP4 \
./start.sh

• スクリプトが付与する --default-chat-template-kwargs '{"enable_thinking":false}' は 必須です。 これが無いとモデルが回答を「思考(reasoning)」として出力し、アプリ側の content が空になります。

どちらを使うべき？

	GGUF（既定）	vLLM / NVFP4（任意）
対応 GPU	ほぼ全 GPU / CPU	Blackwell / Hopper のみ
遅延（OCR＋翻訳）	数秒	約 0.5 秒（ウォーム後）
セットアップ	llama.cpp をビルド	docker pull
安定性	安定	実験的（公開前イメージ）
VRAM	調整可（約 16 GB〜）	約 30 GB

品質は同等です（同じ Gemma-4-26B-A4B ベース）。対応ハードでは速度重視で vLLM、可搬性重視で GGUF を 既定のまま、という使い分けがおすすめです。

困ったとき

• 起動時に CUDA out of memory → VLLM_GPU_MEM_UTIL を下げる（例 0.70）、必要なら VLLM_MAX_MODEL_LEN=4096 も： VLLM_GPU_MEM_UTIL=0.70 VLLM_MAX_MODEL_LEN=4096 ./app/scripts/run_vllm_backend.sh start
• 翻訳が空で返る → サーバが enable_thinking:false で動いているか確認（スクリプト既定で付与）。
• 最初の 1 回だけ遅い/崩れる → ウォームアップが実行されたか確認（スクリプトが自動実行）。
• モデル側ログ → docker logs dgemma

フロントエンドの使い方

• ブラウザで http://localhost:8012 にアクセス。
• 画像を 貼り付け (Ctrl+V) するかドラッグ&ドロップ。
• 任意で追加指示を入力し「再送信」。
• 返ってきた Markdown を「コピー」ボタンで取得可能。
• CSS で横に長い行も折り返して表示。

アーキテクチャ

• llama.cpp の llama-server --api を常駐させ、OpenAI 互換 /v1/chat/completions でマルチモーダル推論。
• FastAPI (ポート 8012) が画像を PNG に正規化 → llama-server へ base64 画像付きメッセージ送信。
• 応答 Markdown をそのまま表示 (要約禁止プロンプトを付与)。
• Windows 常駐クライアントは windows/OverlayClient にあり、Ctrl+Alt押下/離しでROIを取得して /api/v1/ocr_translate_with_grounding に送信する。トレイの「Speak Translation」を有効にすると、表示した文字列をそのまま /api/v1/speak に渡して読み上げる。

Windows 常駐クライアント（WPF）

• 参照先: windows/OverlayClient
• 前提: Windows 10/11 + .NET 8 SDK（dotnet --version で確認）
• WSL2でこのリポジトリをCloneした場合は、windowsフォルダをWindows側にコピーしてビルド・実行してください。
• 先に WSL 側の FastAPI を起動しておく（./start.sh、ポート 8012）。
• ビルド:

  cd windows/OverlayClient
  dotnet build

• 実行:

  dotnet run

• 配布用にまとめる:

  dotnet publish -c Release -o output

  • output/ に実行ファイル一式が出力されます（settings.json も同梱）。
• settings.json は exe と同じフォルダに置かれ、ビルド出力に同梱されます。
• WSL 側に繋がらない場合は settings.json の server.base_url を確認してください。
• 既定は Ctrl+Altを押しながらドラッグし、キーを離すと矩形ROI指定 → 翻訳実行です（Ctrlのみ/Altのみは設定で変更可）。
• 既定で ROI は 赤枠で一瞬表示されます（overlay.preview.show_roi_preview）。
• Ctrl押下中のリアルタイム枠表示は overlay.preview.live_preview で切替できます。
• オーバーレイは「×」で閉じられます（アプリ自体の終了はトレイメニューの Quit）。

Ubuntu Gnome Extension (Screenshot Translator)

Ubuntu (Gnome Shell) 環境向けの専用拡張機能です。Windows 版とは操作感が異なります。 バージョン19以降、トップバーのメニューからモード切替が可能になりました。

前提

• Python バックエンド (./start.sh) が 127.0.0.1:8012 で起動している必要があります。
• 対応 GNOME Shell: 46〜50（Ubuntu 24.04 / 26.04・26.04.1 を含む）。Ubuntu のバージョンではなく、gnome-shell --version で確認できます。
• Ubuntu 26.04 系は Wayland で使用します。24.04 の Wayland / X11 向け互換性も維持しています。

インストール方法

リポジトリのルートで次のコマンドを実行します。更新時も同じコマンドで再インストールできます。

./gnome-extension/install.sh

インストーラーは対応 Shell バージョンを確認し、metadata.json の UUID に一致するディレクトリへコピーして、設定スキーマをコンパイルします。ユーザー名への書き換えは不要です。既存のインストール先がシンボリックリンクの場合はリンクをバックアップしてからコピーに切り替えます（リンク先のソースは保持されます）。既存の設定は維持されます。

有効化

インストール・更新後は、通常は Gnome Shell を再読み込みします。

• Wayland (Ubuntu 標準): 一度ログアウトして、再度ログインしてください。
• X11 (24.04 など): Alt + F2 を押し、r を入力して Enter。

再読み込み後、「Extensions (拡張機能)」アプリまたは「Extension Manager」を開き、Screenshot Translator を有効にしてください。

コマンドで有効化・状態確認する場合:

gnome-extensions enable screenshot-translator@amariichi
gnome-extensions info screenshot-translator@amariichi

OS 更新後の OUT OF DATE を再ログインなしで復旧する場合

OS 更新後に古い拡張が OUT OF DATE（非対応）判定で起動しておらず、./gnome-extension/install.sh で対応版をインストール済みの場合は、次の方法で読み込み直せます。Ubuntu 26.04.1 / GNOME Shell 50.1 で、再ログインせずに常駐・翻訳が動くことを確認しています。gnome-extensions enable だけでは、Shell に残った古い対応バージョン情報は更新されません。

以下のコードの入力先は、GNOME の開発者コンソール「Looking Glass」の Evaluator（評価器）です。通常のターミナル（Bash）に貼り付けると構文エラーになります。

1. Alt + F2 を押し、lg と入力して Enter。

2. 開いた画面の Evaluator の >>> 欄に、以下を 1行で入力して Enter。await の後は半角スペースです。画面上の自動折り返しは問題ありません。

   await Main.extensionManager.reloadExtension(Main.extensionManager.lookup('screenshot-translator@amariichi'))

3. r(0) = undefined のように表示されても、処理が戻り値を返さないための正常な表示です。Esc で閉じ、トップバーの辞書アイコンを確認してください。

状態は、通常のターミナルで gnome-extensions info screenshot-translator@amariichi を実行して確認できます。Looking Glass の操作は GNOME 公式ガイド にも説明されています。

この方法は、非対応判定で実装コードがまだ読み込まれていない場合の復旧手順です。すでに動作していた拡張のコードを更新する場合は、上記のログアウト・再ログインなどで Shell を再読み込みしてください。

使い方

画面上部（トップバー）に追加される 辞書アイコン「あ」 (または類似のアイコン) からモードを切り替えて使用します。

1. モード選択: トップバーのアイコンをクリックし、以下のいずれかを選択します。

   • Text Overlay Mode (翻訳モード) [デフォルト]: 選択範囲を翻訳して画面に表示します。
   • TTS Once Mode (読み上げ・1回): 選択範囲を一度だけOCR→翻訳→読み上げします（監視しません）。
   • TTS Monitor Mode (読み上げモード): 選択範囲を定期的に監視し、変化があった箇所を日本語で読み上げます。

2. キャプチャ開始:

   • ショートカット: Ctrl + Alt + S
   • 画面が少し暗くなり、マウスドラッグで範囲を選択します。
   • Esc または 右クリック で範囲選択をキャンセルできます。

3. Monitor Mode (読み上げ) の挙動:

   • 選択後、バックグラウンドで 5秒ごとに 選択範囲を監視します。
   • 監視中はトップバーのアイコンが赤くなり、メニューに「Stop Monitoring」が表示されます。
   • 新しいテキスト（チャットの追記やスクロールなど）が検出されると、自動的に日本語で読み上げられます（Supertonic 3 ONNX 音声合成エンジンを使用）。
     • Mixed TTS: 日本語と英語が混在していても、言語を自動判定して1つの声で途切れずに読み上げます。
     • Stability: 翻訳の揺らぎを抑制し、無駄な再読み上げを減らしました。
     • Full Read: 初回起動時は、検出されたテキスト全文を読み上げます。
     • Chunked Read: 長文は文単位で順次読み上げ、最初の音が早く出るようにしています。
   • 停止するには、再度ショートカットを押して新しい範囲を選ぶか、メニューから「Stop Monitoring」を選択してください。

4. Monitor Mode のリセット:

   • 別の範囲を選択したい場合は、再度 Ctrl + Alt + S を押してください。古いモニタリングは停止し、新しい範囲で即座に開始されます。

アンインストール (取り除き方)

拡張機能を削除するには、以下のディレクトリを削除し、Gnome Shell を再読み込みします。

gnome-extensions uninstall screenshot-translator@amariichi

その後、ログアウト/ログイン (または Alt+F2 r) してください。

トラブルシューティング

• OS 更新後に OUT OF DATE になる: ./gnome-extension/install.sh で対応版をインストールしてください。再ログインを避けたい場合は、上記「OS 更新後の OUT OF DATE を再ログインなしで復旧する場合」の手順を使えます。GNOME 全体のバージョンチェックを無効にする必要はありません。
• 更新が反映されない: Wayland では Alt+F2 r が使えないため、ログアウト/ログインしてください。ファイルを更新しただけでは、動作中の Shell に残った古いコードやメタデータは再読み込みされません。
• 翻訳・TTS が動かない: バックエンドの起動と curl http://127.0.0.1:8012/health を確認してください。拡張のエラーは journalctl -b /usr/bin/gnome-shell --no-pager で確認できます。
• Pango エラー: 古いバージョンがキャッシュされている可能性があります。一度アンインストール操作を行ってから再インストールしてください。

開発者向け動作確認

GNOME 50 の gnome-shell-test-tool で、現在のデスクトップとは独立したヘッドレス Shell に拡張を読み込み、範囲選択のキャンセル、PNG 取得、翻訳表示、TTS 用送信、無効化・再有効化を確認できます。通信先にはランダムなローカルポートのテストサーバーを使うため、LLM や読み上げサーバーの起動は不要です。実際のOCR・翻訳品質・音声はこのテストの対象外です。

mkdir -p /tmp/screenshot-translator-test
gnome-extensions pack --force --out-dir /tmp/screenshot-translator-test gnome-extension
dbus-run-session -- gnome-shell-test-tool --headless \
  --extension /tmp/screenshot-translator-test/screenshot-translator@amariichi.shell-extension.zip \
  "$PWD/tests/gnome-extension-smoke.js"

GNOME の バージョン別移行ガイド も参照してください。

新API（WSL側）

• GET /health
• POST /api/v1/ocr_translate_with_grounding（clean_image (必須) と guide_image (任意) を multipart で送信）
• POST /api/v1/ocr_translate_tts_once（OCR→翻訳→読み上げを1回実行）
• POST /api/v1/speak（{"text": "..."} を読み上げるだけ。推論はしない。呼び出し側が表示した文字列をそのまま読ませるためのもので、Windows 常駐クライアントの「Speak Translation」が使う）

開発メモ

• 依存は仮想環境内 (uv sync) のみでインストールされ、ホストには入れません。
• フロントはプレーン HTML/CSS/JS (ビルド不要)。
• Markdown レンダリングは軽量な独自実装で、コード/箇条書き/強調をサポート。

既知の注意点

• llama.cpp 初回起動時にモデルをロードするため、1 回目のリクエストは時間がかかります。モデルのロードが完了（ステータスに「準備完了 (ログより) / 起動中（API応答あり・モデル読み込み未確認）」と表示されます。）しても翻訳が実行されない場合は、お手数ですが、再度画像を張り付けてください。
• モデル読み込み中に画像を貼り付けると失敗する場合があります。ステータスが「準備完了」と表示されてから貼り付けてください。
• LLAMA_CTX を大きくすると VRAM 使用量が増えます。GPU メモリに合わせて起動時に調整してください。