Compare commits
2 Commits
5d48265bb2
...
36cd2df55d
| Author | SHA1 | Date | |
|---|---|---|---|
| 36cd2df55d | |||
| d23dda03a9 |
68
CLAUDE.md
Normal file
68
CLAUDE.md
Normal file
@@ -0,0 +1,68 @@
|
|||||||
|
# CLAUDE.md
|
||||||
|
|
||||||
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||||
|
|
||||||
|
## 專案性質
|
||||||
|
|
||||||
|
單一檔案 UserScript(ScriptCat / Tampermonkey),把 GitHub 介面翻成台灣繁體中文。全部邏輯在 `github-zh-tw.user.js`,**沒有** package.json、建置腳本、測試套件、lint 設定、相依套件。
|
||||||
|
|
||||||
|
## 開發流程
|
||||||
|
|
||||||
|
改 `github-zh-tw.user.js` 後:
|
||||||
|
|
||||||
|
1. **驗證只能手動**:在瀏覽器裝 ScriptCat/Tampermonkey,把整份檔案貼進「新增腳本」,存檔後強制重載 `https://github.com/*` 驗結果。沒有自動化測試可跑。
|
||||||
|
2. **發版**:改內容時同時修腳本檔開頭 `@version`(UserScript header 用這個判斷更新)。`DEVELOPMENT.md` 記錄了每個版本的改動脈絡,重大改動順手補一段。
|
||||||
|
3. **不要**建立 `package.json` / 加 build 工具 / 加 npm 相依。檔案必須保持能直接貼進 Tampermonkey 就跑。
|
||||||
|
|
||||||
|
## 核心架構(動一行詞庫前先讀完)
|
||||||
|
|
||||||
|
所有邏輯在 IIFE 內,四個關鍵結構:
|
||||||
|
|
||||||
|
1. **`TRANSLATION_MAP`**(`Map`)— 英→中詞庫,按語意分類排列。建構時會依字串長度排序成 `WORD_BOUNDARY_REGEX`,**長詞優先**匹配。
|
||||||
|
2. **`LOWER_MAP`** — 小寫鍵的查表。regex 用 `gi` 旗標(大小寫不敏感)匹配後,以小寫查譯文。
|
||||||
|
3. **`SKIP_CONTEXT_SELECTOR`** — 使用者內容脈絡白名單(檔名、commit 訊息、repo 描述、Topics、README、程式碼、Issue/PR 標題、使用者名稱、搜尋框語法…)。`shouldSkipTextAncestor` 用 `el.closest(...)` 判斷祖先是否落在這些 selector。
|
||||||
|
4. **`SKIP_TAGS`** — `SCRIPT/STYLE/CODE/PRE/INPUT/TEXTAREA/NOSCRIPT`。文字節點跳過,但**屬性仍會翻**(`<input placeholder>` 會翻,輸入內容不動)。
|
||||||
|
|
||||||
|
### 替換流程(`replaceText` 三層,順序不可交換)
|
||||||
|
|
||||||
|
```
|
||||||
|
TIME_AGO_REGEX "3 days ago" → "3 天前" ← 先跑,避免 days 被當詞庫吃掉
|
||||||
|
WORD_BOUNDARY_REGEX 詞庫整批替換 ← 長詞優先
|
||||||
|
ABBREV_REGEX "62.8k" → "6.3 萬" ← 最後,避開 k/M 在詞庫中撞到
|
||||||
|
```
|
||||||
|
|
||||||
|
### 掃描策略
|
||||||
|
|
||||||
|
- 文字節點:`TreeWalker(SHOW_TEXT)` 走全部,靠 `shouldSkipTextAncestor` 剔除。**不用** SCAN 白名單(v0.12 拿掉了,白名單會漏 `<th>`/`<td>`/`<relative-time>` 等)。
|
||||||
|
- 屬性:`querySelectorAll(ATTR_SELECTOR)` — 翻 `data-content` / `aria-label` / `title` / `placeholder`。
|
||||||
|
- SPA:MutationObserver(`childList` + `attributes`)+ hook `pushState`/`replaceState` + `popstate` + `turbo:load`/`turbo:render`,所有 trigger 都走同一個 150ms debounce 後做全域 re-scan。
|
||||||
|
|
||||||
|
## 修改詞庫的不變條件
|
||||||
|
|
||||||
|
這些規則是踩過坑才定的(`DEVELOPMENT.md` 有血淚史),動之前先確認新需求不會撞到:
|
||||||
|
|
||||||
|
- **整句優先於單字**。要譯 `Active branches` 就加整句,不要靠 `Active` + `branches` 組合(長詞優先 regex 會整句吃掉,否則會出現「Active 分支」這種半翻)。
|
||||||
|
- **一個英文詞只能一個翻譯**。因為 `gi` + `LOWER_MAP`,`Open`(tab)和 `opened`(動詞)共用同一譯文。取捨原則:保頻率高的那個;另一個保留英文。
|
||||||
|
- **搜尋語法不可翻**。`is:issue state:open` 這類 token 翻掉會破壞搜尋。靠 `[role="searchbox"]` / `[role="combobox"]` / `.pl-c1` 等 skip selector 擋下。加新詞時確認不會污染搜尋框。
|
||||||
|
- **使用者內容不可翻**。檔名、commit 訊息、Issue 標題、Repo 描述、Topics、使用者名稱、README、程式碼。遇到誤翻時,**加 skip selector** 而不是從詞庫拔詞。
|
||||||
|
- **React class 不可靠**。GitHub 新 UI 的 class 帶 hash(`SearchInput-module__xxx_f5Xpk`)會變。一律用穩定的 `role` / `data-testid` / `data-hovercard-*` / `[href*="/blob/"]` 這類語意屬性。
|
||||||
|
- **詞庫條目不要帶結尾標點**。`Search branches...` 結尾 `.` 會讓 `\b` 尾界失敗。詞庫只放 `Search branches`,regex 在 `\b` 前停下自然保留原 `...`。
|
||||||
|
- **避免太通用的短詞**。`of`、`Page`、`Showing` 這類會打穿「Member of X」「out of」等片語,不要進詞庫。
|
||||||
|
|
||||||
|
## 數字格式化(`formatAbbrev`)
|
||||||
|
|
||||||
|
```
|
||||||
|
val ≥ 1,000,000 → "X 萬"(≥100 萬整數;否則 1 位小數)
|
||||||
|
1,000,000 > val ≥ 10,000 → "X.X 萬"(`.0` 去掉)
|
||||||
|
val < 10,000 → "X,XXX" 千分號
|
||||||
|
無 k/M 後綴的純整數 → 不動
|
||||||
|
```
|
||||||
|
|
||||||
|
## 回報問題時要怎麼處理
|
||||||
|
|
||||||
|
使用者反映「某某沒翻」或「某某誤翻」時,先分類:
|
||||||
|
|
||||||
|
- **沒翻** → 加詞庫。先確認在哪個語意分類、是否該加整句以免半翻。
|
||||||
|
- **誤翻使用者內容**(檔名、commit 訊息、使用者名、repo 描述…)→ 加 `SKIP_CONTEXT_SELECTOR`,別動詞庫。用 DevTools 找穩定的 selector(`data-testid` / `role` / `href` pattern)。
|
||||||
|
- **誤翻搜尋語法/程式碼** → 加 skip selector,動詞庫不能解。
|
||||||
|
- **半翻**(「Active 分支清單」)→ 補整句進詞庫,利用長詞優先規則蓋過去。
|
||||||
@@ -1,7 +1,7 @@
|
|||||||
// ==UserScript==
|
// ==UserScript==
|
||||||
// @name GitHub 中文化 (繁體)
|
// @name GitHub 中文化 (繁體)
|
||||||
// @namespace https://github.com/scriptscat/scriptcat
|
// @namespace https://github.com/scriptscat/scriptcat
|
||||||
// @version 0.15
|
// @version 0.17
|
||||||
// @description 幫 GitHub 導覽列、按鈕、屬性換成繁體中文,支援 SPA 動態更新,不亂翻、不卡頓。
|
// @description 幫 GitHub 導覽列、按鈕、屬性換成繁體中文,支援 SPA 動態更新,不亂翻、不卡頓。
|
||||||
// @match https://github.com/*
|
// @match https://github.com/*
|
||||||
// @run-at document-idle
|
// @run-at document-idle
|
||||||
@@ -135,6 +135,11 @@
|
|||||||
// PR / Issue 常見按鈕
|
// PR / Issue 常見按鈕
|
||||||
['New issue', '開新問題'],
|
['New issue', '開新問題'],
|
||||||
['New pull request', '開新拉取請求'],
|
['New pull request', '開新拉取請求'],
|
||||||
|
['New repository', '新增倉庫'],
|
||||||
|
['Import repository', '匯入倉庫'],
|
||||||
|
['New codespace', '新增 codespace'],
|
||||||
|
['New gist', '新增 gist'],
|
||||||
|
['New organization', '新增組織'],
|
||||||
['Compare', '比較'],
|
['Compare', '比較'],
|
||||||
['Merge', '合併'],
|
['Merge', '合併'],
|
||||||
['Merge pull request', '合併拉取請求'],
|
['Merge pull request', '合併拉取請求'],
|
||||||
@@ -185,6 +190,14 @@
|
|||||||
['Everyone', '所有人'],
|
['Everyone', '所有人'],
|
||||||
['Anyone', '任何人'],
|
['Anyone', '任何人'],
|
||||||
|
|
||||||
|
// Copilot / 搜尋框
|
||||||
|
['Ask Copilot', '詢問 Copilot'],
|
||||||
|
['About this page', '關於此頁'],
|
||||||
|
['In a space', '在 Space 中'],
|
||||||
|
['Download for', '下載'],
|
||||||
|
['Type', '輸入'],
|
||||||
|
['to search', '搜尋'],
|
||||||
|
|
||||||
// 全站導覽 / 使用者選單
|
// 全站導覽 / 使用者選單
|
||||||
['Pull', '拉取'],
|
['Pull', '拉取'],
|
||||||
['Marketplace', '市集'],
|
['Marketplace', '市集'],
|
||||||
@@ -278,6 +291,9 @@
|
|||||||
'[itemprop="about"]',
|
'[itemprop="about"]',
|
||||||
'.BorderGrid-cell > p',
|
'.BorderGrid-cell > p',
|
||||||
'.f4.my-3',
|
'.f4.my-3',
|
||||||
|
// 2026 新版 React UI:描述 <p class="f4 tmp-my-3"> 包在 .hide-sm.hide-md 裡,原 `> p` 直接子代選擇器失效。
|
||||||
|
// 用 p.f4 靠語意(f4 = 大型段落文字 = prose 描述),對未來 tmp-* 類別變動有抵抗力。
|
||||||
|
'p.f4',
|
||||||
// Topics 標籤
|
// Topics 標籤
|
||||||
'a.topic-tag',
|
'a.topic-tag',
|
||||||
'.topic-tag',
|
'.topic-tag',
|
||||||
|
|||||||
Reference in New Issue
Block a user