star-cloud/.agents/skills/multilingual-specs/SKILL.md

多語系管理與自動對齊規範 (Multilingual Specs)

本技能規範定義了 Star Cloud 系統中所有多語系 JSON 檔案（位於 lang/）的維護標準。當專案需要新增、修改或校對多語系時，必須嚴格遵守此規範。

---

核心三大原則 (CRITICAL RULES)

1. 三語系完美對齊 (Master-Align)

• 以 zh_TW.json 為唯一標準：不論任何時候新增或修改翻譯 Key，都必須以 lang/zh_TW.json 的鍵值（Keys）集合為絕對標準。
• 三檔對齊：lang/en.json 與 lang/ja.json 的鍵值集合必須與 zh_TW.json 百分之百相同（行數、數量與 Key 的拼寫必須完全一致）。

2. 字母順序排序 (ksort)

• 為避免 Git 版本控制產生大範圍的亂序 Diff，三個 JSON 檔案中的所有鍵值對，必須一律按 Key 的英文字母升冪順序 進行排序（類似 PHP 的 ksort()）。

3. 斜線不逸出與美化 (No Escaped Slashes)

• 禁止使用預設 json_encode 逸出斜線：JSON 檔案中的網址或路徑斜線一律使用 /，嚴禁產生 \/。
• 儲存格式化要求： 在寫入語系 JSON 檔案時，必須使用以下 JSON 編碼參數：

  JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
  

---

自動化對齊工具 (I18n Alignment Tool)

當處理語系變更時，AI 助手應在專案的 scratch/ 目錄中建立一個臨時 PHP 腳本（例如 scratch/align_lang.php），執行對齊並排序後，立即將其刪除。

🔧 臨時對齊腳本範本 (scratch/align_lang.php)

<?php
/**
 * Star Cloud - 多語系自動對齊與排序工具
 * 執行指令：php scratch/align_lang.php
 */

$langDir = __DIR__ . '/../lang/';
$zhPath = $langDir . 'zh_TW.json';
$enPath = $langDir . 'en.json';
$jaPath = $langDir . 'ja.json';

if (!file_exists($zhPath)) {
    die("❌ 找不到 zh_TW.json 主語系檔！\n");
}

$zhData = json_decode(file_get_contents($zhPath), true);
$enData = file_exists($enPath) ? json_decode(file_get_contents($enPath), true) : [];
$jaData = file_exists($jaPath) ? json_decode(file_get_contents($jaPath), true) : [];

// 1. 精準翻譯對照字典 (用於自動補齊常見系統/機台特有詞彙)
$translationDict = [
    // 通行碼/機台/權限相關
    "Channel Limits Config" => [
        "en" => "Channel Limits Config",
        "ja" => "チャンネル制限設定"
    ],
    "Connection error" => [
        "en" => "Connection error",
        "ja" => "接続エラー"
    ],
    "Passcode settings" => [
        "en" => "Passcode settings",
        "ja" => "パスコード設定"
    ],
    "Reset Passcode" => [
        "en" => "Reset Passcode",
        "ja" => "パスコードをリセット"
    ],
    "Update Passcode" => [
        "en" => "Update Passcode",
        "ja" => "パスコードを更新"
    ],
    "Machine Authorization" => [
        "en" => "Machine Authorization",
        "ja" => "デバイス授権"
    ],
    "Status" => [
        "en" => "Status",
        "ja" => "ステータス"
    ],
    "Actions" => [
        "en" => "Actions",
        "ja" => "操作"
    ]
];

$missingEnCount = 0;
$missingJaCount = 0;

$newEnData = [];
$newJaData = [];

// 2. 以 zh_TW 的 keys 為基準對齊 en 與 ja
foreach ($zhData as $key => $zhVal) {
    // 處理英文
    if (isset($enData[$key]) && trim($enData[$key]) !== '') {
        $newEnData[$key] = $enData[$key];
    } else {
        // 嘗試從精準字典查找
        if (isset($translationDict[$key]["en"])) {
            $newEnData[$key] = $translationDict[$key]["en"];
        } else {
            // fallback: 使用 key 原始名稱作為英文
            $newEnData[$key] = $key;
        }
        $missingEnCount++;
    }

    // 處理日文
    if (isset($jaData[$key]) && trim($jaData[$key]) !== '') {
        $newJaData[$key] = $jaData[$key];
    } else {
        // 嘗試從精準字典查找
        if (isset($translationDict[$key]["ja"])) {
            $newJaData[$key] = $translationDict[$key]["ja"];
        } else {
            // fallback: 如果 key 與英文相同，且非中文，可先 fallback 英文，後續再由 LLM 補譯
            $newJaData[$key] = $key;
        }
        $missingJaCount++;
    }
}

// 3. 字母排序 (ksort)
ksort($zhData);
ksort($newEnData);
ksort($newJaData);

// 4. 寫回檔案 (反逸出斜線 + Unicode)
$jsonFlags = JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE;

file_put_contents($zhPath, json_encode($zhData, $jsonFlags) . "\n");
file_put_contents($enPath, json_encode($newEnData, $jsonFlags) . "\n");
file_put_contents($jaPath, json_encode($newJaData, $jsonFlags) . "\n");

echo "✅ 多語系處理完畢！\n";
echo "📊 統計結果：\n";
echo "   - 總共鍵數: " . count($zhData) . " 個\n";
echo "   - 補齊英文空缺: {$missingEnCount} 個\n";
echo "   - 補齊日文空缺: {$missingJaCount} 個\n";

---

💡 AI 助手處理語系之 SOP 流程

當使用者要求修改或補齊語系時，AI 必須：

1. 同步更新/新增 zh_TW.json：將新的詞彙加入 zh_TW.json 中。
2. 利用 LLM 翻譯補足空缺：
   • 針對新加入的詞彙，由 AI 運用其 LLM 能力將高品質的英文（en）與日文（ja）翻譯出來。
3. 擴充對齊腳本的暫存字典：
   • 將這些新翻譯的詞彙暫時寫入臨時對齊腳本 scratch/align_lang.php 中的 $translationDict 中。
4. 執行一鍵對齊與字母排序：
   • 在終端機執行 php scratch/align_lang.php，確保三個語系 JSON 檔案行數百分之百對齊、全部排序、斜線清空。
5. 清理暫存：
   • 刪除 scratch/align_lang.php。
6. Git 檢查與提交：
   • 執行 git diff 確認修改範疇僅限於新增的語系，無亂序與無關的語系被刪除。