Read Frog Preload Configuration Options: Optimizing Translation Performance and Resource Usage

Read Frog's preload configuration options let you control how aggressively the extension pre-fetches translations through the margin (characters ahead to scan) and threshold (confidence level) settings, directly impacting perceived translation speed versus API usage and memory consumption.

Read Frog is an open-source browser extension that enhances reading by providing instant translations. The preload configuration options within the translation settings allow fine-grained control over how the extension prepares translation candidates before you actually request them. Understanding these settings helps you balance between instantaneous translation display and efficient resource utilization.

Understanding Preload Configuration Options in Read Frog

The preload mechanism works by scanning text ahead of your current viewport and preparing translation candidates in the background. This behavior is governed by the preload object located at translate.page.preload in the configuration hierarchy.

The Preload Object Structure

According to the Zod schema defined in src/types/config/translate.ts, the preload object contains two numeric properties:

Property	Meaning	Typical Range	Default
margin	Number of characters ahead of the current viewport to scan and prepare for translation	0 – 5000 characters	1000 (DEFAULT_PRELOAD_MARGIN)
threshold	Fraction (0 – 1) indicating the minimum confidence required before pre-loading a text segment	0 – 1	0 (DEFAULT_PRELOAD_THRESHOLD)

Default Values and Valid Ranges

The permissible ranges and defaults are declared as constants in src/utils/constants/translate.ts:

• MIN_PRELOAD_MARGIN = 0, MAX_PRELOAD_MARGIN = 5000
• DEFAULT_PRELOAD_MARGIN = 1000
• MIN_PRELOAD_THRESHOLD = 0, MAX_PRELOAD_THRESHOLD = 1
• DEFAULT_PRELOAD_THRESHOLD = 0

These constraints are enforced by the UI component in src/entrypoints/options/pages/translation/preload-config.tsx, which validates user input against these constants before persisting changes to the Jotai atom configFieldsAtomMap.translate.

How Preload Configuration Options Impact Translation Performance

The two preload settings create a direct trade-off between responsiveness and resource consumption.

Margin: Balancing Preemptive Translation and Resource Usage

The margin setting determines how far ahead of your current reading position the extension actively scans.

• Higher margin (e.g., 3000–5000): Creates more pre-translation tasks in the background. When you scroll into the pre-loaded region, translations appear instantly, significantly improving UI responsiveness. However, each extra character increases the request payload and may trigger additional API calls (particularly problematic with providers that impose per-request limits). This raises CPU usage, memory consumption for storing pending translation jobs, and network bandwidth.

• Lower margin (e.g., 0–200): Minimizes background activity. Translations occur on-demand as you encounter text, conserving resources but potentially introducing slight delays when scrolling quickly through content.

Threshold: Controlling Translation Confidence and API Calls

The threshold setting acts as a confidence filter for the pre-loader.

• Lower threshold (e.g., 0–0.2): Instructs the engine to accept lower-certainty matches, causing the pre-loader to fire on more text fragments. This yields a denser pre-translation cache, reducing latency but increasing API traffic and potentially introducing noisier translations.

• Higher threshold (e.g., 0.8–1.0): Restricts pre-loading to only the most confident segments, conserving API quota and reducing background work. Users may notice a short delay when reaching new content that doesn't meet the confidence criteria.

Configuring Preload Options in Read Frog

You can adjust these settings programmatically or through the extension's options UI.

Programmatic Configuration

For advanced users or migration scripts, you can construct a complete translation configuration object using the Zod schema. The migration script src/utils/config/migration-scripts/v035-to-v036.ts demonstrates how the preload block was added to existing user configs during a version upgrade.

Here is an example of configuring custom preload values:

import { translateConfigSchema } from '@/types/config/translate';

