docs: 新增 README / QUICKSTART / SUMMARY 三份文件
三份文件定位不重疊: - README.md:參考手冊(功能、架構、規則對照表、相容性) - QUICKSTART.md:操作指南(安裝、自訂翻譯、自訂跳過、FAQ) - SUMMARY.md:開發故事線(v0.6→v0.15 順序敘事、設計心得)
This commit is contained in:
139
QUICKSTART.md
Normal file
139
QUICKSTART.md
Normal 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
|
||||
Reference in New Issue
Block a user