自定义 DOM 规则

概述

Read Frog 允许你定义自定义 DOM 规则来控制特定网站上元素的翻译方式。这些规则在 dom-rules.ts 中定义,支持两种主要行为:

强制元素不翻译 - 跳过特定元素的翻译
强制块级翻译 - 让内联元素以块级元素的方式翻译(带换行)

配置文件位置

自定义规则定义在 extension 仓库中:

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
遵循贡献指南

查看代码贡献指南了解提交更改的更多详细信息。

自定义 DOM 规则

On this page