/translate

觸發

G6（smoke build 的 20 條）或 G7（實機確認後的大量翻譯）；或使用者說「開始翻譯」。只在有模型的站點（dgxluna）跑。

輸入

• projects/<game>/exported/script.json（有 .agt.json sidecar 才知道引擎；沒有就加 --engine）。
  兩站流程：先 git pull → $PY agt.py detect <交接包> → $PY agt.py handoff unpack <交接包>，並讀 HANDOFF.md 最新一段（smoke 的 --filter 在那裡）。
• 選用 projects/<game>/glossary.txt（自動載入）或 --dict；font_charset.txt／charset_map.json（fix_text 自動用）。

步驟

# $PY / $PYT 見 CLAUDE.md §3（dgxluna：conda galtransl / nllb-env）
S=projects/<game>/exported/script.json
$PY  tools/translate.py -i $S --dry-run --limit 20        # 不連線：看篩選／去重／prefix 拆分是否合理
bash tools/llama_server.sh status || bash tools/llama_server.sh start
$PYT tools/translate.py -i $S --limit 20 --filter <開場正則> --log projects/<game>/logs/translate.log   # G6 小樣本
# --- 使用者實機確認、mark user_boot_ok 之後（兩站：隨交接包 #3 過來，或使用者直接對翻譯端說 OK 就自己 mark）---
$PYT tools/translate.py -i $S --log projects/<game>/logs/translate.log             # G7，用 run_in_background 跑
$PYT tools/fix_text.py $S                                  # s2twp、符號表、統一譯法、控制碼退回、字型缺字替換（projects/<game>/font_charset.txt）
$PY  tools/check_codes.py $S                               # 任何 fatal → exit 1，先修再導入
$PY  agt.py validate <game>
$PY  agt.py handoff pack <game>                            # 兩站流程：交回實機端 import/verify/package（/handoff）

1. 沒有 user_boot_ok 又沒給 --limit，translate.py 會拒絕（--force 可越過，但不該用）。
2. 大量翻譯用 run_in_background，等完成通知；期間做準備工作。每批日誌有時間戳與吞吐（約 3 條/秒）。
3. 中斷可重跑，檢查點 .agt_checkpoint.json 以 (source_file, location) 為鍵；看到舊式 .script_checkpoint.json 要先刪。檢查點會隨交接包走。
4. --priority N 只翻優先級 ≤ N 的 context；--include-optional 才翻 risky 的（Wolf string_var/condition、RPG Maker picture_name…）。
5. 翻譯端骨架專案（沒 original/）不能 import／package——那是實機端的事，pack 回去即可。

輸出

• 填好 translated 的 script.json、translate.log、控制碼報告；fix_text 前的備份 script.backup-<ts>.json；兩站流程再加交接包。

停下來問使用者

• G6 小樣本導入打包後（見 /deliver-patch）。
• 失敗率異常（>5%）或譯文明顯不對時，先查 endpoint／模型再重跑。

詳見 docs/translation-quality.md。