docs: 新增 README / QUICKSTART / SUMMARY 三份文件

三份文件定位不重疊:
- README.md:參考手冊(功能、架構、規則對照表、相容性)
- QUICKSTART.md:操作指南(安裝、自訂翻譯、自訂跳過、FAQ)
- SUMMARY.md:開發故事線(v0.6→v0.15 順序敘事、設計心得)
This commit is contained in:
2026-04-22 17:12:33 +08:00
parent 9ea401ac1d
commit 5d48265bb2
3 changed files with 439 additions and 0 deletions

139
QUICKSTART.md Normal file
View File

@@ -0,0 +1,139 @@
# 快速上手
## 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