自訂 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