自定义 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