# 快速上手

## 1. 安裝瀏覽器擴充套件

三選一皆可：

- [ScriptCat](https://scriptcat.org/)（推薦，開源）
- [Tampermonkey](https://www.tampermonkey.net/)
- [Violentmonkey](https://violentmonkey.github.io/)

## 2. 安裝腳本

### 方法 A：直接貼

1. 開啟 ScriptCat / Tampermonkey 管理面板
2. 點「建立新腳本」
3. 把 `github-zh-tw.user.js` 全文貼上
4. 儲存（Cmd/Ctrl + S）

### 方法 B：從網址安裝

把腳本掛到任何 raw 檔案網址（GitHub Gist、Gitea raw URL、自架 web server）然後進該網址，擴充套件會自動跳出安裝視窗。

## 3. 驗證

打開 https://github.com ，側欄應該變成：

```
Code          → 原始碼
Issues        → 問題
Pull requests → 拉取請求
62.8k stars   → 6.3 萬 星標
3 days ago    → 3 天前
```

沒作用？看本檔最後 [常見問題](#常見問題)。

---

## 自訂翻譯

### 新增一個詞

打開腳本，找 `TRANSLATION_MAP`：

```js
const TRANSLATION_MAP = new Map([
  ['Code', '原始碼'],
  // ...
  ['My custom term', '我的自訂詞'],   // ← 加在這裡
]);
```

存檔後重新載入 GitHub 頁面即可。

### 長詞優先規則

若你加了 `Open pull request`，就算已經有 `Open` → `開啟中`，長詞會先被匹配。所以遇到半翻情況（像 `開啟 pull request`），直接加整句進去。

### 多種譯法選擇

同一個英文詞在不同語境可能想要不同翻譯（例如 `Open` 當 tab vs. 動詞）。**做不到**—regex 是大小寫不敏感的。
取捨原則：保留使用頻率高、不翻會更奇怪的那個意思。

---

## 自訂「不翻」範圍

### 不想翻某個 class / 元素

打開腳本找 `SKIP_CONTEXT_SELECTOR`，加一行：

```js
const SKIP_CONTEXT_SELECTOR = [
  // ...
  '.my-custom-dont-translate',   // ← 加這
  '[data-no-translate]',          // 或用屬性
].join(',');
```

該元素與所有子孫的文字節點都會被跳過，但**它的屬性（如 `aria-label`）仍會翻**；若連屬性都不想翻，請從 `ATTR_SELECTOR` 那邊獨立處理（罕見）。

### 不想翻整個網域 / 路徑

改腳本開頭的 `@match`：

```js
// @match        https://github.com/*
// @match        https://github.com/yourorg/*   ← 只翻這個 org
// @exclude      https://github.com/settings/*  ← 排除設定頁
```

---

## 更新

從來源倉庫複製最新 `github-zh-tw.user.js` 全文，貼回 ScriptCat / Tampermonkey 的編輯器覆蓋儲存。不需要重裝擴充套件。

---

## 常見問題

### Q1：安裝後沒變化
- 確認 ScriptCat / Tampermonkey 擴充套件是**開啟**狀態
- 確認腳本在 `https://github.com/*` 頁面顯示為「已執行」
- 重新載入頁面（Cmd/Ctrl + Shift + R 強制重載）

### Q2：某些詞還是英文
- 可能是剛加入 GitHub 的新 UI，詞庫還沒收錄 → 依上方「新增一個詞」加入
- 可能是文字在被跳過的區塊（README、程式碼、Issue 標題…）→ 這是刻意的

### Q3：搜尋功能壞了
原因：`state:open` 這類過濾語法被翻。這不該發生 — 若發生，檢查是否有第三方腳本干擾，或 GitHub 改版了搜尋元件的 class。
暫時停用腳本可恢復。

### Q4：檔名被翻成中文
原因：GitHub 改版導致檔案列表 class 變動，跳過規則失效。
修法：檢查該檔名元素的 DevTools，找穩定的 class / 屬性加進 `SKIP_CONTEXT_SELECTOR`。

### Q5：效能變慢、Chrome 高 CPU
- 先停用本腳本看是否為本腳本造成
- 若是，檢查自己是否改過腳本讓 debounce 失效 / MutationObserver 範圍過大
- 保持預設 `150ms` debounce 通常不會有感卡頓

### Q6：看到「Active 分支清單」這種半翻
詞庫中 `Branches` 被單獨翻了卻沒有整句版本。加整句進 `TRANSLATION_MAP` 即可（長詞會優先匹配）。

### Q7：自己伺服器上的 Gitea / GitHub Enterprise 也想用
改 `@match` 指向你的網域。注意 GHES 的 class 可能與 github.com 有差異，部分跳過規則需要調整。

---

## 回報 / 建議

看到沒翻或誤翻的地方，最快回報方式：

1. 截圖有問題的頁面
2. DevTools 右鍵檢查，把該元素的 HTML 片段一起附上
3. 提 Issue 或直接在詞庫 PR