# GitHub 中文化 (繁體)

一份 ScriptCat / Tampermonkey 用的 UserScript，把 GitHub 介面轉成台灣用語的繁體中文，不動使用者內容（檔名、commit 訊息、Issue 標題、程式碼、README）。

> 想快速裝起來用？看 [`QUICKSTART.md`](./QUICKSTART.md)
> 想看一路怎麼做出來的？看 [`SUMMARY.md`](./SUMMARY.md)

## 檔案

| 檔案 | 用途 |
|---|---|
| `github-zh-tw.user.js` | 腳本本體（貼到 ScriptCat / Tampermonkey） |
| `README.md` | 參考手冊（本檔）— 功能、架構、規則 |
| `QUICKSTART.md` | 安裝與自訂操作指南 |
| `SUMMARY.md` | 開發故事線、設計取捨 |

## 功能概覽

| 類別 | 例子 |
|---|---|
| 導覽列 | `Code` / `Issues` / `Pull requests` / `Actions` / `Security` / `Insights` |
| 倉庫側欄 | `About` / `Releases` / `Contributors` / `Sponsor this project` |
| Branches 頁 | `Default` / `Active` / `Stale` / `All` / `Behind` / `Ahead` |
| Issue / PR 列表 | `Sort by` / `Newest` / `Oldest` / `No results found` |
| 數字縮寫 | `62.8k` → `6.3 萬`、`1.2M` → `120 萬`、`7,800` 千分號 |
| 相對時間 | `3 days ago` → `3 天前`、`last month` → `上個月` |
| 頁尾 / 無障礙 | `Terms` / `Privacy` / `Footer navigation` / `GitHub Homepage` |

## 不翻什麼（刻意）

| 內容類別 | 選擇器依據 |
|---|---|
| 檔名、資料夾名 | `.react-directory-filename-column`、`a[href*="/blob/"]`、`a[href*="/tree/"]` |
| Commit 訊息 | `a[href*="/commit/"]`、`[data-testid="latest-commit-details"]` |
| Repo 描述 | `.BorderGrid-cell > p`、`.f4.my-3`、`[itemprop="about"]` |
| Topic 標籤 | `a.topic-tag`、`.topic-tag-link` |
| 使用者 / 組織名 | `a[data-hovercard-type="user"]`、`a[data-hovercard-url*="/users/"]` |
| README（渲染後） | `.markdown-body` |
| 程式碼檢視 | `.blob-code-inner`、`.highlight`、`.react-code-lines` |
| Issue / PR 標題 | `.markdown-title`、`.js-issue-title` |
| 搜尋語法（`is:issue state:open`） | `[role="searchbox"]`、`[role="combobox"]`、`.pl-c1` 等 |
| Labels | `.IssueLabel`、`.Label` |
| 編輯器、程式碼輸入 | `<code>`、`<pre>`、`<input>`、`<textarea>`、`[contenteditable]` |

## 核心架構

### 替換流程（`replaceText` 三層）

```
text
 ├─ 1. TIME_AGO_REGEX         "3 days ago"   → "3 天前"
 │   /\b(\d+)\s+(second|minute|hour|day|week|month|year)s?\s+ago\b/gi
 │
 ├─ 2. WORD_BOUNDARY_REGEX    詞庫批次替換
 │   長詞優先、大小寫不敏感
 │
 └─ 3. ABBREV_REGEX           "62.8k" → "6.3 萬"
     /\b(\d+(?:\.\d+)?)([kKmM])\b/g
```

### 跳過規則（`shouldSkipTextAncestor`）

```
elements (往祖先走)
 ├─ SKIP_TAGS             SCRIPT / STYLE / CODE / PRE / INPUT / TEXTAREA / NOSCRIPT
 ├─ isContentEditable     (所有可編輯區)
 ├─ role="textbox"
 └─ closest(SKIP_CONTEXT_SELECTOR)
     └─ 使用者內容脈絡（見上表）
```

**屬性翻譯獨立於文字節點**：
`<input placeholder="Search branches...">` 的 placeholder 會翻，但輸入內容不動。

### 掃描策略

| 對象 | 方法 |
|---|---|
| 所有文字節點 | `TreeWalker(NodeFilter.SHOW_TEXT)`，不靠白名單 |
| 屬性 | `querySelectorAll('[data-content], [aria-label], [title], [placeholder]')` |

### 動態更新

- **`MutationObserver`**：監聽 `childList` + `attributes`，新增節點立即翻、屬性變更立即補。
- **SPA 路由**：hook `history.pushState` / `replaceState`，監聽 `popstate`、`turbo:load`、`turbo:render`。
- **150ms debounce**：保險起見切頁／大量 DOM 變動後做一次全域掃描。

## 詞庫結構

`TRANSLATION_MAP`（`Map`）按分類排列：

1. 倉庫導覽（Code / Issues / PR / Actions…）
2. 關注 / 分支 / 星標（Watch / Fork / Star）
3. 倉庫側欄（About / Releases / Contributors…）
4. 檔案列表操作（Go to file / Add file / Clone…）
5. PR / Issue 按鈕（New issue / Merge / Review changes…）
6. 列表篩選（Open / Closed / Author / Labels…）
7. 全站導覽 / 使用者選單
8. 通用動作（Save / Cancel / Edit…）
9. 頁尾 / 無障礙
10. 相對時間短語

**長詞優先**：建構 regex 時會依字串長度排序，讓 `Active branches` 優先於 `Branches` 單字匹配。

## 翻譯規則的限制

### 大小寫不敏感 → 同詞只能一個翻譯
`Open`（tab）和 `opened`（動詞）經 `gi` + `LOWER_MAP` 查表會得到同一翻譯。本腳本選「保留 tab 翻譯」，動詞的 `opened` 保持英文。

### 結尾標點不可作為關鍵詞一部分
`Search branches...` 的結尾 `\b` 會失敗（`.` 非字元 + 後面也非字元）。詞庫只放 `Search branches`，regex 會在 `\b` 前停下，保留原 `...`。

### 使用者內容的邊界判斷
靠穩定的語意屬性（`role` / `data-testid` / `data-hovercard-*` / `href` pattern），避開 React CSS 模組的 hash class。

## 數字格式化規則

```
val ≥ 1,000,000   →  "X 萬"    (≥100 萬無小數 / 否則 1 位小數)
1,000,000 > val ≥ 10,000  →  "X.X 萬"  (1 位小數，.0 去掉)
10,000 > val              →  "X,XXX"   (千分號)
val 為純整數（無 k/M 後綴） →  不處理
```

## 相容性

| 項目 | 狀態 |
|---|---|
| ScriptCat / Tampermonkey / Violentmonkey | ✅ |
| Chrome / Edge / Firefox / Safari | ✅ |
| GitHub Turbo / React 新 UI | ✅ |
| GitHub Classic UI | ✅（維持運作） |
| GitHub Enterprise | 未測試（`@match` 需調整） |

## 授權

MIT