// Example of a full TranslateConfig object with custom preload values
const myTranslateConfig = translateConfigSchema.parse({
  providerId: 'deeplx',
  mode: 'bilingual',
  node: { enabled: true, hotkey: 'alt' },
  page: {
    range: 'all',
    autoTranslatePatterns: [],
    autoTranslateLanguages: [],
    shortcut: ['alt', 'e'],
    enableLLMDetection: false,
    preload: {
      margin: 2500,          // pre-load 2.5k characters ahead
      threshold: 0.15,       // accept lower-confidence matches
    },
    minCharactersPerNode: 0,
    minWordsPerNode: 0,
    skipLanguages: [],
    enableSkipLanguagesLLMDetection: false,
  },
  enableAIContentAware: false,
  customPromptsConfig: { promptId: null, patterns: [] },
  requestQueueConfig: { capacity: 60, rate: 8 },
  batchQueueConfig: { maxCharactersPerBatch: 1000, maxItemsPerBatch: 4 },
  translationNodeStyle: {
    preset: 'default',
    isCustom: false,
    customCSS: null,
  },
});

UI-Based Configuration

The options page exposes these settings through the PreloadNumberSelector component rendered in src/entrypoints/options/pages/translation/preload-config.tsx. This component provides two number inputs bound to the margin and threshold properties, enforcing the min/max limits defined in the constants file.

<PreloadNumberSelector property="margin" />
<PreloadNumberSelector property="threshold" />

Changes update the Jotai atom configFieldsAtomMap.translate, which persists to extension storage.

Resource Usage Trade-offs and Optimization Strategies

Selecting the right combination of margin and threshold depends on your hardware capabilities and API plan limits.

Scenario	Margin	Threshold	Expected Outcome
Speed-first (high-end PC, generous API quota)	3000 – 5000	0 – 0.2	Near-instant translation as you scroll, but higher CPU/Memory usage and more network requests.
Balanced (average device, limited quota)	800 – 1200 (default)	0.3 – 0.5	Acceptable latency with modest background load.
Conservative (low-end device or strict quota)	0 – 200	0.8 – 1.0	Minimal background activity; translations happen on-demand, conserving resources.

Fine-tuning these settings allows you to tailor Read Frog to your specific environment, ensuring smooth performance without exhausting system resources or API limits.

Summary

• Read Frog's preload configuration options (translate.page.preload) control how aggressively the extension prepares translations before you request them.
• The margin setting (0–5000 characters, default 1000) determines how far ahead of the viewport to scan; higher values improve responsiveness but increase CPU, memory, and network usage.
• The threshold setting (0–1, default 0) filters pre-loading by confidence; lower values cache more content aggressively, while higher values conserve API quota.
• Configuration is validated through Zod schemas in src/types/config/translate.ts and enforced in the UI component src/entrypoints/options/pages/translation/preload-config.tsx.
• Choose settings based on your hardware capabilities and API plan: high margins for speed on powerful machines, conservative settings for resource-constrained environments.

Frequently Asked Questions

What is the default preload margin in Read Frog?

The default preload margin is 1000 characters, defined as DEFAULT_PRELOAD_MARGIN in src/utils/constants/translate.ts. This means the extension prepares translations for text up to 1000 characters ahead of your current viewport position by default.

How does the preload threshold affect API usage?

The preload threshold acts as a confidence filter. A lower threshold (closer to 0) causes the extension to pre-load more text fragments, including lower-confidence matches, which increases API call volume. A higher threshold (closer to 1) restricts pre-loading to high-confidence segments only, significantly conserving API quota and reducing background network activity.

Can I disable preloading entirely in Read Frog?

Yes, you can effectively disable preloading by setting the margin to 0. This prevents the extension from scanning ahead of the viewport, meaning all translations occur on-demand when you interact with text. However, there is no single "disable" boolean; you achieve this by configuring the margin and threshold to minimal values (margin: 0, threshold: 1).

Where are the preload configuration limits defined in the source code?

The numeric limits and default values for preload settings are defined in src/utils/constants/translate.ts. This file exports constants such as MIN_PRELOAD_MARGIN (0), MAX_PRELOAD_MARGIN (5000), DEFAULT_PRELOAD_MARGIN (1000), and the corresponding threshold constants. The Zod schema that validates these values resides in src/types/config/translate.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}