# 多語系管理與自動對齊規範 (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 編碼參數：
  ```php
  JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
  ```

---

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

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

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

```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` 確認修改範疇僅限於新增的語系，無亂序與無關的語系被刪除。
