Site Control & Site Rules

Read Frog has two website controls with different purposes:

Use Site Control for permission-like policy. Use Site Rules when Read Frog runs but chooses the wrong nodes, breaks inline text, translates code, or needs site-specific CSS.

General Site Control

Blacklist mode runs Read Frog everywhere except listed hosts. Whitelist mode runs it only on listed hosts. Hostname matching is exact or by subdomain: example.com also matches news.example.com, but it does not accept a URL path or wildcard syntax.

This hostname-only format is also used by Translation's Auto Translate Websites and Never Auto Translate Websites lists. Never-auto affects automatic startup; General Site Control decides whether the extension runs at all.

Site Rule URL patterns

Site Rules support richer URL patterns. Query strings are ignored during matching.

Schemes may be http, https, or *. Explicit ports are rejected. Put exclusions in excludeMatches when a broad rule should skip a section of a site.

How matching rules combine

Read Frog applies all matching enabled built-in rules first, then all matching enabled user rules. You can disable a built-in rule by its ID.

• Selector lists are processed in order through their base, .add, and .remove fields.
• minCharacters and minWords are scalar values; the last matching value wins.
• injectedCss and injectedCss.add are concatenated in matching order.
• A malformed URL pattern or selector is ignored and reported as a warning instead of being executed.

This means a user rule normally has the final say, but arrays are not simply replaced. Use .remove to undo a selector introduced by an earlier rule and .add to extend it.

Available fields

Every rule needs a unique id and matches. The editor accepts an object or array of objects; using an array is convenient for export and review.

Selector collections also support .add and .remove, such as excludeSelectors.add and excludeSelectors.remove.

Safe example

Start with one narrow hostname, a few familiar selectors, and scoped CSS:

[
  {
    "id": "example-docs",
    "description": "Translate article copy but leave navigation and code untouched.",
    "matches": ["docs.example.com/*"],
    "excludeSelectors": [
      "nav",
      "pre",
      "code",
      "[aria-label='Breadcrumb']"
    ],
    "includeSelectors": ["main article"],
    "forceBlockSelectors": ["article p", "article li"],
    "preserveTextSelectors": [".product-name", ".command-name"],
    "minCharacters": 2,
    "minWords": 1,
    "injectedCss": ".read-frog-translated-content-wrapper { max-width: 100%; }"
  }
]

Save, reload one matching page, and inspect the result before broadening the pattern. Prefer CSS classes or semantic attributes that are stable across page loads. Generated class names often change after a deployment.

Adjusting an earlier rule

To extend or undo selector decisions from a matching built-in rule, add a later user rule:

[
  {
    "id": "example-docs-adjustment",
    "matches": ["docs.example.com/*"],
    "excludeSelectors.add": [".sidebar-ad"],
    "excludeSelectors.remove": [".article-summary"],
    "forceInlineSelectors.add": [".term-with-tooltip"]
  }
]

This keeps the rest of the built-in rule while changing only the listed selectors. If the whole built-in rule is wrong, disable it instead of recreating every field.

Validation and limits

The editor validates JSON syntax, schema, duplicate IDs, selector and pattern syntax, rule count, and size before saving. Current limits are 200 user rules, 65,536 characters for the JSON document, and 8,192 characters for each CSS value.

Debugging checklist

1. Confirm General Site Control allows the hostname.
2. Confirm the rule is enabled and its matches pattern covers the current path.
3. Check excludeMatches and any disabled built-in rule.
4. Test selectors in the browser inspector against the current DOM.
5. Remove half the rule temporarily to isolate a selector, threshold, or CSS issue.
6. Reload the page after saving; already-processed nodes may retain the previous result.