自訂 DOM 規則

概述

Read Frog 讓你定義自訂 DOM 規則來控制特定網站上元素的翻譯方式。這些規則在 dom-rules.ts 中定義,支持兩種主要行為:

強制元素不翻譯 - 跳過特定元素的翻譯
強制區塊級翻譯 - 讓內嵌元素以區塊級元素的方式翻譯(帶換行)

設定檔位置

src/utils/constants/dom-rules.ts

可用規則類型

1. 自訂不遍歷元素選擇器

使用 CUSTOM_DONT_WALK_INTO_ELEMENT_SELECTOR_MAP 來阻止特定網域上某些元素的翻譯。

語法:

export const CUSTOM_DONT_WALK_INTO_ELEMENT_SELECTOR_MAP: Record<string, string[]> = {
  "example.com": [".selector-1", "#element-id", "custom-element > *"],
};

範例:

export const CUSTOM_DONT_WALK_INTO_ELEMENT_SELECTOR_MAP: Record<string, string[]> = {
  "chatgpt.com": [".ProseMirror"],
  "arxiv.org": [".ltx_listing"],
  "www.reddit.com": [
    "faceplate-screen-reader-content > *",
    "reddit-header-large *",
    "shreddit-comment-action-row > *",
  ],
  "www.youtube.com": [
    "#masthead-container *",
    "#guide-inner-content *",
    "#metadata *",
    "#channel-name",
    ".translate-button",
    ".yt-lockup-metadata-view-model__metadata",
    ".yt-spec-avatar-shape__badge-text",
    ".shortsLockupViewModelHostOutsideMetadataSubhead",
    "ytd-comments-header-renderer",
    "#top-row",
    "#header-author",
    "#reply-button-end",
    "#more-replies",
    "#info",
    "#badges *",
  ],
};

使用場景:

跳過導覽選單和頁頭
排除互動式 UI 元素
防止翻譯程式碼編輯器或技術內容
避免翻譯元資料部分

2. 自訂強制區塊級翻譯選擇器

使用 CUSTOM_FORCE_BLOCK_TRANSLATION_SELECTOR_MAP 強制內嵌元素以區塊級元素的方式翻譯(帶換行)。

語法:

export const CUSTOM_FORCE_BLOCK_TRANSLATION_SELECTOR_MAP: Record<string, string[]> = {
  "example.com": [".force-block-selector"],
};

範例:

export const CUSTOM_FORCE_BLOCK_TRANSLATION_SELECTOR_MAP: Record<string, string[]> = {
  "github.com": [".react-directory-row-commit-cell *"],
};

使用場景:

強制提交資訊顯示在單獨的行上
確保列表項目單獨翻譯
透過分割密集的內嵌內容來提高可讀性

如何新增自訂規則

步驟 1: 確定網站域名

使用瀏覽器網址列中顯示的準確網域:

對於 https://example.com 使用 'example.com'
對於 https://www.example.com 使用 'www.example.com'

步驟 2: 尋找元素選擇器

使用瀏覽器開發者工具尋找 CSS 選擇器:

打開網站
右鍵點選要定位的元素
選擇"檢查"或"檢查元素"
在開發者工具中右鍵點選 HTML 元素
複製選擇器(CSS Selector 或建立自己的選擇器)

步驟 3: 新增規則到配置

開啟 dom-rules.ts 並加入你的規則:

export const CUSTOM_DONT_WALK_INTO_ELEMENT_SELECTOR_MAP: Record<string, string[]> = {
  // ... 现有规则 ...
  "your-website.com": [".header-navigation", "#sidebar-menu", ".code-block"],
};

步驟 4: 測試你的規則

運行開發伺服器:
```
pnpm dev
```
導航到網站
驗證元素是否正確處理
根據需要調整選擇器

最佳實踐

選擇器特異性

足夠具體 以僅定位預期的元素
避免過於寬泛的選擇器 如單獨的 * 或 div
使用類別名稱、ID 或元素組合

性能考慮

保持選擇器數量合理
在實際頁面上測試以確保效能可接受
當簡單選擇器可以工作時,避免複雜的後代選擇器

可維護性

將相關選擇器分組在一起
加入註解解釋為什麼需要這些規則
盡可能使用有意義的選擇器名稱

常見模式

排除導航元素

'example.com': [
  'nav *',
  'header *',
  '.navigation',
]

排除互動式 UI

'example.com': [
  'button',
  'input',
  'select',
  '.modal',
  '.dropdown',
]

排除技術內容

'example.com': [
  'pre',
  'code',
  '.code-block',
  '.terminal',
]

全域 DOM 規則

除了自訂規則外,Read Frog 還有幾個適用於所有網站的全域規則:

強制區塊級標籤

始終被視為區塊級元素的標籤:

export const FORCE_BLOCK_TAGS = new Set([
  "BODY",
  "H1",
  "H2",
  "H3",
  "H4",
  "H5",
  "H6",
  "BR",
  "FORM",
  "SELECT",
  "BUTTON",
  "LABEL",
  "UL",
  "OL",
  "LI",
  "BLOCKQUOTE",
  "PRE",
  "ARTICLE",
  "SECTION",
  "FIGURE",
  "FIGCAPTION",
  "HEADER",
  "FOOTER",
  "MAIN",
  "NAV",
]);

不遍歷和翻譯的標籤

永遠不會被遍歷進行翻譯的元素:

export const DONT_WALK_AND_TRANSLATE_TAGS = new Set([
  "HEAD",
  "TITLE",
  "HR",
  "INPUT",
  "TEXTAREA",
  "IMG",
  "VIDEO",
  "AUDIO",
  "CANVAS",
  "SOURCE",
  "TRACK",
  "META",
  "SCRIPT",
  "NOSCRIPT",
  "STYLE",
  "LINK",
  "PRE",
  "svg",
  ...MATH_TAGS,
]);

故障排除

規則不起作用

檢查域名拼字 - 確保域名完全匹配
驗證選擇器語法 - 在瀏覽器開發者工具控制台中測試選擇器
清除快取 - 重新載入擴充功能並重新整理頁面
檢查選擇器特異性 - 元素可能被更具體的規則匹配

元素仍在翻譯

檢查元素是否為被排除元素的子元素
驗證選擇器是否定位到正確的元素
尋找頁面載入後動態載入的元素

翻譯破壞頁面佈局

謹慎使用強制塊級規則
在同一網站的多個頁面上測試
考慮使用 !translate 規則而不是強制區塊級

貢獻自訂規則

如果你創建了對其他人有益的規則,請考慮貢獻它們:

在多個頁面上徹底測試
記錄為什麼需要這些規則
提交包含你的變更的 Pull Request
遵循贡献指南

查看代码贡献指南以了解提交更改的更多詳細資訊。

On this page