Timmy
5d48265bb2
三份文件定位不重疊： - README.md：參考手冊（功能、架構、規則對照表、相容性） - QUICKSTART.md：操作指南（安裝、自訂翻譯、自訂跳過、FAQ） - SUMMARY.md：開發故事線（v0.6→v0.15 順序敘事、設計心得）
140 lines
4.2 KiB
Markdown
140 lines
4.2 KiB
Markdown
# 快速上手
|
||
|
||
## 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
|