159 lines
7.1 KiB
Markdown
159 lines
7.1 KiB
Markdown
# GitHub 中文化 (繁體) UserScript — 開發紀錄
|
||
|
||
一份給 ScriptCat / Tampermonkey 用的 GitHub 介面繁體中文化腳本，檔案在 `github-zh-tw.user.js`。本文件紀錄從 v0.6 一路迭代到 v0.15 的過程、遇到的坑與解法。
|
||
|
||
## 設計原則
|
||
|
||
1. **只翻 GitHub 介面本身，不動使用者內容。** 檔名、commit 訊息、issue 標題、使用者名稱、topic 標籤、repo 描述、README、程式碼一律保留原樣。
|
||
2. **不破壞功能。** 搜尋語法（`is:issue state:open`）必須維持英文，否則點擊篩選會失效。
|
||
3. **SPA 友善。** GitHub 用 Turbo/pushState，切頁不會重載腳本，需要自己監聽。
|
||
4. **效能優先。** 預編譯 regex、debounce、只處理必要節點。
|
||
|
||
## 架構概念
|
||
|
||
三層替換：
|
||
|
||
```
|
||
text
|
||
├─ TIME_AGO_REGEX "3 days ago" → "3 天前"
|
||
├─ WORD_BOUNDARY_REGEX 詞庫批次替換（長詞優先、大小寫不敏感）
|
||
└─ ABBREV_REGEX "62.8k" → "6.3 萬"
|
||
```
|
||
|
||
兩層跳過：
|
||
|
||
```
|
||
shouldSkipTextAncestor(el)
|
||
├─ SKIP_TAGS SCRIPT / STYLE / CODE / PRE / INPUT / TEXTAREA ...
|
||
├─ isContentEditable / role="textbox"
|
||
└─ SKIP_CONTEXT_SELECTOR closest() 快速判斷使用者內容脈絡
|
||
```
|
||
|
||
掃描策略：`TreeWalker` 走所有文字節點 + `querySelectorAll(ATTR_SELECTOR)` 補翻屬性。
|
||
|
||
## 版本演進
|
||
|
||
### v0.6（初版）
|
||
使用者提供，基本能翻導覽列。用 `setInterval(500ms)` 輪詢 + MutationObserver flag。
|
||
|
||
**問題：** 詞庫太少、每個詞跑一次 regex 效能差、沒處理 SPA。
|
||
|
||
### v0.7
|
||
- 擴充詞庫（Settings、Pulls、Commits、Branches…）
|
||
- 使用預編譯的 `WORD_BOUNDARY_REGEX` 一次替換
|
||
- 拿掉 setInterval 輪詢，改 MutationObserver + debounce
|
||
- Hook `pushState` / `replaceState`、監聽 `turbo:load`
|
||
|
||
### v0.8
|
||
**Bug：** `stars` / `watching` / `forks` 小寫沒被翻。
|
||
**原因：** regex 只有 `g` 沒 `i` 旗標。
|
||
**修：** 改 `gi`，搭配 `LOWER_MAP` 做大小寫不敏感查表。
|
||
|
||
**Bug：** `Security and quality` 變 `安全 and quality`。
|
||
**原因：** 只有 `Security` 在詞庫，`and quality` 不在。
|
||
**修：** 加整句 `Security and quality` → `安全與品質`。長詞優先排序會先吃掉整句。
|
||
|
||
### v0.9（數字格式化）
|
||
使用者要求「62.8k」改成更好看的格式。
|
||
|
||
新增 `formatAbbrev`：
|
||
- `≥ 1 萬` → `X.X 萬`（≥100 萬去掉小數）
|
||
- `< 1 萬` → 千分號 `7,800`
|
||
- 純數字不動
|
||
|
||
**額外問題：** `<strong>62.8k</strong>` 沒被掃到。
|
||
**原因：** SCAN_SELECTORS 沒包 `<strong>`。
|
||
**修：** 加入 `strong, b, em, h1-h4, li`。
|
||
|
||
### v0.10
|
||
**Bug：** 按鈕上的 `7.8k` / `62.8k`（在 `<span class="Counter">` 裡）沒格式化。
|
||
**原因：** `Counter` 在 skip 清單。
|
||
**修：** 移除 `Counter` skip。純數字本來就不會被誤翻，`k/M` 後綴才會處理。
|
||
|
||
### v0.11（分支頁）
|
||
Branches 頁大量詞彙沒翻：Default、Active、Stale、All、Updated、Check status、Behind、Ahead 等。
|
||
|
||
也加了相對時間 regex：
|
||
```js
|
||
TIME_AGO_REGEX = /\b(\d+)\s+(second|minute|hour|day|week|month|year)s?\s+ago\b/gi
|
||
```
|
||
|
||
**修 `Active 分支清單` 的半翻：** 把 `Branches` → `分支`（中文無複數差異），加整句 `Active branches` → `活躍分支`。
|
||
|
||
### v0.12（TreeWalker 重構）
|
||
**Bug：** `<th>` / `<td>` / `<relative-time>` 的文字沒翻，`<input>` 的 placeholder 也沒翻。
|
||
**原因：** SCAN_SELECTORS 白名單太窄；`<input>` 整個被 SKIP_TAGS 跳過，連屬性都沒碰。
|
||
|
||
**大改：**
|
||
1. 拿掉 SCAN_SELECTORS，改用 `TreeWalker` 走所有文字節點
|
||
2. 屬性翻譯獨立於文字節點跳過邏輯 — `<input>` 文字跳過但 placeholder 仍翻
|
||
3. `shouldSkipTextAncestor` 改成走 parent chain，比單一元素判斷更穩
|
||
|
||
### v0.13
|
||
補空狀態整句：`No branches match the search` → `沒有分支符合搜尋條件` 等。
|
||
|
||
**教訓：** 差點加了 `of` → `／共`，但 `of` 會破壞「Member of X」「out of」等句型，移除。同理 `Page`、`Showing` 也太通用不加。
|
||
|
||
### v0.14（使用者內容保護）
|
||
使用者抱怨檔名、commit 訊息、repo 描述被翻（`授權` / `自述檔.md` / `更新.sh` / `Initial 提交` / `全部 IN ONE Hacking Tool For Hackers`）。
|
||
|
||
**新增 `SKIP_CONTEXT_SELECTOR`：**
|
||
- 檔名：`.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`
|
||
- Topics：`a.topic-tag`
|
||
- README：`.markdown-body`
|
||
- 程式碼：`.blob-code-inner`、`.highlight`、`.react-code-lines`
|
||
- Issue / PR 標題：`.markdown-title`、`.js-issue-title`
|
||
|
||
用 `el.closest(SKIP_CONTEXT_SELECTOR)` 一次判斷祖先脈絡。
|
||
|
||
### v0.15（Issues 頁）
|
||
多個新問題：
|
||
1. `is:issue state:開啟中` — 搜尋語法被翻，**破壞功能**
|
||
2. `karanraza608-星標` — 使用者名稱被翻
|
||
3. 下拉選單沒翻（Sort by / Newest / Oldest…）
|
||
4. `read the 貢獻 guidelines` — 半翻
|
||
5. Dismiss / Want to contribute 沒翻
|
||
|
||
**新增跳過脈絡：**
|
||
- 使用者：`a[data-hovercard-type="user"|"organization"]`、`a[data-hovercard-url*="/users/"]`
|
||
- 搜尋：`[role="searchbox"]`、`[role="combobox"]`、語法 token `.pl-c1` 等
|
||
- Labels：`.IssueLabel`、`.Label`
|
||
|
||
**新增詞庫：** `Sort by` / `Order` / `Newest` / `Oldest` / `Created on` / `Last updated` / `Total comments` / `Best match` / `Reactions` / `Recently updated` / `Dismiss` / `Want to contribute to` / 整句 `If you have a bug or an idea, read the contributing guidelines before opening an issue`。
|
||
|
||
## 關鍵技術點
|
||
|
||
### 大小寫不敏感 + 保留原大小寫？
|
||
做不到。因為 `Open` (tab) 和 `opened` (issue meta 動詞) 經過 `gi` + LOWER_MAP 會用同一個翻譯。只能二選一。目前選「保留 tab 翻譯」，動詞保留英文。
|
||
|
||
### 長詞優先
|
||
```js
|
||
const sorted = [...TRANSLATION_MAP.keys()]
|
||
.sort((a, b) => b.length - a.length)
|
||
```
|
||
搭配 regex 的回溯（backtracking），長詞失敗時會嘗試短詞。讓「Active branches」整句優先於「Branches」單字。
|
||
|
||
### 屬性裡的 `...` 結尾
|
||
`Search branches...` 放進詞庫但 `\b...\b` 的尾端 `\b` 不會成立（`.` 是非字元 + 後方結尾也非字元）。解法是詞庫只放 `Search branches`，regex 會在 `\b` 前停下，保留後面的 `...`。
|
||
|
||
### React 元件的 key 變動
|
||
GitHub 的 React class 常含 hash（如 `SearchInput-module__searchInput_f5Xpk`）。不靠這些，改靠穩定的 `role`、`data-testid`、`data-hovercard-*`、`[href*="/blob/"]`。
|
||
|
||
## 目前已知限制
|
||
|
||
- **大小寫衝突**：同詞不同語境無法分別翻譯。
|
||
- **使用者自定 label / project 名稱**：會看內容決定，但已用 `.IssueLabel` / `.Label` 跳過彩色 label。
|
||
- **Issue 標題**：刻意保留英文（屬使用者內容）。
|
||
- **新 UI 改版**：如果 GitHub 改變 class / data-testid，跳過規則可能失效。
|
||
|
||
## 檔案
|
||
|
||
- `github-zh-tw.user.js` — 腳本本體
|
||
- `DEVELOPMENT.md` — 本文件
|
||
|
||
## 安裝
|
||
|
||
在 ScriptCat / Tampermonkey「新增腳本」，貼上 `github-zh-tw.user.js` 全文。或用「從本地檔案匯入」。
|