# 網頁本地化
支援繁體中文與英文：運行狀態（/runtime）、專用瀏覽器（/browser）、人流分析（/traffic）與主控台導覽。人流分析的圖表、日期操作、歷史表格與清理介面使用 `traffic.*`；`/logViewer`、`/autoclip`、`/keyword` 的人流分析入口也已本地化。其餘未標記的介面仍維持中文，聊天內容、平台名稱、分頁標題、日誌與底層錯誤不自動翻譯。
## 使用方式
在已支援頁面導覽列選擇語言。選擇保存於同一來源的 localStorage（ttw.language），跨頁保留，其他已開啟且支援翻譯的分頁同步更新。不同連接埠或主機的選擇各自保存。無法使用儲存空間時仍可在當頁切換。
## 新增翻譯
- lang/zh-TW.json 是主要對應表；lang/en.json 可逐步補齊。
- 使用穩定的扁平 key，例如 runtime.state.running，避免用整句中文作 key。
- 顯示順序：所選語言 → 繁體中文 → 呼叫處預設文字 → key。空字串或全空白視同缺漏。
- 參數使用 {seconds}、{time} 等名稱，各語言保留相同參數名稱，可調整順序。
- 不放 HTML；前端以 textContent 更新文字，參數不會被解析為標籤。
## 接入頁面
在純文字節點加入 data-i18n="對應key"，保留中文原文作載入失敗時的備援。避免標記包含按鈕、連結等子元素的容器。title 亦可標記；html lang 由共用程式更新。
在頁面 DOM 後、頁面程式前載入 /assets/i18n.js。語言選單標記 data-language-select，選項由共用程式依 lang/index.json 自動產生；HTML 只需保留繁體中文作載入失敗的備援。
動態文字使用 window.TTWI18n.t(key, params, 中文預設文字)。首次初始化等待 TTWI18n.ready；監聽 document 的 languagechange 事件重新呈現動態狀態。瀏覽器 API 的 code 用於翻譯，原 error 仍保留供舊客戶端及未收錄的錯誤回退。
## 新增語言（只需兩個 JSON）
1. 新增 lang/ja.json，可先填入部分 key；缺漏項目回退繁體中文。
2. 在 lang/index.json 的 languages 加入 { "code": "ja", "label": "日本語" }。
清單範例：
```json
{
"default": "zh-TW",
"languages": [
{ "code": "zh-TW", "label": "繁體中文" },
{ "code": "en", "label": "English" },
{ "code": "ja", "label": "日本語" }
]
}
```
code 對應同名 JSON 檔案（大小寫需一致），使用有效語言代碼，如 ja、en-US；label 是選單名稱，順序依清單排列。default 是未保存偏好或已移除原選擇時的預設語言；翻譯缺漏仍固定回退繁體中文。
後端與前端共用清單驗證，忽略非法代碼、重複語言及空白名稱；保留繁體中文作備援。未登記的 JSON 不對外提供。清單缺檔或格式錯誤時僅提供繁體中文。
部署本次程式更新需重啟一次主服務；之後新增或移除語言，只需更新 JSON 並重新整理頁面，不必修改 JS、HTML 或重啟。已開啟的頁面要重新整理才會取得新清單。只改語系 JSON 不需要重建 CSS。
## 驗證
npm run test:core 包含 Test/i18n.test.cjs 與靜態資源路由測試，驗證回退、插值、參數一致性、切換競態、儲存被拒及語系載入失敗。英文尚未補齊不會導致測試失敗。
修改根目錄 HTML 後執行 npm run build:css，再執行 npm run test:ci。新增頁面仍需檢查長英文與手機寬度的呈現。