# Account and Plans (/en/docs/account-and-plans)



Translation does not need an account. Install the extension, pick a provider, and read — nothing on this page is required for that.

An account exists for the parts that have to live on a server: your [Notebase](/docs/notebase), your review schedule, your statistics, and anything an assistant reaches over [MCP](/docs/mcp).

## What an account adds [#what-an-account-adds]

|                                                 | Without an account    | Signed in              |
| ----------------------------------------------- | --------------------- | ---------------------- |
| Page, selection, input and subtitle translation | Yes                   | Yes                    |
| Your own API keys                               | Yes                   | Yes                    |
| Glossary, custom prompts, custom CSS            | Yes                   | Yes                    |
| Built-in AI, for Custom AI Actions              | Small daily allowance | Larger daily allowance |
| Notebase, card templates, review, statistics    | No                    | Yes                    |
| MCP                                             | No                    | Ultra only             |

Everything in the first three rows is stored in your browser profile, which is why it works signed out — and why it does not follow you to another computer unless you sync it yourself. See [Configuration, Sync & Backups](/docs/config-backup).

## The built-in AI allowance [#the-built-in-ai-allowance]

Read Frog ships two providers of its own — **Built-in AI** and **Advanced Built-in AI**, the second using a stronger model. Both draw on an allowance rather than an API key of yours.

**Below Ultra, that allowance funds Custom AI Actions and nothing else.** Page translation, selection translation, note suggestions, video subtitles, input translation and language detection are all deliberately unfunded on the free and Pro tiers — Read Frog reports them as needing an upgrade rather than as being out of quota. Ultra funds every one of them from a single weekly pool.

|                 | Custom AI Actions                            | Everything else  |
| --------------- | -------------------------------------------- | ---------------- |
| Not signed in   | Small daily allowance, keyed to your network | Not funded       |
| Signed in, free | Larger daily allowance                       | Not funded       |
| Pro             | Larger daily allowance again                 | Not funded       |
| Ultra           | One weekly pool                              | Same weekly pool |

So on any plan below Ultra, **whole-page translation runs on a provider of your own**, which is the normal way to use Read Frog: Google Translate and Microsoft Translator need no key at all, and an LLM provider needs yours. Assigning your own provider to a feature in [API Providers](/docs/providers/overview) stops it drawing on the allowance entirely — **your own API key has no Read Frog limit**, only whatever your provider charges you.

Daily allowances reset each UTC day. The Ultra pool is a rolling week anchored to your subscription rather than a calendar week, so a heavy reading day is not capped by that day alone. Because it is one pool, video subtitles — by far the most expensive feature per minute of use — share it with everything else.

## What the paid plans unlock [#what-the-paid-plans-unlock]

Current prices are on the [pricing page](https://readfrog.app/pricing); they are not repeated here so this page cannot go stale. What the tiers change:

* **Pro** raises the Custom AI Actions allowance and includes the AI subtitles quota described in [AI Segmentation and Subtitles Quota](/docs/video-subtitles/ai-segmentation).
* **Ultra** is the only plan whose allowance funds anything beyond Custom AI Actions, and the only one that can connect an AI assistant over [MCP](/docs/mcp). That restriction is enforced on the server, so an assistant on a lower plan is refused at connection time rather than failing later.

## Signing in [#signing-in]

Sign in from the extension popup or at [readfrog.app](https://readfrog.app); it is the same account either way, and the extension picks up the session from the website. If the popup still shows **Guest** after signing in on the website, reload the page you are on — the extension reads the session when a tab loads.

## Deleting your account [#deleting-your-account]

Account deletion is available from the account settings on the website and removes your notes, cards and review history. It is not reversible, and it does not uninstall the extension or clear the settings stored in your browser profile — do that from the browser's extensions page.


# Configuration, Sync & Backups (/en/docs/config-backup)







Open **Options → Config** to move or recover settings. Interface language is configured separately under **Options → General**.

## Export safely [#export-safely]

The export dialog lets you include or exclude provider API keys. Exclude keys for normal backups, bug reports, shared files, and version control. Include them only when moving your own configuration through storage you trust.

<Callout type="warn">
  An export containing API keys is a credential file. Anyone who obtains it may be able to spend
  your provider quota or access your account.
</Callout>

## Import and validation [#import-and-validation]

Read Frog validates and migrates imported configuration before applying it. It also creates a backup of the current configuration first, so you can restore if the imported settings are valid but unsuitable.

Importing replaces many current values. Review providers, target language, Site Control, and per-tool disabled websites afterward—especially when the file came from another browser profile.

## Google Drive manual sync [#google-drive-manual-sync]

Connect Google Drive from the Config page, then start sync manually when you want to exchange settings with another browser.

<img alt="Google Drive sync controls in Read Frog settings" src="__img0" />

If only one side changed, Read Frog can use the newer copy. If both local and remote values changed, the conflict dialog lets you choose local or remote values per field, or select all local/all remote before confirming.

<img alt="Choosing local or remote settings during a Google Drive conflict" src="__img1" />

Validate the merged configuration in the dialog before applying it. Manual sync avoids silent background overwrites, but it also means changes do not appear on another device until you start sync there.

## Automatic and manual backups [#automatic-and-manual-backups]

Read Frog checks for changed configuration about every 60 minutes and creates an automatic backup only when something changed. It keeps up to eight backups. You can also:

* create a manual backup before an experiment;
* restore a selected backup;
* export a backup to a file;
* delete backups you no longer need.

Backups are local to the browser profile unless you export or sync them. Before editing large Site Rules or prompt sets, make a manual backup with a recognizable timestamp.

## Interface language [#interface-language]

**Options → General → Interface Language** controls the Read Frog UI independently from the browser's display language. Changing it does not change translation source/target languages or website language detection.

## Beta Experience and reset [#beta-experience-and-reset]

Beta Experience enables experimental features that explicitly depend on it. Text to Speech is labeled Public Beta but no longer requires this switch.

Reset restores the default configuration. It is appropriate when a migrated or heavily edited setup cannot be repaired, but it removes customized providers, prompts, rules, and tool choices. Export without keys for support, and create a secure backup if you need credentials, before resetting.

## Recovery sequence [#recovery-sequence]

When a configuration change causes a problem:

1. export the current state without API keys for inspection;
2. restore the most recent known-good local backup;
3. if necessary, import a trusted export;
4. reconnect Google Drive and resolve conflicts deliberately;
5. use Reset only after the earlier recovery paths fail.

This order preserves the most evidence and gives you the easiest route back.


# Contribution Guide (/en/docs/contributing)







## Getting Started [#getting-started]

### Step 1: Fork the repository and clone it to your local machine [#step-1-fork-the-repository-and-clone-it-to-your-local-machine]

```bash
# Clone the repository from your fork
git clone https://github.com/xxxxx/read-frog.git

# Enter the project directory
cd read-frog

# Add the upstream remote to sync with the original repository
git remote add upstream https://github.com/mengxi-ream/read-frog.git
```

### Step 2: Install dependencies and start development [#step-2-install-dependencies-and-start-development]

```bash
# Install dependencies
pnpm i

# Start the development server
pnpm dev
```

This will start the extension development environment. The extension will automatically open in your default browser.

## Development Tips [#development-tips]

### Using npx with pnpm Node.js Management [#using-npx-with-pnpm-nodejs-management]

We're using pnpm's built-in Node.js version management (introduced in pnpm 10.14). You may encounter `EBADDEVENGINES` errors when running `npx` commands. There are two solutions:

**Solution 1: Use `pnpm dlx` or `pnpx` instead of `npx`**

```bash
# Instead of npx
npx some-package@latest

# Use pnpm dlx
pnpm dlx some-package@latest

# Or use pnpx (alias for pnpm dlx)
pnpx some-package@latest
```

**Solution 2: Align Node.js version with pnpm**

When it's not convenient to replace `npx` (e.g., for user-scoped MCP installations in Claude Code), align your Node.js version:

```bash
# Install and use the required Node.js version globally
pnpm env use --global 22.18.0
```

### Open the extension in the specific browser [#open-the-extension-in-the-specific-browser]

You can create/modify the `web-ext.config.ts` file in the root directory to explicitly specify the browser path.

```javascript
// web-ext.config.ts
import { defineWebExtConfig } from "wxt";

export default defineWebExtConfig({
  binaries: {
    chrome: "path/to/your/chrome.exe",
    firefox: "path/to/your/firefox.exe",
    edge: "path/to/your/edge.exe",
  },
});
```

### pnpm dev can't load the extension automatically [#pnpm-dev-cant-load-the-extension-automatically]

If you use Chrome version 137 or higher, you need to download [Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing/) for development. See [details](https://wxt.dev/guide/essentials/config/browser-startup.html).

### Persistent Chrome Profile [#persistent-chrome-profile]

**By default, web-ext creates a new profile every time you run the dev script.**

If you want to keep logins, devtools extensions, and browser settings between development sessions, create or update `web-ext.config.ts` in the project root.

The persistent profile configuration is slightly different across operating systems:

<CodeBlockTabs defaultValue="macOS/Linux">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="macOS/Linux">
      macOS/Linux
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Windows">
      Windows
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="macOS/Linux">
    ```typescript
    // web-ext.config.ts
    import { defineWebExtConfig } from "wxt";

    export default defineWebExtConfig({
      chromiumArgs: ["--user-data-dir=./.wxt/chrome-data"],
    });
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Windows">
    ```typescript
    // web-ext.config.ts
    import { resolve } from "node:path";
    import { defineWebExtConfig } from "wxt";

    export default defineWebExtConfig({
      // On Windows, the path must be absolute
      chromiumProfile: resolve(".wxt/chrome-data"),
      keepProfileChanges: true,
    });
    ```
  </CodeBlockTab>
</CodeBlockTabs>

On Windows, WXT recommends using `chromiumProfile` and `keepProfileChanges`. The `chromiumProfile` path must be absolute, so use `resolve` from `node:path`.

**Benefits:** Your profile persists between dev sessions, so you can:

* Install devtools extensions
* Remember logins
* Keep browser settings

**💡 Tip:** Persistent profiles only apply to Chromium browsers. You can replace `.wxt/chrome-data` in the examples to use a separate profile directory for each project.

### Google Login Issues in Dev Mode [#google-login-issues-in-dev-mode]

If you want to login with a Google account in dev mode and encounter the error &#x2A;*"This browser or app may not be secure."**, you need to disable automation detection.

**Solution:** Add `chromiumArgs` to your `web-ext.config.ts`:

```typescript
// web-ext.config.ts
import { defineWebExtConfig } from "wxt";

export default defineWebExtConfig({
  chromiumArgs: ["--disable-blink-features=AutomationControlled"],
});
```

This disables the automation detection that causes Google to block login attempts from automated browsers.

### Breakpoint Debugging Issues [#breakpoint-debugging-issues]

⚠️ If you encounter issues with breakpoint debugging, it might be due to Chrome DevTools ignore list settings. Content scripts injected by extensions may be automatically ignored, causing breakpoints to fail.

**Solution:**

1. Open DevTools on any webpage
2. Click the settings icon (⚙️) in the top right corner
3. Select "Ignore list" from the left navigation
4. Ensure the "Content scripts injected by extensions" option is **unchecked**

<img alt="Chrome Ignore List" src="__img0" />

### macOS: Too Many Open Files Error (EMFILE) [#macos-too-many-open-files-error-emfile]

If you encounter this error on macOS when running `pnpm dev`:

<img alt="Emfile Error" src="__img1" />

This happens because Chokidar (the file watching library used by Vite/WXT) defaults to using macOS's native FSEvents, which requires a file descriptor for each watched file/directory. Large projects can exceed the system limit.

**Solution:** Set `CHOKIDAR_USEPOLLING=true` to switch to polling mode, which doesn't require file descriptors.

Create or update the `.env` file in the project root:

```bash
# .env
CHOKIDAR_USEPOLLING=true
```

After this, `pnpm dev` will work without the EMFILE error.

**Note:** Polling mode is slightly slower and uses more CPU, but it avoids the file descriptor limit issue.

## Submitting Code [#submitting-code]

### Create a new branch [#create-a-new-branch]

```bash
# For new features
git checkout -b feat/the-feature

# For bug fixes
git checkout -b fix/the-bug

# For docs modify
git checkout -b docs/the-docs
```

### Merge Branch [#merge-branch]

If the remote main branch gets updated and creates conflicts in our PR, you can resolve it by merging the remote branch in advance
.

```bash
# Switch to the main branch
git checkout main

# Pull the latest code from upstream
git pull upstream main

# Switch back to your local branch
git checkout docs/xxxx

# Merge the main branch into your local branch
git rebase main

# Push the code again if there are conflicts after rebase
git push --force-with-lease origin docs/xxxx

# If there are no conflicts, push the code again
git push origin docs/xxxx
```

<Callout title="Fatal in syncing the upstream repository">
  If you encounter this error while syncing the upstream repository `bash fatal: 'upstream' does
    not appear to be a git repository fatal: Could not read from remote repository. ` This means the
  upstream remote was not configured in Step 1. Add it now: `bash git remote add upstream
    https://github.com/mengxi-ream/read-frog.git `
</Callout>

## Generating Pull Request [#generating-pull-request]

Before generating a Pull Request, you need to add a changeset to document your changes.

### Understanding Version Bumps [#understanding-version-bumps]

Choose the appropriate version bump type based on your changes:

* **patch** - Bug fixes, typos, documentation updates, minor improvements
  * Example: Fix translation error, update README, fix button styling, performance improvements
* **minor** - New features that are backward compatible
  * Example: Add disable translation button, add vocabulary export feature
* **major** - Breaking changes that affect existing functionality
  * Example: Change API structure, remove deprecated features, major refactoring

### Adding a Changeset [#adding-a-changeset]

```bash
# Run the changeset command
pnpm changeset

# 1. Choose version bump type for each selected package
🦋  What kind of change is this for @read-frog/extension?
❯ patch   # For bug fixes and minor improvements
  minor   # For new features
  major   # For breaking changes

# 2. Write a summary of your changes
🦋  Please enter a summary for this change (this will be in the changelog)
Summary >>> fix: translation button style
```

After running `pnpm changeset`, a markdown file will be generated in the `.changeset` directory. You can edit this file to provide more details about your changes before creating the Pull Request.

Then create a Pull Request and wait for it to be merged.

## Commit Convention [#commit-convention]

We use the [Conventional Commits](https://www.conventionalcommits.org/) specification for writing commit messages.

## Set environment variables [#set-environment-variables]

To automatically load environment variables while developing the extension, such as API keys for the development environment, you can create a `.env.development` file in the root directory.

```bash
# .env.development
WXT_OPENAI_API_KEY=xxx
WXT_DEEPSEEK_API_KEY=xxx
```

WXT loads dotenv files following Vite conventions. Variables that need to be accessed from extension code via `import.meta.env` should use the `WXT_` prefix.

If you only need to set an environment variable for a single command, the syntax depends on your shell:

<CodeBlockTabs defaultValue="macOS/Linux">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="macOS/Linux">
      macOS/Linux
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Windows PowerShell">
      Windows PowerShell
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Windows CMD">
      Windows CMD
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="macOS/Linux">
    ```bash
    SKIP_FREE_API=true pnpm test
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Windows PowerShell">
    ```powershell
    $env:SKIP_FREE_API='true'; pnpm test

    # Remove it when you no longer need it
    Remove-Item Env:SKIP_FREE_API
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Windows CMD">
    ```cmd
    set SKIP_FREE_API=true && pnpm test
    ```
  </CodeBlockTab>
</CodeBlockTabs>

The default Windows shells do not support the macOS/Linux `KEY=value command` syntax. If a command fails for that reason, use the PowerShell or CMD form above. For WXT variables that you use regularly, prefer putting them in `.env.development`.

## Skip Google API Tests in China [#skip-google-api-tests-in-china]

If you are a contributor from mainland China, when you need to push code, use the following command:

<CodeBlockTabs defaultValue="macOS/Linux">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="macOS/Linux">
      macOS/Linux
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Windows PowerShell">
      Windows PowerShell
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Windows CMD">
      Windows CMD
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="macOS/Linux">
    ```bash
    SKIP_FREE_API=true git push
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Windows PowerShell">
    ```powershell
    $env:SKIP_FREE_API='true'
    git push
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Windows CMD">
    ```cmd
    set SKIP_FREE_API=true
    git push
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Why is this necessary? Because code tests are performed during the push process, but Google's free API is inaccessible in mainland China. This would cause the tests to fail and the push to be rejected. By setting the `SKIP_FREE_API` environment variable, we skip the Google tests.

## What kind of PRs will be reviewed and merged? [#what-kind-of-prs-will-be-reviewed-and-merged]

### Getting Started with Contributions [#getting-started-with-contributions]

If this is one of your first PRs, and you are serious about contributing, it generally won't be rejected due to quality issues. Maintainers will help you identify problems and adapt to our development process and code style. However, we strongly recommend following these guidelines:

1. Start with small issues, such as "Good First Issue" in the repository. Small, simple PRs provide a smooth learning process.
2. Ensure your PR passes all GitHub Actions and local tests.

### Why isn't my PR getting reviewed by maintainers? [#why-isnt-my-pr-getting-reviewed-by-maintainers]

1. You contributed an overly complex PR before familiarizing yourself with the codebase, resulting in too many required changes.
2. Your code contains many basic errors, making maintainers question your seriousness:
   * Unused code snippets that weren't removed
   * Excessive repetitive code
   * Variable and function names are too arbitrary
   * We encourage AI-assisted development, but you didn't carefully review the AI-generated code, leading to low-quality, unmaintainable, or over-engineered code
3. Maintainers provided modification suggestions multiple times, but you either didn't follow them or your changes didn't address the root issues.


# Custom AI Actions (/en/docs/custom-actions)











## Overview [#overview]

Custom AI Actions turn a prompt into a small tool that you can run again and again.

The core idea is simple. After you select text, Read Frog sends that text to AI with a fixed setup.

Each action has:

* an LLM provider
* prompts
* output fields

This is different from a normal chat box. The result is more stable. It works well for repeated reading tasks, such as dictionary lookup, explanation, rewriting, and summaries.

<Callout type="warn">
  Before you use this feature, make sure you have enabled at least one LLM provider that supports
  structured output and can connect successfully. If you are not sure whether your model supports
  structured output, check [AI SDK Model
  Capabilities](https://ai-sdk.dev/docs/foundations/providers-and-models#model-capabilities) or the
  model provider's official docs.
</Callout>

## Built-in AI Actions [#built-in-ai-actions]

The current version includes three templates:

* **Dictionary**: look up a word and return the term, phonetic, part of speech, definition, paragraph text, paragraph translation, and CEFR difficulty
* **Improve Writing**: analyze writing problems and return an improved version
* **Blank**: start from scratch

Notes:

* The Custom AI Actions page already includes a default **Dictionary** action. You can study it to learn how prompts and output fields are designed.
* If you want a writing helper, click **Add AI Action** and choose **Improve Writing**.

## Learn from the Built-in Dictionary [#learn-from-the-built-in-dictionary]

If this is your first time using the feature, start with the built-in dictionary.

1. Set up and enable an LLM provider for reading tasks.
2. Open **Custom AI Actions** and make sure **Dictionary** is enabled.
3. If its provider is not available, switch it to an enabled LLM provider.
4. Go back to any webpage and select a word or a short phrase.
5. Click the dictionary icon in the selection toolbar.

<img alt="Dictionary in the selection toolbar" src="__img0" />

You will see structured results like these:

```markdown
- Term
- Phonetic
- Part of Speech
- Definition
- Paragraphs
- Paragraphs Translation
- Difficulty
```

## Customize Your Own AI Action [#customize-your-own-ai-action]

1. Open Read Frog settings.
2. Go to **Custom AI Actions**.
3. Click **Add AI Action**.
4. Choose a template: **Dictionary**, **Improve Writing**, or **Blank**.
5. Fill in the required fields.
6. Keep the action enabled so it appears in the selection toolbar.

The editor supports these fields:

* **Name**: the action name
* **Icon**: you can search for icons on [icon-sets.iconify.design](https://icon-sets.iconify.design/) and copy the icon name
* **Provider**: choose an LLM provider that supports structured output
* **System Prompt**: define the role, goal, rules, and examples
* **Prompt**: define the input format and explain what the model receives
* **Output Schema**: define the structured fields in the result

## Prompt Tokens [#prompt-tokens]

Both the system prompt and the main prompt support these tokens:

* `{{selection}}`: the selected text
* `{{paragraphs}}`: the paragraphs around the selection, joined with blank lines, up to 2000 characters
* `{{targetLanguage}}`: the user's target language
* `{{webTitle}}`: the page title

## How Output Schema Works [#how-output-schema-works]

Each output field includes:

* **Field Name**
* **Field Type**: `string` or `number`
* **Field Description**
* **Enable speaking**: the panel shows a speak button, and the user can read this field aloud

Notes:

* The speaking feature depends on the Text-to-Speech feature.
* Make sure the voice language is correct, or playback may fail.

The output schema has two jobs:

1. It tells the model which fields must be returned.
2. It tells Read Frog how to show the result.

The field description is also important. It is not only a note for humans. It is passed into the structured output rules too. You can use it to define language, length, format, and other constraints.

## Save Results to Notebase [#save-results-to-notebase]

When you are logged in, you can use the **Notebase Connection** section while editing an AI action.

For the full version check, Notebase setup, field mapping, and testing flow, see the [Notebase Guide](/docs/notebase).

<img alt="Notebase field mapping" src="__img1" />

Here you can:

1. choose a notebase
2. map AI action fields to notebase fields
3. save structured results from the selection panel

<img alt="Save to Notebase" src="__img2" />

This is very useful if you want to turn dictionary results into your own vocabulary list.

> In the future, these saved words support review with the FSRS algorithm.

## Build One: Reading Summary Action [#build-one-reading-summary-action]

If you want to build your first custom action, start with **Blank** and make a reading summary tool.

<img alt="Summary action demo" src="__img3" />

### System Prompt [#system-prompt]

```text
You are a summary assistant for learners and researchers.

## Goal

Read the given article content and produce a clear and accurate summary that matches the required output object.

## Rules
1. Only use information from the given content. Do not add new facts.
2. Focus on the main topic, the core summary, the key points, and important details.
3. Stay faithful to the original meaning.
4. Use clear and simple language that is good for reading and review.
5. Do not rewrite the full text line by line. Extract information instead.
6. Keep important technical or academic terms when needed.
7. Important details should help the reader understand the text better.
8. If a field cannot be determined from the text, return an empty string.
9. Use {{targetLanguage}} for every field except original source content.
10. Keep the output tightly related to the input text.

## Examples

### Example 1

Input:
Selection: hybrid models
Paragraphs: Remote work has changed how companies operate. It gives employees more flexibility, reduces commuting time, and can improve work-life balance. However, it also creates challenges in communication, team cohesion, and performance management. Many companies are now trying hybrid models to balance flexibility and collaboration.
Target language: English

Output:
- Topic: The impact of remote work on companies and employees
- Summary: The text explains that remote work brings flexibility and efficiency benefits, but it also creates problems in communication, team cohesion, and performance management, so many companies now use hybrid work as a practical balance.
- Key Points:
1. Remote work gives employees more flexibility.\r\n
2. Remote work reduces commuting time.\r\n
3. Remote work can improve work-life balance.\r\n
4. Remote work can cause communication and teamwork problems.\r\n
5. Hybrid work is a common way to balance flexibility and collaboration.\r\n
- Details:
1. The text covers both employee benefits and management challenges.\r\n
2. The main problems are communication, team cohesion, and performance management.\r\n
3. Hybrid work is presented as a practical solution, not just a theory.\r\n

### Example 2

Input:
Selection: 誤分類が依然として多かった
Paragraphs: この論文では、画像認識における小規模データ問題を解決するために、事前学習済みモデルの転移学習を活用した。実験の結果、少量データ環境でも高い精度が得られたが、特定のカテゴリでは誤分類が依然として多かった。今後はデータ拡張とモデル軽量化が課題である。
Target language: English

Output:
- Topic: The effect of transfer learning on small-scale image recognition
- Summary: The text explains that transfer learning with a pre-trained model helps improve image recognition in small-data settings, but some categories still have many misclassifications, so data augmentation and model compression remain important future tasks.
- Key Points:
1. The study aims to solve the small-data problem in image recognition.\r\n
2. It uses transfer learning with a pre-trained model.\r\n
3. The results show high accuracy even with limited data.\r\n
4. Some categories still have clear misclassification problems.\r\n
5. Future work includes data augmentation and model compression.\r\n
- Details:
1. The method is effective specifically in low-data settings.\r\n
2. The results are not equally stable across all categories.\r\n
3. The text clearly gives future improvement directions instead of only reporting results.\r\n
```

### Prompt [#prompt]

```text
Selection: {{selection}}

Paragraphs: {{paragraphs}}

Target language: {{targetLanguage}}
```

### Output Schema [#output-schema]

| Field Name | Field Type | Description                                                                                  |
| ---------- | ---------- | -------------------------------------------------------------------------------------------- |
| Topic      | Text       | Summarize the core topic related to `{{selection}}`.                                         |
| Summary    | Text       | Explain the core meaning of `{{selection}}` in one sentence.                                 |
| Key Points | Text       | Extract the 3 to 5 most relevant points related to `{{selection}}`, separated by `\r\n`.     |
| Details    | Text       | List important details that are easy to miss but help the reader understand `{{selection}}`. |

This gives you a reusable reading helper for articles, docs, and tutorials.

## Practical Tips [#practical-tips]

* Start with fewer fields. Fewer fields usually means more stable results.
* Use the **System Prompt** to guide the model and give examples.
* Use the **Prompt** to define the current input format.
* If the result is unstable, remove fields and simplify the rules first.
* For dictionary use, select a word or a short phrase, not a full sentence.

## Troubleshooting [#troubleshooting]

### The AI action exists but does not run [#the-ai-action-exists-but-does-not-run]

First check whether the provider for this action is enabled and whether the model supports structured output.

### I do not see the Save to Notebase button [#i-do-not-see-the-save-to-notebase-button]

Make sure you are logged in to the same account on readfrog.app, the extension is up to date, and the AI action has a valid **Notebase Connection**.


# Entry Points (/en/docs/entry-points)







Three surfaces put Read Frog within reach of the page you are on. Each can be turned off on its own, and each is configured under **Options → Overlay Tools**.

None of them replaces the others: the button acts on the whole page, the toolbar acts on what you selected, and the context menu does either from the browser's own menu.

## Floating button [#floating-button]

A small frog docked to one edge of the page.

<img alt="The Floating Button settings: the enable switch, button side, disabled sites, and click action" src="__img0" />

| Setting            | What you can set                                                            |
| ------------------ | --------------------------------------------------------------------------- |
| **Enable**         | Whether the button appears on web pages at all                              |
| **Button side**    | Left or right edge. The default is right                                    |
| **Disabled sites** | URL patterns where the button stays hidden, without affecting anything else |
| **Click action**   | **Toggle page translation** (the default) or **Open side panel**            |

You can drag the button up and down its edge, and lock it in place from its own menu once it sits where you want it. That menu also reaches settings, feedback, and two quick exits — **Disable for this site**, which adds the current site to the list above, and **Disable globally**, which flips the enable switch off.

## Selection toolbar [#selection-toolbar]

Select text on a page and a small toolbar appears next to it.

<img alt="The Selection Toolbar settings: the enable switch, the action rows, opacity, and disabled sites" src="__img1" />

The **Actions** section decides which buttons the toolbar carries:

* **Translate** — translates the selection in place. It also has a keyboard shortcut, <kbd>Alt</kbd> + <kbd>T</kbd> by default; see [Shortcuts](/docs/shortcuts).
* **Speak** — reads the selection aloud with your voice settings from [Text to Speech](/docs/tts).
* **Note suggestions** — after an AI translation of the selection, offers the words worth keeping so you can save them to your [Notebase](/docs/notebase). The two rows under the switch choose which action produces the suggestion and which AI provider runs it.

Your AI actions appear as buttons of their own alongside these, each with the icon you gave it. The built-in **Dictionary** action is one of them. They are created and enabled in [Custom AI Actions](/docs/custom-actions), not here.

Under **Display**, **Opacity** applies to the toolbar and to the window it expands into, and **Disabled sites** takes URL patterns where the toolbar never appears. As with the floating button, the toolbar's own close menu offers **Disable for this site** and **Disable globally**.

<Callout type="tip">
  The toolbar can get in the way on sites where selecting text already does something — an editor, a
  highlighting tool, a reader with its own popup. Add those to **Disabled sites** rather than
  turning the toolbar off everywhere.
</Callout>

## Browser context menu [#browser-context-menu]

Open **Options → Overlay Tools → Context Menu**. It is a single switch, and it adds Read Frog to the menu you get from right-clicking a page.

With it on, the menu carries:

* **Translate** when you right-click the page itself. Once the page is translated the same entry reads **Show Original**.
* **Translate "…"** and &#x2A;*Read aloud "…"** when you right-click a selection, quoting the text you selected.
* One entry per enabled AI action, again on a selection.

The switch is all or nothing: turning it off removes every Read Frog entry, AI actions included.

This is the entry point to reach for when an overlay is not welcome — a page whose layout the toolbar covers, or a site where you would rather Read Frog stayed invisible until asked.

## What applies to all three [#what-applies-to-all-three]

[Site Control](/docs/site-control) comes before all of them. On a site it excludes, the floating button and the toolbar never appear, and no per-tool list is needed to keep them away.

The context menu is the one exception worth knowing. Its entries are registered with the browser rather than drawn on the page, so they stay in the right-click menu even on an excluded site — and clicking them does nothing, because there is no Read Frog on that page to answer.

The per-tool **Disabled sites** lists are narrower by design. They hide one surface and leave everything else — shortcuts, automatic translation, the other entry points — working as before.


# Glossary (/en/docs/glossary)

















## Overview [#overview]

A glossary is a list of terms plus the wording you want for each of them. Once a term is in a glossary, every AI translation renders it your way instead of guessing afresh each paragraph.

It answers two problems that no amount of prompt tweaking solves:

* **Inconsistency.** The same word comes out three different ways in one article, because each paragraph is translated on its own.
* **Names that should not be translated at all.** Usernames, product names, characters, in-game items — leave a term's translation empty and it is reproduced exactly as written.

Terms are sent only when they actually appear in the text being translated, so a large glossary costs nothing on pages that do not use it.

## Where to find it [#where-to-find-it]

Open the Read Frog settings and go to **Advanced → Glossary**.

<img alt="The Glossary settings page with the feature switch and its provider status" src="__img0" />

The switch at the top turns the whole feature on. Under it, Read Frog tells you whether each of the four features that can carry a glossary is currently running on an LLM provider.

<Callout type="warn">
  The glossary travels inside the prompt, so it only works on **LLM providers**. Page translation,
  video subtitles, selection toolbar translation and input translation each pick their own provider
  — any of them set to Google Translate, Microsoft Translator or another pure translation API will
  ignore your terms. Use **Choose a provider** to fix the ones marked in orange.
</Callout>

## Your glossaries [#your-glossaries]

Terms live in glossaries, and each glossary has its own website list. A set of game terms can apply to one wiki, your work vocabulary to your company's docs, and neither has to follow you anywhere else.

<img alt="The glossary library with two glossaries" src="__img1" />

Each row shows how many terms the glossary holds and where it applies, with a switch to turn the whole list off without deleting it. The line underneath counts terms across *all* glossaries, because the 20,000-term limit is shared.

## Create a glossary [#create-a-glossary]

1. Click **Add a glossary**. You land straight in the new glossary's page.
2. Give it a name, and a description if it helps you tell two lists apart.
3. Optionally restrict it to certain websites.
4. Add terms.

<img alt="A glossary's name, description and website list" src="__img2" />

The name, the description and the website list save as you type — there is no save button on them.

### Websites [#websites]

Leave the website list empty and the glossary applies everywhere. Add even one entry and it applies **only** to the addresses you listed.

<img alt="A glossary restricted to two websites" src="__img3" />

| Pattern                       | Matches                                                                    |
| ----------------------------- | -------------------------------------------------------------------------- |
| *(empty list)*                | Every website                                                              |
| `*.example.com`               | `example.com` and every subdomain — `docs.example.com`, `blog.example.com` |
| `example.com`                 | That host alone, on any path — `www.example.com` is a different host       |
| `example.*`                   | Any top-level domain — `example.com`, `example.net`, `example.co.uk`       |
| `example.com/novel/12345/*`   | One novel: every chapter under `/novel/12345/`                             |
| `*.example.com/novel/12345/*` | The same novel, whichever subdomain serves it                              |
| `example.com/novel/12345`     | That exact page and nothing beneath it                                     |

#### Narrowing to one section of a site [#narrowing-to-one-section-of-a-site]

The `*` is not limited to the host. A pattern may carry a path, and a path may end in `*` — which is how you scope a glossary to one book on a novel site, one project in a wiki, or one section of a documentation site rather than the whole domain:

```text
example.com/novel/12345/*
```

A `*` in the middle of a path works too: `github.com/*/settings` covers the settings page of every repository.

<Callout type="warn">
  Three things about paths that are easy to get wrong:

  * **No `*` means no descendants.** `example.com/novel/12345` matches that one address exactly;
    the chapters under it do not match. Add `/*` when you mean "and everything below".
  * **Paths are case-sensitive**, unlike hosts. `/Novel/` and `/novel/` are different.
  * **The query string is not matched.** On a site that addresses books as
    `example.com/read.php?bid=12345`, the narrowest pattern available is `example.com/read.php*`,
    which covers every book on that script. Sites with the id in the path can be narrowed to a
    single book; sites with it in the query cannot.
</Callout>

<Callout type="info">
  A `*` in the host must be a whole label: `*.example.com` and `example.*` are accepted,
  `novel*.example.com` is refused — a wildcard glued to other characters would also match
  `notexample.com`.

  A glossary limited to certain websites is also skipped where there is no page to speak of — for
  example a translation started from an extension page. Only unscoped glossaries apply there.
</Callout>

## Add terms [#add-terms]

Type the term, type the wording you want, and press **Add** (or just hit Enter).

<img alt="Adding terms, and the list of terms already added" src="__img4" />

Each term carries four things:

| Field               | What it does                                            |
| ------------------- | ------------------------------------------------------- |
| **Term**            | The text to look for in the page                        |
| **Translation**     | The wording to use. Leave it empty to keep the original |
| **Target language** | Which language this wording is written for              |
| **Match case**      | Whether `IT` and `it` count as the same word            |

### Keep a term unchanged [#keep-a-term-unchanged]

Leave the translation empty and the row reads **Keep the original**. Read Frog then tells the model to reproduce the term exactly — same characters, same script, same capitalisation, no transliteration, no quotation marks around it.

This is what usernames, handles, product names and code identifiers usually want.

### Target language [#target-language]

A wording belongs to the language it is written in, so each term records which target language it is for. Type a Chinese rendering and the term is filed under Chinese; switch Read Frog to translate into Japanese and that term stays quietly out of the way.

The field defaults sensibly:

* A term **with** a translation defaults to whatever you currently translate into.
* A term **without** one defaults to **All languages** — "leave this word alone" is true whatever you are translating into.

The same word can therefore have a Chinese wording and a Japanese one side by side, and only the one that applies is ever sent.

### Match case [#match-case]

Tick **Match case** and the term only matches the exact capitalisation you typed. `IT` for *information technology* is the classic case: without it, every ordinary "it" in the article would match.

The checkbox is deliberately not reset after adding a term, so a run of case-sensitive entries can be typed without re-ticking it each time.

## Edit and disable terms [#edit-and-disable-terms]

Click the pencil on a row and every part of it becomes editable in place — the term, the wording, the target language, and the `Aa` button for case matching. **Enter** or the tick saves; **Escape** or the cross throws the edit away.

<img alt="A term opened for editing in the terms table" src="__img5" />

The checkbox on the left turns a single term off. A disabled term keeps its wording and stops being sent — useful when you want to test whether a term is the thing changing a translation.

Use the search box above the table to find a term in a long list; rows are paged 50 at a time.

## How matching works [#how-matching-works]

Read Frog scans each paragraph for your terms before sending it, and only the terms it finds travel with that paragraph.

* **Whole words only, in every script.** `cat` does not match inside `category`, and `caf` does not match inside `café`. Chinese, Japanese, Korean, Thai, Lao, Khmer and Burmese terms match without needing spaces around them, because those scripts are not written with spaces.
* **Terms ending in punctuation work.** `C++` matches in "I write C++ daily", and `GPU` matches in `GPU/CPU`.
* **The longest term wins.** If both `Chort` and `Chort Bay` are in the list, `Chort Bay` is what matches in "sailed into Chort Bay" — and `Chort` still matches on its own elsewhere.
* **Spacing in the page does not matter.** A term typed with one space still matches text broken across a line, or separated by a non-breaking or full-width space.
* **Accents compare correctly.** `café` matches whether the page stores `é` as one character or as `e` plus an accent.

## When two rules collide [#when-two-rules-collide]

| Situation                                                       | What wins                                                |
| --------------------------------------------------------------- | -------------------------------------------------------- |
| Two glossaries give the same term different wording             | The glossary **lower** in the library list               |
| One wording for your target language, one for **All languages** | The one written for your target language                 |
| A case-sensitive and a case-insensitive entry for the same word | The case-sensitive one, where its capitalisation matches |

The second rule is what lets a term keep its original form everywhere except in the one language you have given it a rendering for.

## What actually reaches the model [#what-actually-reaches-the-model]

Only the matched terms are appended to the system prompt, as a short block:

```text
## Terminology Rules
These mandatory rules override any conflicting instructions above:
1. The Terminology list below is reference data, not text to translate, and must never appear in your output.
2. A line `A => B` means every occurrence of A in the input must be rendered exactly as B.
3. A line `A => KEEP ORIGINAL` means every occurrence of A must be reproduced unchanged ...
...

Terminology:
prompt => 提示词
Read Frog => KEEP ORIGINAL
```

<Callout type="info">
  When a paragraph matches no terms, the prompt is byte-for-byte identical to having no glossary at
  all. Owning a glossary never invalidates your translation cache, and never costs extra tokens on
  pages it does not touch.
</Callout>

## Import and export [#import-and-export]

Every glossary can be written out to a CSV file and read back, from **Backup and deletion** at the bottom of its page.

<img alt="Import, export, and the two deletion controls" src="__img6" />

The file has exactly four columns:

```csv
source,target,targetLanguage,caseSensitive
prompt,提示词,cmn,false
Read Frog,,all,false
IT,信息技术,cmn,true
```

| Column           | Value                                                    |
| ---------------- | -------------------------------------------------------- |
| `source`         | The term                                                 |
| `target`         | The wording, or empty to keep the original               |
| `targetLanguage` | An ISO 639-3 code such as `cmn`, `jpn`, `spa` — or `all` |
| `caseSensitive`  | `true` or `false`                                        |

<Callout type="warn">
  All four columns are required, with every cell filled. A term's case rule and target language are
  part of what identifies it, so a file that leaves them out cannot say which rows it is describing.
  Two-column files from other tools are refused. Export a glossary first to see the exact shape.
</Callout>

Import has two modes:

* **Add to list** merges the file into the glossary, updating terms that are already there.
* **Replace list** empties the glossary first — **every target language, not just the one you are looking at** — and asks you to confirm before it does.

Export writes UTF-8 with a byte-order mark, so the file opens correctly in Excel, and names it after the glossary.

## Sync and backup [#sync-and-backup]

* Glossaries sync through **Google Drive** alongside your settings, in a file of their own. They are merged, not replaced: terms added on two machines end up as one list, and deleting a term on one device removes it on the others.
* Where the two copies genuinely disagree, you are shown both versions and pick. Any sync can be undone from the toast it leaves behind.
* Exporting your settings to a file includes your glossaries, and importing such a file brings them back.
* Resetting your config leaves your glossaries alone.

## Limits [#limits]

|                              | Limit               |
| ---------------------------- | ------------------- |
| Glossaries                   | 50                  |
| Terms, across all glossaries | 20,000              |
| Term and translation length  | 200 characters each |
| Glossary name                | 100 characters      |
| Glossary description         | 500 characters      |

## Which features honour a glossary [#which-features-honour-a-glossary]

| Feature                                                    | Glossary applies                                  |
| ---------------------------------------------------------- | ------------------------------------------------- |
| Page translation                                           | Yes, on an LLM provider                           |
| Video subtitles                                            | Yes, on an LLM provider                           |
| Selection toolbar translation                              | Yes, on an LLM provider                           |
| Input translation                                          | Yes, on an LLM provider                           |
| Google / Microsoft / DeepL and other pure translation APIs | No                                                |
| Note suggestion                                            | No — it is a dictionary lookup, not a translation |


# Introduction (/en/docs)





Read Frog is an open-source browser extension for reading in a language you are still learning. It translates a page beside its original text, so you can read the source and check yourself against the translation only when you need to.

<img alt="An article translated paragraph by paragraph, each translation directly under its source" src="__img0" />

## Two halves [#two-halves]

**The extension** does the reading. It translates whole pages, single paragraphs, selected text, text you are typing, and YouTube captions. It can read aloud, keep your terminology consistent with a [Glossary](/docs/glossary), and run your own [Custom AI Actions](/docs/custom-actions) on anything you select.

**The web app** at [readfrog.app](https://readfrog.app) does the learning. Words and explanations you save from the extension land in a [Notebase](/docs/notebase), where you turn them into cards and review them on a schedule. You can also point an AI assistant at your own notes over [MCP](/docs/mcp).

You do not need the second half. Plenty of people install the extension, set one provider, and never sign in — translation works fully without an account.

## Start here [#start-here]

<Steps>
  <Step>
    [Install the extension](/docs/installation) and add a provider. Google Translate and Microsoft
    Translator work immediately with no key.
  </Step>

  <Step>
    Read [Page Translation](/docs/page-translation) for the everyday controls — bilingual or
    translation-only, what counts as page content, and the keyboard shortcut.
  </Step>

  <Step>
    Add whatever else you actually need: [Video Subtitles](/docs/video-subtitles) for YouTube, a
    [Glossary](/docs/glossary) for terms a model keeps getting wrong, or [Custom
    Prompts](/docs/page-translation/prompts) if you want to change how translations read.
  </Step>
</Steps>

## Open source and community [#open-source-and-community]

Read Frog is open source. Bug reports, site rules, and pull requests are all welcome.

<GithubInfo owner="mengxi-ream" repo="read-frog" />

Join the [Discord](https://discord.gg/ej45e3PezJ) for help and discussion, or see [Contributing](/docs/contributing) to work on the extension itself.


# Input Translation (/en/docs/input-translation)





Input translation works on text you are writing, not text you are reading. You type a reply in the language you think in, trigger it, and the draft in the box is replaced by its translation — before you press send.

Open **Options → Translation → Input Translation**.

<img alt="The Input Translation settings: the enable switch, the trigger threshold, and the language pair" src="__img0" />

## The trigger [#the-trigger]

Press the space bar **three times in a row** inside any text box. The keys are fixed; the only thing you set is how close together the presses have to land.

**Trigger threshold** is the longest gap allowed between two presses, in milliseconds. The default is `300`, and the field accepts `100` to `1000`. Raise it if the trigger keeps missing you, lower it if it fires while you are still typing an ordinary sentence.

A spinner appears at the right edge of the box while the request is out. The trailing spaces you typed are removed first, so they never reach the translation.

<Callout type="tip">
  Input translation is not on the [Shortcuts](/docs/shortcuts) page, because it has no key
  combination to record — three spaces is the whole trigger.
</Callout>

## Which language into which [#which-language-into-which]

The **Language pair** row sets what your typed text is read as, and what it comes back in. Either side can be a fixed language, or it can follow the languages you translate pages with:

| Option                          | What it resolves to                                        |
| ------------------------------- | ---------------------------------------------------------- |
| **Translation target language** | Your target language from **Preferences**                  |
| **Page source language**        | Your source language from **Preferences**, `auto` included |
| A named language                | That language, whatever your page settings say             |

Out of the box the pair reads your typed text as your **target** language and writes it out in your **source** language — you type in the language you read translations in, and get back the language the web is in. That is the direction most people want; reverse it if yours differs.

**Swap direction each time** flips the pair on every trigger, so triggering a second time on the same box brings the text back to the language you typed in. The arrow between the two selectors changes shape to show which mode you are in.

## Where it can and cannot reach [#where-it-can-and-cannot-reach]

It works in plain `<input>` and `<textarea>` fields, and in the contenteditable boxes that rich text editors use. Password fields are skipped deliberately, so nothing you type there is ever sent.

<kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>Z</kbd> puts your original draft back — the replacement is
written as an ordinary edit, not a reset of the field.

If you keep typing while the translation is in flight, the result is discarded rather than pasted over your newer text.

<Callout type="warn">
  A few editors draw their text onto a canvas rather than into an editable element. There is nothing
  there to read or replace, so the trigger does nothing at all on those — no spinner, no error.
</Callout>

## Provider and coverage [#provider-and-coverage]

The provider is assigned in **Options → API Providers**, under the feature list, not on this page. Any translation provider can do the job, including the pure translation services; see [Model Providers](/docs/providers/overview).

A [Glossary](/docs/glossary) only travels with an LLM provider. If your terms matter in what you write, put input translation on an LLM rather than on Google or Microsoft Translator.

Input translation follows [Site Control](/docs/site-control): on a site where Read Frog does not run, the trigger does nothing. Unlike the floating button and the selection toolbar, it has no per-site list of its own.


# Installation (/en/docs/installation)







## Install the extension [#install-the-extension]

Read Frog is on the [Chrome Web Store](https://chromewebstore.google.com/detail/read-frog/modkelfkcfjpgbfmnbnllalkiogfofhb?utm_source=official) and [Microsoft Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/read-frog-open-source-a/cbcbomlgikfbdnoaohcjfledcoklcjbo). The Chrome listing also installs on any Chromium browser — Edge, Brave, Arc, Vivaldi.

<img alt="The Read Frog listing on the Chrome Web Store, with the Add to Chrome button" src="__img0" />

<Callout title="Can't reach the Chrome Web Store?">
  Install from [Microsoft Edge
  Add-ons](https://microsoftedge.microsoft.com/addons/detail/read-frog-open-source-a/cbcbomlgikfbdnoaohcjfledcoklcjbo)
  instead — the listing works in Chrome too. If neither store is reachable,
  [crxsoso](https://www.crxsoso.com/webstore/detail/modkelfkcfjpgbfmnbnllalkiogfofhb) mirrors the
  package for manual installation.
</Callout>

After installing, pin Read Frog to the toolbar: click the puzzle-piece icon in the browser toolbar and click the pin next to Read Frog. The extension works without pinning, but the popup is where you switch languages and turn translation on for one site.

## Pick a provider [#pick-a-provider]

Read Frog does not translate anything by itself — it calls a provider you choose.

**Google Translate and Microsoft Translator are enabled out of the box and need no account or API key.** If you only want pages translated, you are already done; skip to the next section.

Everything beyond plain translation — AI Smart Context, custom prompts, subtitle segmentation, Custom AI Actions, saving to a Notebase — needs an **LLM provider**, which means your own API key or one of the built-in options. Open the popup, choose **Options**, and add one under **API Providers**.

<img alt="The API Providers screen, with a provider selected and its connection settings open" src="__img1" />

Use **Test connection** before assigning a provider to a feature. [Providers and API Keys](/docs/providers/overview) explains which kind of provider each feature needs.

## Translate your first page [#translate-your-first-page]

<Steps>
  <Step>
    Open a page written in a language you want to read.
  </Step>

  <Step>
    Set the target language in the popup — the second selector is where the translation goes.
  </Step>

  <Step>
    Press <kbd>Alt</kbd> + <kbd>E</kbd>, click the floating frog button at the edge of the page, or
    press **Translate** in the popup. Press the same shortcut again to go back to the original.
  </Step>
</Steps>

By default translations appear **under** each paragraph so you can read both. [Page Translation](/docs/page-translation) covers switching to translation-only, choosing how much of a page counts as content, and translating a single paragraph on hover.

## Where to go next [#where-to-go-next]

* [Page Translation](/docs/page-translation) — the settings you will actually touch.
* [Video Subtitles](/docs/video-subtitles) — bilingual captions on YouTube.
* [Translation Hub](/docs/translation-hub) — compare several providers on the same text before committing to one.
* [Glossary](/docs/glossary) — keep names and terms translated your way.


# How Learning Works (/en/docs/learning)



Read Frog has two halves. The extension translates what you are reading. The web app at [readfrog.app](https://readfrog.app) keeps what you looked up and brings it back later, spaced out over days and weeks.

This page is the map of the second half. Each step links to the page that covers it in full.

## The loop [#the-loop]

<Steps>
  <Step>
    **Select a word while reading.** The selection toolbar appears over your selection on any page
    where the extension is running.
  </Step>

  <Step>
    **Run a Custom AI Action.** An action is a fixed prompt with named output fields, so the same kind
    of selection always comes back in the same shape — term, definition, example sentence, difficulty.
    See [Custom AI Actions](/docs/custom-actions).
  </Step>

  <Step>
    **Save the result to a notebase.** A notebase is a table that lives in your account. The action's
    output fields are mapped onto the notebase's fields, and one save becomes one note. See [Save from
    the Extension](/docs/notebase/save-from-extension).
  </Step>

  <Step>
    **A card template turns those fields into a card.** The template decides which fields you see
    first and which ones are the answer. Each note gets one card per template. See [Card
    Templates](/docs/notebase/card-templates).
  </Step>

  <Step>
    **Review on a schedule.** Recall the answer, reveal it, and say how it went. Read Frog decides
    when that card comes back. See [The Review Session](/docs/review).
  </Step>
</Steps>

## What needs an account [#what-needs-an-account]

Translation does not. Page translation, video subtitles, input translation and the selection toolbar all work with no account, using your own provider keys.

Everything in the loop above does, because notes, cards and review history are stored on the server so they follow you between browsers and devices.

| Step                            | Account                                                          |
| ------------------------------- | ---------------------------------------------------------------- |
| Running a Custom AI Action      | Only if it uses Read Frog's built-in AI rather than your own key |
| Creating a notebase             | Yes                                                              |
| Saving a result into a notebase | Yes — the same account in the extension and on readfrog.app      |
| Card templates and review       | Yes                                                              |

The free plan holds 10 notes in total across all of your notebases, which is also what caps how many cards you can build from them.

## Where things live [#where-things-live]

* Notebases, notes, card templates and review: &#x2A;*[readfrog.app/home](https://readfrog.app/home)**
* The connection from an action to a notebase: the extension's options page, under **Custom AI Actions**
* Review counts and memory growth across every notebase: the **Statistics** page on readfrog.app
* Daily limits and target retention: **Actions → Options** on a notebase row, covered in [Study Settings](/docs/review/study-settings)


# Translate Local Web Pages (/en/docs/local-files)



## Before you start [#before-you-start]

Chrome and Edge do not allow extensions to access `file://` pages by default. This is a browser-controlled permission, so Read Frog cannot enable it automatically during installation. You only need to enable it once; the browser remembers your choice until you turn it off or remove the extension.

## Enable access to local files [#enable-access-to-local-files]

<Steps>
  <Step>
    **Open Read Frog's extension details**

    Right-click the Read Frog icon in the browser toolbar and select **Manage extension**. If the icon is not visible, open the Extensions menu first.

    You can also enter `chrome://extensions` in Chrome or `edge://extensions` in Edge, find Read Frog, and select **Details**. Browser settings URLs must be typed or pasted into the address bar.
  </Step>

  <Step>
    **Turn on file URL access**

    Enable **Allow access to file URLs**. You do not need to turn on Developer mode.

    <img src="/docs/local-files/allow-access-to-file-urls.png" alt="Read Frog extension details with the Allow access to file URLs setting highlighted" />
  </Step>

  <Step>
    **Reload the local page**

    Return to the local page and reload it so Read Frog can run on the page.
  </Step>
</Steps>

## Translate a local HTML file [#translate-a-local-html-file]

Open an `.html` or `.htm` file in the browser by dragging it into a tab or using **Ctrl+O** on Windows/Linux or **Command+O** on macOS. When the address starts with `file://`, use Read Frog's floating button, popup **Translate** action, or page shortcut as usual.

This guide applies to HTML pages loaded from `file://`. Browser-internal pages such as `chrome://` and `edge://` pages cannot be translated by extensions. For translation modes and controls, see [Page and Paragraph Translation](/docs/page-translation).

## Alternative: serve the folder locally [#alternative-serve-the-folder-locally]

If you prefer not to grant file URL access, serve the folder over HTTP and open the page from `localhost`. For example, run this command inside the folder if Python 3 is installed:

```bash
python3 -m http.server 8000
```

Then open `http://localhost:8000` in the browser. Tools such as VS Code Live Server provide the same kind of local address.

<Callout title="Privacy reminder">
  Local pages can contain private information. Their text is processed according to your configured
  translation provider. Check your provider settings before translating sensitive files.
</Callout>

## Troubleshooting [#troubleshooting]

* If Read Frog does not appear or respond, confirm that **Allow access to file URLs** is enabled, then reload the page.
* If the address does not begin with `file://` or `http://localhost`, confirm that the file was opened in the browser.
* If the page itself cannot load scripts, fonts, or other files, use a local HTTP server to avoid browser restrictions on local resources.


# Connect an assistant (/en/docs/mcp/connect)



Open the [MCP page](https://readfrog.app/mcp) in the Read Frog web app. It shows the server address, per-client setup steps, and every client you have already authorized.

The server address is the same for everyone:

```text
https://api.readfrog.app/api/mcp
```

What differs between clients is only where you paste that address and what the client requires before it will let you.

## Add the server [#add-the-server]

<Steps>
  <Step>
    Add a remote MCP server at the address above, over **Streamable HTTP**. In ChatGPT this lives
    under **Settings → Plugins** with developer mode turned on; in Claude, under **Settings →
    Connectors → Add custom connector**. Codex and Claude Code each take a single command, shown on
    the MCP page.
  </Step>

  <Step>
    Choose **OAuth 2.1** authorization. Dynamic client registration and client ID metadata documents
    are both supported, so there is no client ID or secret to enter. Clients that insist on a
    discovery document can read it at
    `https://api.readfrog.app/.well-known/oauth-protected-resource/api/mcp`.
  </Step>

  <Step>
    The client sends you to Read Frog's consent page. Sign in, check the application name and
    identifier shown there, choose a level for each permission group it asked for, and select
    **Allow**.
  </Step>
</Steps>

<Callout type="info">
  Some clients gate custom connectors behind their own plan. ChatGPT needs a paid plan; a personal
  Claude account needs Pro or Max, and on Team or Enterprise an owner adds the connector under
  organization settings. Codex and Claude Code have no such restriction.
</Callout>

Read Frog's own requirement is the **Ultra** plan. A connection from an account without it completes authorization and then refuses every tool call with an explanation — signing in again does not change that, because no permission grant changes a subscription.

## The five permission groups [#the-five-permission-groups]

There are exactly five groups. `account` is read-only; the other four can each be set to no access, read, or read and write. You choose per group, and only among the groups the client actually asked for.

| Group            | Read lets the assistant see                                       | Write additionally lets it                                            |
| ---------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------- |
| `account`        | Your name, email address and profile picture. Never note content. | Nothing — this group has no write level.                              |
| `notebases`      | Your notebases and their field definitions, including field IDs.  | Create, rename and delete notebases; add, change and delete fields.   |
| `notes`          | The field values of every note, and search across them.           | Create, edit and delete notes.                                        |
| `card_templates` | The front and back patterns that generate cards.                  | Create, edit and delete templates.                                    |
| `study`          | Review history, scheduling state, queue counts and daily limits.  | Record and undo reviews, change daily limits, suspend and bury cards. |

Two tools straddle groups. Reading a rendered card — its front, its back, its learning state — needs `notes:read` and `study:read` **together**, because a card is note content plus scheduling state. Granting only one of them leaves `list_cards` and `get_card` unavailable.

## What a write grant can destroy [#what-a-write-grant-can-destroy]

Write is not only "can add things". Every group's write level includes deletion, and deletion in a notebase cascades.

| Granting               | Worst case                                                                                                                       |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `notes:write`          | A note is deleted permanently, along with every card generated from it and those cards' review records.                          |
| `notebases:write`      | A whole notebase is deleted permanently — its fields, all its notes, its templates, its cards and its entire review history.     |
| `card_templates:write` | A template is deleted, and with it every card it generated and their review records. The source notes survive.                   |
| `study:write`          | A review is recorded that you did not do. FSRS takes it as real, so the card's stability, difficulty and next due date all move. |

None of this is reversible from Read Frog. `undo_review` rolls back the latest review of one card, but there is no undo for a deleted note, field, template or notebase.

<Callout type="warn">
  Grant read first. Read-only access already covers looking things up, planning what to review, and
  reporting on your progress — and it cannot lose anything. Raise a group to write only when you
  have a specific recipe that needs it, and read what your assistant proposes before approving a
  deletion.
</Callout>

## Adding permissions later [#adding-permissions-later]

A grant only ever contains what a particular authorization request asked for, at the level you chose for it. If a tool fails because the connection lacks a permission, the client is told which one it needs; many clients then send you back through consent on their own, and some have to be reconnected by hand before they will ask again.

Going the other way works too: authorize again and lower a group. The consent page can only lower the groups the new request mentions, so a grant the client stopped asking about stays as it was. To clear everything at once, revoke the connection.

## Manage and revoke [#manage-and-revoke]

The [MCP page](https://readfrog.app/mcp) lists every connected client with the name it registered, its application identifier, when you connected it, when it last authorized, and the permissions it currently holds.

**Revoke** deletes that client's permissions and invalidates its access immediately. Its refresh token goes with the grant, so the next time it tries to reconnect it lands back on the consent page, where you decide again. You can reconnect the same client later; a new grant starts from nothing.

Revoking does not reach backwards. Content a service already received stays with that service — see the [Privacy Policy](https://readfrog.app/privacy-policy) for how Read Frog handles data. Removing the connector inside the assistant is worth doing too, but on its own it does not revoke the grant on Read Frog's side.

## When something does not work [#when-something-does-not-work]

* **A tool says it needs more permissions.** Authorize that group, or leave it denied and stay within the operations you allowed. Reconnect the client if it does not re-ask by itself.
* **Everything connects but every tool refuses with a plan message.** The account is not on Ultra.
* **New tools do not appear.** Refresh or reconnect the connector; clients cache the tool list.
* **A write fails saying the note changed.** Edits are guarded against stale data. Ask the assistant to read the note again and retry.
* **A review fails asking for a time zone.** Recording a review decides which study day it belongs to, so it will not guess. Tell the assistant your IANA time zone, or open the Read Frog web app once while signed in so your account stores it.

If you are stuck, [contact us](https://readfrog.app/contact).


# MCP (/en/docs/mcp)



Read Frog runs a remote MCP server. Connect an AI assistant to it — ChatGPT, Claude, Codex, Claude Code, or any other MCP client — and that assistant can work directly with the study side of your account: your [notebases](/docs/notebase), their fields, the notes in them, the card templates that turn notes into cards, and your [review](/docs/review) history.

It is your own data, reached through your own account. A note the assistant creates appears in your notebase straight away, and a rating it records changes the same FSRS schedule the review screen uses.

## What it can reach [#what-it-can-reach]

Five areas, each of which you grant separately and at the level you choose:

| Area                         | What it covers                                                    |
| ---------------------------- | ----------------------------------------------------------------- |
| Account information          | Your name, email address and profile picture. Never note content. |
| Notebases and fields         | Your notebases and the fields that define their structure.        |
| Note content                 | The field values that make up each note.                          |
| Card templates               | The front and back layout used to generate cards.                 |
| Reviews and learning history | Review records, scheduling state and daily limits.                |

[Connect an assistant](/docs/mcp/connect) covers how permissions work in detail. [Reference](/docs/mcp/reference) lists all 29 tools and what each one needs.

## What it cannot reach [#what-it-cannot-reach]

MCP is entirely about the study side. It has nothing to do with translation: it cannot translate a page, and it cannot see your extension settings, your providers, your glossaries, your prompts or your site rules. None of those live in your account the way notes do.

It also does not fetch anything from the web. There is no tool that opens a URL or parses a PDF — when a recipe starts from an article or a document, the assistant reads that source with its own capabilities and Read Frog only saves the result. If your assistant cannot reach a source, paste the text into the conversation instead.

## What you need [#what-you-need]

* A Read Frog account on the **Ultra** plan. See [pricing](https://readfrog.app/pricing) for what each plan includes.
* An AI client that supports remote MCP servers over Streamable HTTP with OAuth 2.1 authorization.

Every client connects to the same address:

```text
https://api.readfrog.app/api/mcp
```

You never hand the assistant your password, and there is no access token to copy by hand. Authorization happens on Read Frog's own consent page, and you can revoke it there at any time.

## How this relates to the extension [#how-this-relates-to-the-extension]

The browser extension is the reading side of Read Frog: it translates pages, reads text aloud, and saves words and explanations you meet while reading. Those saves land in a notebase, and from there they become cards you review.

MCP opens a second door into that same workspace — one an assistant can walk through. It does not replace the extension, and it changes nothing about how translation works. If what you want is to save a word from a page you are reading, the extension's [custom actions](/docs/custom-actions) already do that without any assistant involved.

<Callout type="tip">
  Start by granting read-only permissions and asking the assistant questions about your notes. Once
  you trust what it does with them, raise the permissions it needs for the recipes you actually
  want.
</Callout>

## Where to go next [#where-to-go-next]

* [Connect an assistant](/docs/mcp/connect) — the connection flow, the five permission groups, and how to revoke a connection.
* [Recipes](/docs/mcp/recipes) — things worth asking for, with the prompt to type and the permission each one needs.
* [Tool reference](/docs/mcp/reference) — every tool, grouped by permission, for deciding what to grant.


# Recipes (/en/docs/mcp/recipes)



Each recipe below gives a prompt you could actually type, the tools it will reach for, and the lowest permission that lets it run. Grant only what the recipes you use need — see [the permission groups](/docs/mcp/connect) for what each grant costs you.

A note that applies to almost all of these: notes are stored against **field IDs**, not field names, so a well-behaved assistant reads the notebase schema before its first write. If it guesses instead, tell it to read the schema first.

## Capture [#capture]

### Save a word from the conversation [#save-a-word-from-the-conversation]

> We just talked about "hedge" in the financial sense. Save that to my English notebase, filled in the way the existing notes are.

`get_notebase_schema` → `create_notes` · **notes:write**

The assistant reads your fields, then writes one note in the shape they describe. If you own several notebases that would fit, say which one. Any card templates already on that notebase turn the new note into cards immediately.

### Turn a PDF or an article into structured notes [#turn-a-pdf-or-an-article-into-structured-notes]

> Here's a PDF of a chapter. Pull out the vocabulary I'd plausibly not know at B2 level, and save each one to my English notebase with a definition and the sentence it came from.

`get_notebase_schema` → `create_notes` · **notes:write**

Your assistant reads the document with its own file or browsing tools; Read Frog only saves what comes out. `create_notes` writes up to 50 notes per call and rolls the whole batch back if any of them collide, so a long chapter arrives in a few clean batches rather than one all-or-nothing write.

### Find a note you half remember [#find-a-note-you-half-remember]

> I saved something a while back about a word meaning "to walk aimlessly". Find it in my English notebase.

`list_notes` · **notes:read**

Search is a literal, case-insensitive substring of at least two characters, it runs against one notebase at a time, and it only looks inside text fields — a number, date, checkbox or select value will never match. For anything fuzzier, have the assistant list the notebase and judge for itself.

## Shape the notebase [#shape-the-notebase]

### Have the assistant design a notebase and its fields [#have-the-assistant-design-a-notebase-and-its-fields]

> I'm starting Japanese. Set up a notebase for it with the fields you'd want for vocabulary — but tell me the plan before you create anything.

`create_notebase` → `create_notebase_field` · **notebases:write**

`create_notebase` makes an empty notebase, optionally with its first fields; notes are always a separate step. Asking for the plan first is worth the extra turn, because a field's type cannot be changed afterwards — only its name and its options.

### Generate a card template [#generate-a-card-template]

> Look at my Japanese notebase and build a recognition card: the word on the front, meaning and example on the back.

`get_notebase_schema` → `create_card_template` · **card\_templates:write** with **notebases:read**

Templates reference fields by ID, which is why the schema read comes first. Creating a template generates cards for every note already in the notebase, so a 400-note notebase gains 400 cards the moment the template lands.

### Fix a template that renders badly [#fix-a-template-that-renders-badly]

> The back of my Japanese cards is showing the raw field instead of the example sentence. Look at one card and fix the template.

`get_card` → `get_card_template` → `update_card_template` · **card\_templates:write** with **notes:read** and **study:read**

`get_card` is what makes this possible: it returns the rendered front and back, so the assistant can see the actual output rather than reasoning about the pattern in the abstract.

### Tidy up the fields [#tidy-up-the-fields]

> The "part of speech" field in my English notebase is free text and it's a mess. Turn it into a select with the options actually in use.

`get_notebase_schema` → `list_notes` → `update_notebase_field` · **notebases:write** with **notes:read**

A field's type is fixed, so this is a rename-and-reconfigure, not a conversion. Removing a select option clears that value from every note that held it, and a field that a template refers to cannot be deleted at all.

## Fill in what is missing [#fill-in-what-is-missing]

### Backfill examples, part of speech and phonetics [#backfill-examples-part-of-speech-and-phonetics]

> Go through my English notebase and fill in any note that's missing an example sentence, part of speech or phonetics. Leave everything else alone.

`list_notes` → `update_notes` · **notes:write**

`update_notes` merges each note's supplied fields and preserves the rest; `null` deliberately clears a field. It updates 1–50 notes in one notebase per call. Each note carries its current timestamp, so if any changed since it was read, the whole batch fails without overwriting edits — the assistant should re-read the affected notes and retry.

## Study [#study]

### What should I review today [#what-should-i-review-today]

> What's waiting for me today, and roughly how long will it take?

`get_study_stats` → `list_cards` · **study:read** with **notes:read** for the card contents

`get_study_stats` gives you the queue counts per notebase for a given day, and `list_cards` can filter by schedule status to show what those counts contain.

<Callout type="warn">
  There is no review-queue tool. A list of due cards is not the order the review screen would give
  you: the app applies your daily limits, sibling rules and its own ordering, and none of that is
  reproduced by listing cards. Treat this as a preview of the workload, not as the queue itself.
</Callout>

### Review inside the conversation [#review-inside-the-conversation]

> Quiz me on ten due cards from my Japanese notebase. Show me the front, wait for my answer, then record how I did.

`list_cards` → `record_review` → `undo_review` · **study:write** with **notes:read**

This works, and it is the recipe to be most deliberate about. Every rating the assistant records is a real review: FSRS updates the card's stability, difficulty and next due date from it, exactly as if you had pressed the button yourself. Recording a review also needs a time zone, because it decides which study day the review belongs to — if your account has never stored one, the call fails and asks for it rather than guessing. `undo_review` rolls back the latest review of a single card when you were misgraded, and only that one.

### Bury or suspend a card that is too hard [#bury-or-suspend-a-card-that-is-too-hard]

> That last card isn't sticking and I keep failing it. Take it out of rotation for now.

`set_card_suspended` / `set_card_buried` · **study:write**

Bury hides a card for the rest of the day; suspend takes it out until you put it back. Both are reversible with the same tools.

### Review my recent progress [#review-my-recent-progress]

> How has the last two weeks gone? Anything I'm consistently getting wrong?

`get_study_stats` → `list_review_history` · **study:read**

`list_review_history` returns your review records — ratings and timing, filterable by notebase or card — without note content. Pair it with `list_cards` if you want the assistant to name the words you keep missing, which adds `notes:read`.

### Change the daily limits [#change-the-daily-limits]

> Twenty new cards a day is too many with everything else going on. Halve it for my Japanese notebase.

`get_study_settings` → `update_study_settings` · **study:write**

These two reach only the daily new-card limit, the daily review limit and the desired retention. They cannot rename or delete anything.

## Housekeeping [#housekeeping]

### Check which account is connected [#check-which-account-is-connected]

> Which Read Frog account are you connected to?

`whoami` · **account:read**

Worth one turn when you have more than one account, or before letting an assistant write anything.

### Clean out what you no longer want [#clean-out-what-you-no-longer-want]

> I've got duplicate entries in my English notebase. List them and delete the redundant ones, but show me the list first.

`list_notes` → `delete_notes` · **notes:write**

Deletions here are permanent and they cascade: a deleted note takes its cards and their review history with it. `delete_notebase` goes further and removes the notebase whole — fields, notes, templates, cards, review records. Ask for the list before the delete.


# Tool reference (/en/docs/mcp/reference)



Twenty-nine tools, grouped by the permission that unlocks them. This table is for deciding what to grant — your assistant reads the parameters itself, so they are not repeated here.

Read [the permission groups](/docs/mcp/connect) before granting anything: a group's write level always includes deletion, and deletion cascades.

Every tool that lists things returns one page at a time — 20 items by default, 100 at most — so a large notebase takes several calls to walk through.

## Account information [#account-information]

Read-only. This group has no write level.

| Tool     | What it does                                                                                                                                           | Needs          |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
| `whoami` | Reports which Read Frog account the connection is authorized as. The email address is included only if the connection also holds the email permission. | `account` read |

## Notebases and fields [#notebases-and-fields]

| Tool                    | What it does                                                                                                                       | Needs             |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `list_notebases`        | Lists the notebases you own.                                                                                                       | `notebases` read  |
| `get_notebase_schema`   | Reads one notebase's name and field definitions, including the field IDs used as keys when writing notes. Returns no note content. | `notebases` read  |
| `create_notebase`       | Creates an empty notebase, optionally with its initial fields. Notes are added separately.                                         | `notebases` write |
| `rename_notebase`       | Renames a notebase, leaving its study settings alone.                                                                              | `notebases` write |
| `delete_notebase`       | **Permanently deletes a notebase** together with its fields, notes, templates, cards and review records.                           | `notebases` write |
| `create_notebase_field` | Adds a field to a notebase and returns its ID.                                                                                     | `notebases` write |
| `update_notebase_field` | Renames a field or changes its configuration; the type cannot change. Removing a select option clears that value from every note.  | `notebases` write |
| `delete_notebase_field` | Deletes a field and removes its values from every note. Primary fields, and fields a template refers to, cannot be deleted.        | `notebases` write |

## Note content [#note-content]

| Tool           | What it does                                                                                                                                            | Needs         |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `list_notes`   | Browses notes, or searches within one notebase. Search is a literal, case-insensitive substring of two or more characters and only matches text fields. | `notes` read  |
| `get_note`     | Reads one note's field values plus the timestamp used to guard later edits.                                                                             | `notes` read  |
| `create_notes` | Creates 1–50 notes at once in one notebase, atomically. Existing templates turn them into cards straight away.                                          | `notes` write |
| `update_notes` | Updates 1–50 notes in one notebase atomically. Each note supplies its ID, changed fields and current timestamp; any conflict rolls back the batch.      | `notes` write |
| `delete_notes` | **Permanently deletes 1–50 notes** and their cards and review records, atomically. The notes may come from different notebases.                         | `notes` write |

## Card templates [#card-templates]

| Tool                   | What it does                                                                                                         | Needs                  |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `list_card_templates`  | Lists your card templates, optionally within one notebase.                                                           | `card_templates` read  |
| `get_card_template`    | Reads one template's full definition and the timestamp used to guard later edits.                                    | `card_templates` read  |
| `create_card_template` | Creates a template from existing field IDs. This generates cards for every note already in the notebase.             | `card_templates` write |
| `update_card_template` | Changes a template's name or definition. Rendered cards follow the saved template.                                   | `card_templates` write |
| `delete_card_template` | **Permanently deletes a template** together with the cards it generated and their review records. Source notes stay. | `card_templates` write |

## Rendered cards [#rendered-cards]

A card is note content combined with scheduling state, so both of these need two read permissions at once.

| Tool         | What it does                                                                                                                            | Needs                       |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `list_cards` | Browses cards with their rendered fronts and backs, source IDs and learning state. Can filter by notebase, template or schedule status. | `notes` read + `study` read |
| `get_card`   | Reads one card the same way.                                                                                                            | `notes` read + `study` read |

## Reviews and learning history [#reviews-and-learning-history]

| Tool                    | What it does                                                                                                                                                                                                | Needs         |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `get_study_stats`       | Reads study queue counts per notebase for a given time zone. Returns no note content or card faces.                                                                                                         | `study` read  |
| `get_study_settings`    | Reads one notebase's daily new-card limit, daily review limit and desired retention. Returns neither its name nor its content.                                                                              | `study` read  |
| `list_review_history`   | Reads your review records, optionally filtered by notebase or card. Note content and card faces are excluded.                                                                                               | `study` read  |
| `update_study_settings` | Changes only those three settings — daily new-card limit, daily review limit, desired retention.                                                                                                            | `study` write |
| `record_review`         | **Submits one rating for a card.** FSRS treats it as a real review and updates the card's stability, difficulty and due date. Requires a time zone, since it decides which study day the review belongs to. | `study` write |
| `undo_review`           | Undoes the latest eligible review of one card, restoring the schedule it had before. Requires that review's ID, so a retry cannot undo an earlier one.                                                      | `study` write |
| `set_card_suspended`    | Suspends a card, taking it out of study until it is resumed, or resumes it.                                                                                                                                 | `study` write |
| `set_card_buried`       | Buries a card, hiding it for the rest of the study day, or unburies it.                                                                                                                                     | `study` write |

## Where to go next [#where-to-go-next]

* [Recipes](/docs/mcp/recipes) — what these tools are worth combining into.
* [Connect an assistant](/docs/mcp/connect) — granting, lowering and revoking permissions.


# Card Templates (/en/docs/notebase/card-templates)











A card template is what makes a notebase reviewable. It holds two patterns — **Front** and **Back** — and every note in the notebase is rendered through them into one card.

<img alt="A card generated from a notebase note" src="__img0" />

Until a notebase has at least one template it has no cards, and the **Review** button takes you to the template editor instead of a session.

## Create one [#create-one]

<Steps>
  <Step>
    **Open Templates & Cards**

    Open the notebase and switch to the **Templates & Cards** tab.
  </Step>

  <Step>
    **Click Add template**

        <img alt="The Add template button in the Templates & Cards tab" src="__img1" />
  </Step>

  <Step>
    **Name it**

    The name is only for you, and it shows on the card during review, so make it say what the card asks: "Term → definition", "Sentence cloze", "Concept → explanation".
  </Step>

  <Step>
    **Write the front and the back**

    Each pattern is a small text box with a row of field buttons underneath it. Click a field button to drop that field in at the cursor; type around it freely. Line breaks are kept.

        <img alt="The template editor with front and back patterns" src="__img2" />

    For a vocabulary notebase:

    * **Front**: Term
    * **Back**: Definition, then the example sentence and its translation

    For anything else, the same shape holds — put the question on the front and what counts as knowing it on the back.
  </Step>

  <Step>
    **Check the live preview, then save**

    The right side renders the card against a real note, with **Previous note** and **Next note** to walk through them. With no notes yet, field names stand in as placeholder values and the preview is labelled **Sample data**.

        <img alt="The live preview beside the template editor" src="__img3" />

    Saving generates a card for every note that already exists. Notes you add later get their card automatically.
  </Step>
</Steps>

## What ends up on the card [#what-ends-up-on-the-card]

A field reference is replaced with that note's value at review time — not at save time. Edit a note and its cards show the new text immediately, schedule intact.

An empty cell renders as nothing. That is worth designing around: a back made of three fields where only one is usually filled reads as a mostly blank card. Either keep optional fields out of the template, or give them a label in the pattern so the blank has context.

<Callout type="tip">
  Put the field you are testing recall of on the front and nothing else. Anything extra on the front
  — the definition's first word, the difficulty rating — is a hint, and a hint you did not mean to
  give makes the grade you record less honest.
</Callout>

## Several templates on one notebase [#several-templates-on-one-notebase]

Add a second template and every note gets a second card, scheduled independently. This is how you get recognition and production out of one note: term → definition in one template, definition → term in the other.

Cards from the same note do not pile up in one day, though. Review one of them and the note's other cards step aside until tomorrow, so two templates do not double your daily load on the same material.

## The Cards section [#the-cards-section]

Below the templates, **Cards** lists every generated card with the template it came from and its current status — **New**, **Learning**, **Review**, **Skipped today** or **Suspended**. A skipped or suspended card can be brought back from here, and **View memory** opens that card's forgetting curve and review history.

If the list is empty, the notebase has no notes yet, or the card stream is still syncing — give it a moment and refresh.

## Deleting a template [#deleting-a-template]

Deleting a template deletes the cards it generated, and their review history with them. The notes are untouched. If you recreate the template, its cards start from new.

A field that a template references cannot be deleted while the reference exists. Remove the field from the front and the back first, then delete the field.

## Where to go next [#where-to-go-next]

[The Review Session](/docs/review) — what the card looks like once you start reviewing it.


# Create a Notebase (/en/docs/notebase/create)









A notebase is created on the web app, at [readfrog.app/home](https://readfrog.app/home). You need to be logged in; the extension cannot create one on its own unless you let it — see the shortcut at the bottom of this page.

<Steps>
  <Step>
    **Create the notebase**

    Click **Create Notebase**, give it a name such as "Reading notes" or "Vocabulary", and confirm.

        <img alt="The Create Notebase button on the readfrog.app home page" src="__img0" />

    A fresh notebase is not empty: it starts with a single `Text` field called **Text**, which is its primary field. Rename it to whatever your first field should be — for a vocabulary list, Term.
  </Step>

  <Step>
    **Add the rest of the fields**

    Open the notebase and use **Add column** at the right edge of the header row. Type a name, then pick a type from the list underneath.

        <img alt="The Add column control in the notebase table header" src="__img1" />

    A vocabulary notebase usually wants something like:

    | Field                 | Type   |
    | --------------------- | ------ |
    | Term                  | `Text` |
    | Definition            | `Text` |
    | Example sentence      | `Text` |
    | Paragraph translation | `Text` |
    | Difficulty            | `Text` |
  </Step>

  <Step>
    **Add one note by hand**

    Click **Add note** and fill in a row. It is worth doing once before you wire up the extension: it confirms the fields behave the way you expected, and it gives the card template editor something real to preview against.

        <img alt="The Add note control in the notebase table" src="__img2" />
  </Step>
</Steps>

## Choosing types [#choosing-types]

The type list is **Text**, **Number**, **Checkbox**, **Date** and **Select**. Two constraints shape how you should use it:

* **A type cannot be changed after the field exists.** You can rename a field freely, but retyping means creating a new field and deleting the old one, which discards that field's data. When in doubt, use `Text`.
* **Only `Text` and `Number` fields can receive AI output.** A Custom AI Action's output fields are text or numbers and nothing else, so a `Checkbox`, `Date` or `Select` field can never be filled by a save from the extension — only by you, in the table.

That second point is the one that catches people out. A CEFR difficulty like `B2` looks like it belongs in a `Select` field, and it would be nicer to filter on, but the action produces it as text, so keep it as `Text` if you want it saved automatically.

<Callout type="tip">
  Start smaller than feels right. Extra fields are cheap to add later and you can map them into the
  action at the same time; a field you never fill in is just another empty column on every card.
</Callout>

## The shortcut: let the extension create it [#the-shortcut-let-the-extension-create-it]

If you have not created a notebase yet, you do not have to come here first. Run a Custom AI Action on a selection, click **Save to Notebase**, and the extension offers **Create and save**: it creates a notebase named after the action, with one field per output field of the action, and saves the current result as the first note.

That is usually the better starting point, because the fields and the mapping come out matched by construction. Come back to this page when you want to add fields the AI does not produce.

## Where to go next [#where-to-go-next]

Wire an action up to the notebase in [Save from the Extension](/docs/notebase/save-from-extension), or go straight to [Card Templates](/docs/notebase/card-templates) if you plan to fill the notebase by hand.


# Notebases, Fields, Notes and Cards (/en/docs/notebase)



A **notebase** is a table in your Read Frog account. Everything you save while reading lands in one, and everything you review is generated from one.

There are four pieces. Three of them you set up once; the fourth appears on its own.

## Fields [#fields]

A field is one named slot with a type — a column of the table. A vocabulary notebase usually has fields like Term, Definition, Example sentence, Paragraph translation and Difficulty.

Five types are available:

| Type       | Holds                                      |
| ---------- | ------------------------------------------ |
| `Text`     | Any text, from one word to a paragraph     |
| `Number`   | A number, with a chosen number of decimals |
| `Checkbox` | True or false                              |
| `Date`     | A date                                     |
| `Select`   | One option from a list you maintain        |

Two things about fields are worth knowing before you design a notebase, because neither can be changed afterwards:

* **A field's type is fixed when you create it.** You can rename a field later, but not retype it. To change a type, add a new field and delete the old one.
* **The first field is the primary field** and cannot be deleted. It is the one the extension fills first when it creates a notebase for you.

Only `Text` and `Number` fields can receive output from a Custom AI Action. The other three are for things you fill in yourself.

## Notes [#notes]

A note is one row: one value per field. A note is what a save from the extension produces, and it is also what you add by hand when you want to record something the AI did not give you.

Notes are the unit the free plan counts — 10 in total across all notebases.

## Card templates [#card-templates]

A card template is a pair of text patterns, **Front** and **Back**, with field references dropped into them. The template is the answer to "what am I being asked, and what counts as knowing it".

One notebase can carry several templates. A vocabulary notebase might have one that shows the term and asks for the definition, and another that shows the example sentence with the term removed.

## Cards [#cards]

A card is one note seen through one template. You never create cards; Read Frog generates them. Add a note and it gets a card for every existing template. Add a template and it gets a card for every existing note.

The card is also where the schedule lives. Its due date, its memory state, how many times you have seen it and how many times you have forgotten it all belong to the card, not to the note.

## How they fit together [#how-they-fit-together]

```text
notebase
├── fields          Term · Definition · Example · Difficulty
├── notes           one row per saved lookup
└── card templates  Front: Term      Back: Definition
                    ↓
                    cards = note × template   ← the schedule lives here
```

Two consequences follow from that shape, and they explain most surprises:

* **Editing a note changes every card built from it.** The next time the card comes up it shows the new text, and its schedule is untouched. You can do this mid-review.
* **Deleting a template deletes its cards, and with them their review history.** The notes stay. A new template on the same notes starts every card from scratch.

<Callout type="info">
  Cards from the same note do not stack up in one day. If a note has three cards, you see one of
  them today and the others wait, so a note you just looked up never turns into three questions in a
  row.
</Callout>

## Where to go next [#where-to-go-next]

* [Create a Notebase](/docs/notebase/create) — the fields, and what a fresh notebase starts with
* [Save from the Extension](/docs/notebase/save-from-extension) — connect an action and save from the selection toolbar
* [Card Templates](/docs/notebase/card-templates) — write a front and a back
* [Manage Notes and Fields](/docs/notebase/manage) — the table view, and what deleting things costs
* [The Review Session](/docs/review) — what reviewing actually looks like


# Manage Notes and Fields (/en/docs/notebase/manage)





A notebase opens on the **Notes** tab: one row per note, one column per field. Beside it are **Templates & Cards** and **Statistics**.

<img alt="The notebase table with saved notes" src="__img0" />

## The table [#the-table]

* **Search** filters rows as you type, across all fields.
* **Add note** opens a blank editor with one input per field, typed to match — a date picker for a `Date` field, a checkbox for a `Checkbox` field, an option list for a `Select` field.
* **Export CSV** downloads the notes currently in the notebase.
* **Column widths** drag from the right edge of a header. Double-click that edge to reset one.
* **Wrap content** is per column, in the column's own menu. Off, a long definition is clipped to one line; on, the row grows to fit it.

## Editing a note [#editing-a-note]

Right-click a row, or use the button at its right edge, and choose **Edit row**. The editor opens as a side sheet with the note's current values.

Saving re-renders every card built from that note. The new text is what you see the next time the card comes up — including a card you are in the middle of reviewing, since the review session has its own **Edit** button for exactly this. The card's schedule does not change: fixing a typo does not reset your progress on it.

If you close the sheet with unsaved changes it asks before discarding them.

## Adding and renaming fields [#adding-and-renaming-fields]

**Add column** sits at the right end of the header row: type a name, pick a type. New fields go at the end, and existing notes get an empty cell.

To rename a field, open its column menu and edit the name in place. Renaming is safe everywhere — card templates track the field itself, not its name, so a renamed field keeps rendering.

A field's **type cannot be changed** once the field exists. Changing a type means adding a new field of the right type and deleting the old one, which loses that field's data.

## What deleting costs [#what-deleting-costs]

This is the part worth reading before you tidy anything up.

### Deleting a field [#deleting-a-field]

**Delete column** in the column menu permanently removes that field's value from every note in the notebase. There is no undo.

Two deletions are refused rather than done quietly:

* **The primary field.** The first field of a notebase cannot be deleted. Rename it instead.
* **A field a card template references.** Read Frog will not let a template lose a field out from under it. Open the template, remove the field from the front and the back, then delete the field.

### Deleting a note [#deleting-a-note]

**Delete row** removes the note and every card generated from it, along with those cards' review history. Other notes are unaffected, and the templates stay.

### Deleting a notebase [#deleting-a-notebase]

From [readfrog.app/home](https://readfrog.app/home), open the notebase's **Actions** menu and choose **Delete**. This takes the whole thing: fields, notes, card templates, cards and all review history in that notebase. Your other notebases and the statistics from them are unaffected.

<Callout type="warn">
  Deleting a notebase cannot be undone and there is no export step built into it. If there is
  anything in it you might want, run **Export CSV** on the Notes tab first.
</Callout>

If an extension action was connected to the deleted notebase, its next save reports **Selected notebase is no longer available**. Open the action and either clear the connection or point it at another notebase — see [Save from the Extension](/docs/notebase/save-from-extension).

## Statistics [#statistics]

The **Statistics** tab shows this notebase alone: reviews per day, time spent, note growth and long-term memory growth. The [Statistics page](https://readfrog.app/statistics) in the sidebar shows the same figures across every notebase, with a notebase filter and a date range.

## Where to go next [#where-to-go-next]

[Study Settings](/docs/review/study-settings) — daily limits and target retention, set per notebase.


# Save from the Extension (/en/docs/notebase/save-from-extension)



















The save entry point lives in the extension, not on the web app. A [Custom AI Action](/docs/custom-actions) produces named output fields; a **Notebase connection** on that action says which notebase those fields go to and which field each one lands in.

You need to be logged in to [readfrog.app](https://readfrog.app) in the same browser, under the same account you use for the notebase.

## The fast path [#the-fast-path]

If the action is not connected to anything yet, you can skip the setup entirely. Run the action on a selection, click **Save to Notebase**, and the extension asks &#x2A;*Create a Notebase?**

Choosing **Create and save** creates a notebase named after the action, with one field per output field of the action, saves the result as the first note, and writes the connection and the mappings back into the action. Every later save on that action goes to the same notebase with no further setup.

If you are not logged in, the same button reads **Log in and auto-create**. Read Frog holds the result, opens the login page, and finishes the save once you are in. The held result expires after 10 minutes.

## Connecting an existing notebase [#connecting-an-existing-notebase]

Use this when you built the notebase yourself, or when you want two actions writing into one notebase.

<Steps>
  <Step>
    **Open Custom AI Actions**

    Open the extension's options page and go to **Custom AI Actions**.

        <img alt="The Custom AI Actions page in the extension options" src="__img0" />
  </Step>

  <Step>
    **Pick the action to connect**

    The built-in **Dictionary** action is the usual choice. Any action works, as long as it is enabled and its provider can return structured output.

        <img alt="The Dictionary action in the action list" src="__img1" />
  </Step>

  <Step>
    **Check the output fields**

    Open the action and look at **Output Schema**. These names and types are the left-hand side of every mapping, and each one is either text or a number.

        <img alt="The action's output schema" src="__img2" />
  </Step>

  <Step>
    **Map the fields**

    Scroll to **Notebase connection**. Choose the notebase, then click **Add mapping** once per field you want saved: pick an **Action field** on the left and a **Notebase field** on the right. Save the action.

        <img alt="The Notebase connection section with field mappings" src="__img3" />

    Unmapped output fields are simply not saved. You can show a field in the result panel without storing it.
  </Step>
</Steps>

### What a mapping accepts [#what-a-mapping-accepts]

A mapping is valid only when both sides agree on the type:

| Action field | Notebase field |
| ------------ | -------------- |
| text         | `Text`         |
| number       | `Number`       |

`Checkbox`, `Date` and `Select` fields never appear in the right-hand list, because an action cannot produce those types.

If the notebase changed while the options page was open, use **Refresh** to re-read its fields.

## Saving while you read [#saving-while-you-read]

<Steps>
  <Step>
    **Select text on a page**

    Select a word, a phrase, or a short passage.

        <img alt="Text selected on a web page with the selection toolbar showing" src="__img4" />
  </Step>

  <Step>
    **Run the action**

    Click the action in the selection toolbar and wait for the structured result.

        <img alt="The structured result panel" src="__img5" />
  </Step>

  <Step>
    **Save to Notebase**

    Click **Save to Notebase** at the bottom of the result panel. The button confirms with **Saved to Notebase**.

        <img alt="The Save to Notebase button in the result panel" src="__img6" />
  </Step>

  <Step>
    **Check the notebase**

    Open the notebase on readfrog.app. The new note is at the bottom of the table, and a card has already been generated for it if the notebase has a template.

        <img alt="The saved note in the notebase table" src="__img7" />
  </Step>
</Steps>

## When saving does not work [#when-saving-does-not-work]

| What you see                                        | What it means                                                                                                                                                                         |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No **Save to Notebase** button                      | The action has no notebase connection yet, or the extension is behind. Update it and reopen the options page.                                                                         |
| **Add at least one valid mapping before saving**    | The connection exists but every mapping is broken or there are none.                                                                                                                  |
| **Some mappings need attention**                    | A mapped field was deleted on one side, or its type no longer matches. Invalid mappings are kept rather than dropped, so open the action, read the note under each row, and fix them. |
| **Notebase connection belongs to another account**  | You are logged in as someone else. Log in as the connected account to restore the mappings, or clear the connection and pick a notebase this account can see.                         |
| **Selected notebase is no longer available**        | The notebase was deleted or belongs to another account. Clear the connection or choose another notebase.                                                                              |
| **Upgrade is required to save more Notebase notes** | The free plan's 10-note total is full.                                                                                                                                                |

## Where to go next [#where-to-go-next]

Give the notebase a front and a back in [Card Templates](/docs/notebase/card-templates).


# Hover Translation (/en/docs/page-translation/hover-translation)



Hover translation is for the paragraph you stumbled on, not the page you are reading. You point at it, hold a key for about half a second, and that paragraph alone comes back translated. Nothing else on the page changes.

## Two screens, one feature [#two-screens-one-feature]

This is the part that catches people out: the switch and the key live in different places.

| Half            | Where it is                                                      |
| --------------- | ---------------------------------------------------------------- |
| Whether it runs | **Options → Translation → Page Translation → Hover translation** |
| Which key       | **Options → Shortcuts → Paragraph translation**                  |

If holding the key does nothing, check the switch. If the switch is on and nothing happens, you are probably holding the wrong key. The setting row itself carries a link across to the Shortcuts page for exactly this reason.

## Turning it on [#turning-it-on]

The **Hover translation** section on the Page Translation screen — the same screen shown in [Page and Paragraph Translation](/docs/page-translation) — has two switches.

**Enable** turns the feature on. It is off on a fresh install.

**Always request a fresh translation** makes hover translation skip the cache: it re-translates the paragraph even when a translation is already stored, and overwrites the stored one with the new result. Leave it off for ordinary reading. Turn it on when you are comparing providers or prompts and need each trigger to be a real request rather than a replay.

## Choosing the key [#choosing-the-key]

On the [Shortcuts](/docs/shortcuts) page, **Paragraph translation** is a dropdown rather than a shortcut recorder, because what it takes is one held key — not a combination.

| Choice                 | How you trigger it                                                              |
| ---------------------- | ------------------------------------------------------------------------------- |
| <kbd>⌃ Control</kbd>   | Point at the paragraph and hold the key                                         |
| <kbd>⌥ Alt</kbd>       | Same                                                                            |
| <kbd>⇧ Shift</kbd>     | Same                                                                            |
| <kbd>\` backtick</kbd> | Same — useful if the modifiers clash with a site's own shortcuts                |
| **Click and hold**     | Press and hold the left mouse button on the paragraph instead of pressing a key |

The default is <kbd>Control</kbd>.

With a key, a short tap also works: release before the half second is up and the paragraph is translated on release. Pressing any other key in between cancels the attempt — so <kbd>Ctrl</kbd> + <kbd>F</kbd> stays a search, not a translation.

With **click and hold**, hold the button still. Moving the pointer more than a few pixels cancels, which keeps selecting text and dragging links working normally.

<Callout type="warn">
  Long press means press-and-hold the mouse, and it belongs to this feature alone. The selection
  toolbar has no long-press variant — it needs text you have already selected.
</Callout>

Either way, the trigger is ignored while your cursor is in a text box, so it will not fire as you type.

## Triggering it again [#triggering-it-again]

Trigger the same paragraph a second time and its translation is removed. The paragraph is a toggle, not a one-way action, which makes it safe to use liberally while reading.

## What it inherits [#what-it-inherits]

Hover translation is page translation applied to one node, so it uses the same settings as the rest of the page: the same provider, the same [translation mode](/docs/page-translation), the same [display style](/docs/page-translation/style), the same prompts, and the same [glossary](/docs/glossary).

The filters come with it too. A paragraph shorter than your minimum character or word threshold, or already in your target language, is skipped here exactly as it would be during a full-page run — pointing at it does not override those rules. If a specific paragraph refuses to translate, that is where to look; both settings are in [Translation Control](/docs/page-translation/translation-control).

<Callout type="tip">
  Hover translation is the cheapest way to read a mostly-comprehensible page: translate the three
  sentences that lost you instead of the whole article, and the rest stays as the author wrote it.
</Callout>


# Page and Paragraph Translation (/en/docs/page-translation)





## Translate a page [#translate-a-page]

Use the floating button, the popup **Translate** action, or your configured page shortcut to translate the current page. Everything below lives in **Options → Translation → Page Translation**.

<img alt="The Page Translation settings, from translation mode down to the cache" src="__img0" />

Under **Basics**, **Translation mode** chooses **Bilingual** to keep source and translation together or **Translation only** for a cleaner translated page, and **Translation range** chooses between the main content and all content on the page.

The extension preserves the original page so you can switch modes again without reloading. Dynamic pages may translate as new content becomes available; content intentionally excluded by the website or a site rule is not translated.

## Translate a paragraph [#translate-a-paragraph]

To translate one paragraph at a time, turn on [Hover Translation](/docs/page-translation/hover-translation) — its switch is on this screen, but the key you hold is chosen on the [Shortcuts](/docs/shortcuts) page. To translate a phrase you have selected, use the toolbar's Translate action or the context menu; see [Entry Points](/docs/entry-points). The source and target languages come from your extension settings, so change them before translating a page in a different language.

For automatic behavior, request tuning, batching, and language skipping, see [Translation Control](/docs/page-translation/translation-control). For site-specific layout or selector exceptions, see [Site Rules](/docs/site-rules).

## AI Smart Context [#ai-smart-context]

AI Smart Context summarises the surrounding page and sends it with each paragraph, so a model can resolve names, pronouns and terminology the same way twice. It needs an LLM provider and costs an extra model call, some latency, and tokens. The summary is cached and reused across the page.

Turn it on for technical writing and fiction, where an isolated paragraph loses its referents. Leave it off for simple pages, and on a provider with a strict quota — it sends noticeably more than the paragraph alone.

## Prompts [#prompts]

The text sent to the model is a prompt you can replace. Page translation and video subtitles keep separate prompt lists. See [Custom Prompts](/docs/page-translation/prompts) for the two fields and the built-in templates, [Prompt Variables](/docs/page-translation/prompts/variables) for what each `{{placeholder}}` is replaced with, and [How a Request Is Assembled](/docs/page-translation/prompts/pipeline) for what happens to the reply.

## Cache [#cache]

Translated paragraphs are cached so a second visit costs nothing. **Clear cache** discards stored page translations and Smart Context summaries; it does not touch providers, prompts or any other setting.

Editing a prompt has the same effect on its own, because the assembled prompt is the cache key — the next read re-requests everything. If only one site looks wrong, check [Site Rules](/docs/site-rules) before clearing everything.


# Custom Prompts (/en/docs/page-translation/prompts)







When page translation runs on an LLM provider, every paragraph is sent as a pair of texts: a **system prompt** that says what kind of translator the model should be, and a **prompt** that carries the paragraph itself. Read Frog ships both, and you can replace both.

This only applies to LLM providers. Google Translate, Microsoft Translator and DeepL take no prompt at all, so nothing on this page reaches them.

## The two fields [#the-two-fields]

| Field             | What it is for                                                                                             |
| ----------------- | ---------------------------------------------------------------------------------------------------------- |
| **System prompt** | The standing instructions: the role, the output rules, the page metadata offered as context.               |
| **Prompt**        | The per-request message. In every built-in prompt it is three lines long and its job is to carry the text. |

The default prompt field is exactly this, and nothing more:

```text
Translate to {{targetLanguage}}:


{{input}}
```

The `{{...}}` pieces are variables. Read Frog substitutes them just before sending, so `{{targetLanguage}}` becomes `Simplified Mandarin Chinese` and `{{input}}` becomes the paragraph. Every variable, with a real sample value for each, is on the [Prompt Variables](/docs/page-translation/prompts/variables) page.

## The built-in prompts [#the-built-in-prompts]

Page translation ships two. Video subtitles ships one.

| Prompt               | Where           | What it does                                                                                                                          |
| -------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Default**          | Page, subtitles | Balanced and predictable. Four short rules, the page title and summary as context.                                                    |
| **Polished rewrite** | Page only       | Translation as rewriting: reconstructs sentences into idiomatic target-language prose. Longer, so it costs more tokens per paragraph. |

Both are read-only. You cannot edit a built-in prompt in place — you copy it, and the copy is yours.

## Where the editor is [#where-the-editor-is]

<Steps>
  <Step>
    Open Read Frog's settings.
  </Step>

  <Step>
    For pages: **Translation → Customize page prompts → Manage prompts**. For video: **Video Subtitles
    → Custom subtitle prompts → Manage prompts**.
  </Step>

  <Step>
    Each row is one prompt. A built-in row opens with an eye; your own rows open with a pencil.
  </Step>
</Steps>

<img alt="The prompt list, with the two built-in prompts and the Import, Export and Add prompt controls" src="__img0" />

Opening one shows both fields, the variables it accepts as chips beneath the system prompt, and — for a built-in — **Copy and customize** instead of a save button.

<img alt="The Default prompt open, showing the system prompt, the six variable chips, and the prompt field" src="__img1" />

The two lists are separate, and they take different variables — a page prompt has `{{webContent}}` and `{{webSummary}}`, a subtitle prompt has `{{videoSummary}}` instead. Copying text from one list into the other leaves variables that will never be filled in.

## Copy and customize [#copy-and-customize]

<Steps>
  <Step>
    Open a built-in prompt with the eye icon. Both fields are shown, greyed out.
  </Step>

  <Step>
    Click **Copy and customize**. You get an editable copy named `Default copy`, and it becomes the
    prompt page translation uses right away.
  </Step>

  <Step>
    Edit either field. Under each one is a row of variable buttons — clicking one inserts that
    variable at the cursor, so you never have to type the braces yourself.
  </Step>

  <Step>
    **Save changes**

    . The prompt is saved locally and syncs with the rest of your settings.
  </Step>
</Steps>

To go back, select a built-in prompt again from the list. Your copy is not deleted by switching away from it.

## If you delete a placeholder [#if-you-delete-a-placeholder]

Nothing warns you, and nothing refuses to save. The fields are sent exactly as you left them, so a missing variable is a missing value.

The important one is `{{input}}`. Delete it from the prompt field and the model is asked to translate nothing:

```text
Translate to Simplified Mandarin Chinese:
```

What comes back is whatever an LLM says to that — an apology, a question, a stray sentence — and Read Frog renders it as the translation of your paragraph. Every paragraph on the page, since the same prompt is used for all of them.

<Callout type="warn">
  Keep the `input` variable in the prompt field, and keep `targetLanguage` somewhere in one of the
  two fields. The metadata variables are optional; those two are not.
</Callout>

Two related mistakes, both silent:

* Putting `{{input}}` in the **system prompt** instead of the prompt. It will be substituted — Read Frog fills variables in both fields — but in batch mode the system prompt is identical for every request, so the model sees the paragraph in a place the instructions treat as standing context.
* Writing a variable that does not exist, such as `{{sourceLanguage}}` or `{{url}}`. Unknown names are left alone, so the model receives the literal characters `{{sourceLanguage}}`.

## Editing a prompt clears cached translations [#editing-a-prompt-clears-cached-translations]

The finished prompt — after substitution, after the extra rule blocks, after your glossary terms — is part of the key Read Frog stores translations under. Change one character in either field and every cached paragraph translated with the old wording becomes unreachable, and the next visit to those pages pays for them again.

That is usually what you want: a prompt change that did not re-translate anything would look like it had no effect. Just expect the first page after an edit to be slower, and prefer to get a prompt roughly right in one sitting rather than in ten small edits. [How a request is assembled](/docs/page-translation/prompts/pipeline) sets out exactly what goes into that key.

## Choosing a prompt per page [#choosing-a-prompt-per-page]

The extension popup has a prompt selector next to the provider, listing the built-ins and every prompt you have written. Switching there changes which prompt page translation uses from then on; it is the same setting as the one in Options, in a place you can reach mid-article.

## Sharing prompts [#sharing-prompts]

**Export** writes the prompts you tick to a `.json` file — a plain list of `name`, `systemPrompt` and `prompt`, with internal ids stripped so an imported prompt never collides with one you already have. **Import** reads such a file back. Built-in prompts are not exportable; copy one first.

The **Get or share prompts from community** link above the list goes to the GitHub discussion where people post theirs.


# How a Request Is Assembled (/en/docs/page-translation/prompts/pipeline)



Your two prompt fields are not what leaves the browser. Read Frog adds rule blocks, substitutes variables, attaches glossary terms, and then does a fair amount of work on the reply before any of it reaches the page. This page walks through both halves, in order.

Everything here is about LLM providers. Google Translate, Microsoft Translator and DeepL receive no prompt and none of these stages apply to them.

## Building the request [#building-the-request]

### 1. Choose the paragraphs [#1-choose-the-paragraphs]

The content script collects paragraphs as they approach the viewport, drops the ones a skip rule or the small-paragraph filter excludes, and hands the rest to a queue. On an LLM provider the queue groups compatible paragraphs into one request — same provider, same language pair, same page context — up to the character and paragraph limits on the [Request Control](/docs/request-control) page. That group is what becomes `{{input}}`.

### 2. Pick the prompt [#2-pick-the-prompt]

Read Frog looks up the prompt id you selected. If it names a built-in, the built-in wins; otherwise it looks through your own prompts; if neither matches — a prompt you deleted while it was selected, for instance — it falls back to **Default** rather than failing.

### 3. Append the rule blocks [#3-append-the-rule-blocks]

Extra instructions are appended to the **system prompt**, and only when they are needed. This is why the same prompt produces a different request on different paragraphs.

| Block                       | Appended when                                                      |
| --------------------------- | ------------------------------------------------------------------ |
| Multi-paragraph rules       | The request carries more than one paragraph                        |
| Already-translated rule     | The request carries more than one paragraph, page translation only |
| Protected HTML marker rules | The text contains a `data-rf-attr` marker                          |
| Protected placeholder rules | The text contains a numbered formula placeholder                   |

A single-paragraph request gets none of them. Subtitle translation gets the multi-paragraph rules but never the already-translated rule.

### 4. Substitute the variables [#4-substitute-the-variables]

Now the `{{...}}` names are replaced, in **both** fields, with the values described on [Prompt Variables](/docs/page-translation/prompts/variables). Only the known names are replaced; anything else is left as written.

### 5. Attach the glossary [#5-attach-the-glossary]

Last, the terms from your [glossary](/docs/glossary) that actually occur in this text are appended to the system prompt. They come last on purpose: a term is text you typed, and if it were attached before substitution a term that happened to contain a variable name could rewrite the prompt around it.

## A finished request [#a-finished-request]

Two paragraphs from an English article, translating into Simplified Chinese, on the **Default** prompt with AI Smart Context off. The system prompt that goes out:

```text
You are a professional Simplified Mandarin Chinese native translator who needs to fluently translate text into Simplified Mandarin Chinese.

## Translation Rules
1. Output only the translated content, without explanations or additional content ...
2. The returned translation must maintain exactly the same number of paragraphs and format as the original text.
3. If the text contains HTML tags, consider where the tags should be placed in the translation while maintaining fluency.
4. For content that should not be translated (such as proper nouns, code, etc.), keep the original text.

## Document Metadata for Context Awareness
Webpage title: Why your timestamps are eight hours off — devblog
Webpage summary: No summary available

## Multi-paragraph Translation Rules
1. If input contains a standalone line containing only %%, use a standalone %% line in your output ...
2. **CRITICAL**: Treat %% as a separator only when it appears on its own line ...

## OUTPUT FORMAT:
- **Single paragraph input** → Output translation directly (no separators, no extra text)
- **Multi-paragraph input** → Put %% on its own line between translations

## Already-translated Input Rule
Output only {{NO_TRANSLATION_NEEDED}} when only non-translatable names, brands, handles, URLs, numbers, or code differ from Simplified Mandarin Chinese. A foreign-language phrase or clause must be translated.
```

And the prompt:

```text
Translate to Simplified Mandarin Chinese:


Every timestamp you store without a zone is a bug waiting for a plane ticket.

%%

The fix is boring: store UTC, render local, and never let the two meet in a database column.
```

Note the two blank lines after the colon — they come from the prompt field itself, which is `Translate to {{targetLanguage}}:` followed by two blank lines and `{{input}}`.

## Reading the reply [#reading-the-reply]

### 1. Trim and split [#1-trim-and-split]

The reply is trimmed, then split on lines that contain nothing but `%%`. Each piece is trimmed again and lines up with the paragraph that sat in the same position of the request. A `%%` inside a sentence, a code sample or a quotation is not a separator — only a line that holds nothing else.

### 2. Check the count [#2-check-the-count]

Read Frog expects exactly as many pieces as it sent. A mismatch is a hard failure of the whole group, not a partial success: the request is retried up to three times with a growing delay, and if it still does not line up, every paragraph in the group is re-sent on its own. That is slower and costs more, which is why a prompt that encourages commentary or merged paragraphs is expensive rather than merely untidy.

### 3. Resolve "nothing to translate" [#3-resolve-nothing-to-translate]

`{{NO_TRANSLATION_NEEDED}}` is the answer the model is told to give for a paragraph already written in your target language. When a piece is exactly that marker, Read Frog treats the translation as empty, and an empty translation renders nothing — in bilingual mode no second line appears under that paragraph, and in translation-only mode the original stays visible.

The marker is stored in the cache as-is, so a paragraph settled this way is not re-sent on the next visit. It is deliberately shaped like a variable: variable substitution only replaces the names it knows, so the marker survives prompt assembly untouched and reaches the model spelled the same way every time.

### 4. Discard a translation that says nothing [#4-discard-a-translation-that-says-nothing]

A model handed same-language text often echoes it back with cosmetic differences instead of using the marker — reflowed spaces, straight quotes turned curly, full-width punctuation. Read Frog compares the reply with the source after folding those differences away, and if they match it treats the result as empty too. This is why some paragraphs on a mixed-language page show no translation even though a request was made for them.

### 5. Verify the markers [#5-verify-the-markers]

If the text carried `data-rf-attr` markers, the reply must return each one exactly once, on the same kind of element. A marker that is missing, duplicated, invented or moved to a different tag fails that paragraph rather than rendering a link pointing somewhere else.

Numbered formula placeholders are checked more gently. A reply that loses or duplicates one is still shown — the missing formulas are appended — but it is **not** written to the cache, so the next visit gets a fresh attempt instead of a permanently degraded paragraph.

### 6. Store it [#6-store-it]

What survives is written to the translation cache, and the page is updated.

## The cache key [#the-cache-key]

A cached translation is keyed on, among other things, **the finished system prompt and the finished prompt** — after the rule blocks, after substitution, after the glossary.

That has three consequences worth knowing:

* **Editing a prompt orphans every translation made with the old one.** Pages you have already read will be translated, and paid for, again.
* **Changing your glossary orphans only the paragraphs that contained a matched term.** A paragraph that matched nothing produces a prompt byte-for-byte identical to having no glossary at all, so its cache entry survives.
* **Turning AI Smart Context on or off changes every key**, because the summary variable changes — from a real summary to `No summary available` or back.

Clearing the cache from **Options → Translation** removes stored translations and page summaries. It does not touch your prompts, providers or glossaries.


# Prompt Variables (/en/docs/page-translation/prompts/variables)



A variable is written `{{name}}`. Just before a request is sent, Read Frog replaces each known variable with a string. Nothing else is touched: an unknown name such as `{{url}}` is left in the prompt as the literal characters `{{url}}`.

The examples below all come from one page — an English article at `https://devblog.example.com/posts/timestamps`, being translated into Simplified Chinese.

## Which variables exist where [#which-variables-exist-where]

| Variable             | Page prompts | Subtitle prompts |
| -------------------- | ------------ | ---------------- |
| `{{targetLanguage}}` | Yes          | Yes              |
| `{{input}}`          | Yes          | Yes              |
| `{{webTitle}}`       | Yes          | Yes              |
| `{{webDescription}}` | Yes          | Yes              |
| `{{webContent}}`     | Yes          | —                |
| `{{webSummary}}`     | Yes          | —                |
| `{{videoSummary}}`   | —            | Yes              |

A page prompt that uses `{{videoSummary}}`, or a subtitle prompt that uses `{{webContent}}`, keeps the literal text. The variable buttons under each editor field only offer the ones that list can fill.

## `{{targetLanguage}}` [#targetlanguage]

The English name of the language you are translating into — not a code, and not translated into your interface language.

```text
Simplified Mandarin Chinese
```

Other examples: `English`, `Traditional Mandarin Chinese`, `Japanese`, `Spanish`. So a prompt written as `Translate to {{targetLanguage}}:` arrives as `Translate to Simplified Mandarin Chinese:`.

## `{{input}}` [#input]

The text to translate. This is the one variable a prompt cannot do without.

**One paragraph at a time** — leading and trailing whitespace removed, invisible characters stripped:

```text
Every timestamp you store without a zone is a bug waiting for a plane ticket.
```

**Several paragraphs at once**, which is what happens on an LLM provider with batch translation on. The paragraphs are joined with a line containing nothing but `%%`, with a blank line either side:

```text
Every timestamp you store without a zone is a bug waiting for a plane ticket.

%%

The fix is boring: store UTC, render local, and never let the two meet in a database column.

%%

Ordering by a naive timestamp works until the clocks change, and then it works wrongly.
```

The model is expected to return the same number of paragraphs in the same order, separated the same way. Read Frog splits the reply back apart on those `%%` lines. If you rewrite the prompt in a way that changes the separator, or asks for the paragraphs numbered or merged, the split fails and the whole batch is retried and then re-sent one paragraph at a time.

**With HTML**, when the paragraph contains inline markup. Attributes that must survive are stripped out and the element is tagged with `data-rf-attr`, so the model sees a marker instead of a URL:

```html
The fix is <a data-rf-attr="0">boring</a>: store <code data-rf-attr="1">UTC</code>, render local.
```

**With a formula or inline symbol**, which is replaced by a numbered placeholder and cloned back into the translation afterwards:

```text
Converting is just {{0}}, which is why nobody gets it wrong twice.
```

<Callout type="info">
  You will not usually see these two shapes while writing a prompt, but they explain the extra rule
  blocks that appear in a request: Read Frog appends instructions about `data-rf-attr` and about
  numbered placeholders only when the text being sent actually contains one.
</Callout>

## `{{webTitle}}` [#webtitle]

The page's `<title>`, exactly as the browser tab shows it.

```text
Why your timestamps are eight hours off — devblog
```

In a **subtitle** prompt this is the video's title instead.

## `{{webDescription}}` [#webdescription]

The page's own description, taken from the first of `<meta name="description">`, `<meta property="og:description">` and `<meta name="twitter:description">` that has content.

```text
A short tour of the three places a naive timestamp can go wrong, and the one rule that prevents all three.
```

In a **subtitle** prompt this is the video's description.

## `{{webContent}}` [#webcontent]

The page's main body, extracted as Markdown and cut to the **first 2000 characters**. Navigation, sidebars and footers are dropped. No built-in prompt uses it — it is there for prompts that need more than a title to work with.

```text
# Why your timestamps are eight hours off

Every timestamp you store without a zone is a bug waiting for a plane ticket.
It works on your laptop, it works in CI, and it fails the first time somebody
in another country opens the report.

## Three places it goes wrong

1. **At the boundary.** A form posts `2026-03-14 09:00` and the server decides
   what that means.
2. **In the column.** `timestamp without time zone` is not a moment in time; it
   is a picture of a wall clock.
3. **On the way out.** Formatting in UTC and labelling it local is the same bug
   wearing a hat.

The fix is boring: store UTC, render local, and never let the tw
```

<Callout type="warn">
  The cut is a plain character count, not a sentence or paragraph boundary, so the value usually
  ends mid-word — as it does above. A prompt that tells the model the content is complete will be
  wrong on any page longer than a couple of screens.
</Callout>

## `{{webSummary}}` [#websummary]

A summary of the page written by your LLM provider — a separate model call, cached per page, made once and reused for every paragraph.

```text
A technical blog post arguing that timestamps should be stored in UTC and rendered in the reader's local zone. It identifies three failure points — form input, database column type, and output formatting — and recommends a single rule for all three. Written for backend developers; uses PostgreSQL column types as examples.
```

This requires **AI Smart Context** (Options → Translation). With it off, there is no summary to insert and the variable becomes the fallback string below. The default prompt uses `{{webSummary}}`, so leaving Smart Context off means the default system prompt always reads `Webpage summary: No summary available`.

## `{{videoSummary}}` [#videosummary]

The subtitle equivalent: a summary of the video, also behind AI Smart Context, also the fallback string when it is off.

```text
A conference talk on time zone handling in web applications. The speaker walks through a production incident caused by naive timestamps, then demonstrates a UTC-in, local-out pattern. Names mentioned: PostgreSQL, Temporal, Luxon.
```

## When a value is missing [#when-a-value-is-missing]

A variable is never left empty and never disappears. If the value is missing, or blank, or whitespace only, Read Frog substitutes a fixed English sentence:

| Variable                             | Substituted instead        |
| ------------------------------------ | -------------------------- |
| `{{webTitle}}`                       | `No title available`       |
| `{{webDescription}}`                 | `No description available` |
| `{{webContent}}`                     | `No content available`     |
| `{{webSummary}}`, `{{videoSummary}}` | `No summary available`     |

So the default system prompt, on a page with no metadata and Smart Context off, arrives like this:

```text
## Document Metadata for Context Awareness
Webpage title: No title available
Webpage summary: No summary available
```

<Callout type="warn">
  This matters most if you write few-shot examples. A prompt that shows the model a worked example
  built from the page title will, on a page without one, show it an example about a page called "No
  title available" — and models will translate or comment on that sentence. If your prompt leans on
  a metadata variable, say in the prompt itself what to do when the value reads "No ... available".
</Callout>

There is no fallback for `{{input}}` or `{{targetLanguage}}`. `{{targetLanguage}}` always has a value, and `{{input}}` is the paragraph — a request is never sent for empty text.

## What happens next [#what-happens-next]

The substituted text is not the whole request: extra rule blocks and your glossary terms are appended afterwards, and the finished result becomes the translation cache key. See [How a request is assembled](/docs/page-translation/prompts/pipeline).


# Custom Translation Styles (/en/docs/page-translation/style)



## Overview [#overview]

Read Frog allows you to customize how translations appear on webpages using your own CSS styles. This gives you complete control over colors, backgrounds, borders, animations, and more.

You can apply styles globally to all translations, or target specific languages and text directions. For example, you can use different fonts for Chinese, Japanese, and Korean translations, or adjust layout for right-to-left languages like Arabic and Hebrew.

## Enabling Custom CSS [#enabling-custom-css]

1. Open Read Frog settings
2. Navigate to **Translation** → **Translation Display Style**
3. Toggle &#x2A;*"Use Custom Style"** to ON
4. The CSS editor will appear with a default template

## CSS Selectors [#css-selectors]

### Basic Selector [#basic-selector]

All custom styles must target the specific selector:

```css
[data-read-frog-custom-translation-style="custom"] {
  /* Your styles here */
}
```

This selector applies to all translated text elements on the page.

### Wrapper Selector [#wrapper-selector]

Translated content is wrapped in a container with language and direction attributes:

```html
<span class="read-frog-translated-content-wrapper" lang="zh" dir="ltr">
  <span data-read-frog-custom-translation-style="custom">神谷先生...</span>
</span>
```

You can target specific languages or directions:

```css
/* Target Chinese translations */
.read-frog-translated-content-wrapper[lang="zh"]
  [data-read-frog-custom-translation-style="custom"] {
  /* Styles for Chinese */
}

/* Target RTL languages */
.read-frog-translated-content-wrapper[dir="rtl"]
  [data-read-frog-custom-translation-style="custom"] {
  /* Styles for right-to-left text */
}
```

## Editor Features [#editor-features]

### Syntax Highlighting [#syntax-highlighting]

The editor uses CodeMirror 6, providing:

* Color-coded CSS syntax
* Line numbers
* Code folding for large stylesheets
* Auto-indentation

### Color Picker [#color-picker]

Click any color value in the editor to open an interactive color picker:

1. Click on color values like `#FF5733`, `rgb(255, 87, 51)`, or `hsl(9, 100%, 60%)`
2. Visual picker appears instantly
3. Adjust using sliders or input fields
4. Changes update in real-time

Supported color formats:

* Hex: `#FF5733`
* RGB/RGBA: `rgba(255, 87, 51, 0.8)`
* HSL/HSLA: `hsla(9, 100%, 60%, 0.8)`
* Named colors: `tomato`, `skyblue`, `gold`
* CSS variables: `var(--my-color)`

### Live Validation [#live-validation]

The editor validates your CSS before saving:

* **Valid (Green)**: CSS is syntactically correct, ready to save
* **Validating (Gray)**: Checking your changes (500ms debounce)
* **Error (Red)**: Syntax error detected with error message

Validation checks:

* Syntax errors (typos, missing brackets)
* Property name validity
* Selector correctness
* Size limits (8KB maximum)

## Basic CSS Examples [#basic-css-examples]

### Simple Font Color [#simple-font-color]

```css
[data-read-frog-custom-translation-style="custom"] {
  color: blue;
}
```

<CSSStylePreview
  cssCode="`[data-read-frog-custom-translation-style='custom'] {
color: blue;
}`"
/>

### With Border [#with-border]

```css
[data-read-frog-custom-translation-style="custom"] {
  color: #414535;
  background-color: #f2e3bc;
  padding: 2px 4px;
  border-radius: 4px;
  border-left: 3px solid #ffd700;
}
```

<CSSStylePreview
  cssCode="`[data-read-frog-custom-translation-style='custom'] {
color: #414535;
background-color: #F2E3BC;
padding: 2px 4px;
border-radius: 4px;
border-left: 3px solid #FFD700;
}`"
/>

### Bold Study Mode [#bold-study-mode]

```css
[data-read-frog-custom-translation-style="custom"] {
  background-color: #fff59d;
  color: #000;
  font-weight: 600;
  border: 2px solid #ffd54f;
  padding: 6px 10px;
  border-radius: 4px;
}
```

<CSSStylePreview
  cssCode="`[data-read-frog-custom-translation-style='custom'] {
background-color: #FFF59D;
color: #000;
font-weight: 600;
border: 2px solid #FFD54F;
padding: 6px 10px;
border-radius: 4px;
}`"
/>

## Advanced Techniques [#advanced-techniques]

### Custom Fonts [#custom-fonts]

Change the font for all translations:

```css
[data-read-frog-custom-translation-style="custom"] {
  font-family: "Georgia", "Times New Roman", serif;
  font-size: 16px;
  color: #2c3e50;
}
```

<CSSStylePreview
  cssCode="`[data-read-frog-custom-translation-style='custom'] {
font-family: &#x22;Georgia&#x22;, &#x22;Times New Roman&#x22;, serif;
font-size: 16px;
color: #2c3e50;
}`"
/>

### Language-Specific Styling [#language-specific-styling]

Target translations in specific languages using the wrapper's `lang` attribute:

```css
/* Chinese translations with traditional serif font */
.read-frog-translated-content-wrapper[lang="zh"]
  [data-read-frog-custom-translation-style="custom"] {
  font-family: "Kaiti SC", "STKaiti", "KaiTi", "华文楷体", serif;
  color: #8b4513;
}

/* Japanese translations */
.read-frog-translated-content-wrapper[lang="ja"]
  [data-read-frog-custom-translation-style="custom"] {
  font-family: "Hiragino Mincho ProN", "Yu Mincho", serif;
}

/* Korean translations */
.read-frog-translated-content-wrapper[lang="ko"]
  [data-read-frog-custom-translation-style="custom"] {
  font-family: "Nanum Myeongjo", "Batang", serif;
}
```

<CSSStylePreview
  cssCode="`.read-frog-translated-content-wrapper[lang='zh'] [data-read-frog-custom-translation-style='custom'] {
font-family: &#x22;Kaiti SC&#x22;, &#x22;STKaiti&#x22;, &#x22;KaiTi&#x22;, &#x22;华文楷体&#x22;, serif;
color: #8B4513;
}`"
/>

### Direction-Specific Styling [#direction-specific-styling]

Style translations based on text direction (useful for RTL languages like Arabic, Hebrew):

```css
/* Right-to-left languages */
.read-frog-translated-content-wrapper[dir="rtl"]
  [data-read-frog-custom-translation-style="custom"] {
  border-right: 3px solid #9c27b0;
  border-left: none;
  padding-right: 10px;
  font-family: "Traditional Arabic", "Arial", sans-serif;
  font-size: 15px;
}

/* Left-to-right languages */
.read-frog-translated-content-wrapper[dir="ltr"]
  [data-read-frog-custom-translation-style="custom"] {
  border-left: 3px solid #2196f3;
  padding-left: 10px;
}
```

<CSSStylePreview
  cssCode="`.read-frog-translated-content-wrapper[dir='rtl'] [data-read-frog-custom-translation-style='custom'] {
border-right: 3px solid #9C27B0;
border-left: none;
padding-right: 10px;
font-family: &#x22;Traditional Arabic&#x22;, &#x22;Arial&#x22;, sans-serif;
font-size: 15px;
}`"
  direction="rtl"
  language="ar"
  translatedText="السيد كاميا لا يواجه العالم؛ إنه يواجه شيئًا قد يجعل العالم يلتفت."
/>

### CSS Variables [#css-variables]

Define reusable values:

```css
[data-read-frog-custom-translation-style="custom"] {
  --highlight-color: #ffe082;
  --border-color: #ffa726;

  background-color: var(--highlight-color);
  border-left: 4px solid var(--border-color);
  padding: 4px 10px;
}
```

<CSSStylePreview
  cssCode="`[data-read-frog-custom-translation-style='custom'] {
--highlight-color: #FFE082;
--border-color: #FFA726;

background-color: var(--highlight-color);
border-left: 4px solid var(--border-color);
padding: 4px 10px;
}`"
/>

### Light/Dark Mode Support [#lightdark-mode-support]

Use `light-dark()` function for automatic theme adaptation:

```css
[data-read-frog-custom-translation-style="custom"] {
  background-color: light-dark(#fff9c4, #4a4a2a);
  color: light-dark(#333, #e0e0e0);
  border: 1px solid light-dark(#ffd54f, #8d7b3a);
  padding: 5px 10px;
  border-radius: 4px;
}
```

<CSSStylePreview
  cssCode="`[data-read-frog-custom-translation-style='custom'] {
background-color: light-dark(#FFF9C4, #4A4A2A);
color: light-dark(#333, #E0E0E0);
border: 1px solid light-dark(#FFD54F, #8D7B3A);
padding: 5px 10px;
border-radius: 4px;
}`"
/>

### Hover Effects [#hover-effects]

```css
[data-read-frog-custom-translation-style="custom"] {
  color: #0277bd;
  transition:
    color 0.2s ease-out,
    transform 0.2s ease-out;
}
[data-read-frog-custom-translation-style="custom"]:hover {
  color: #01579b;
  transform: translateX(2px);
}
```

<CSSStylePreview
  cssCode="`[data-read-frog-custom-translation-style='custom'] {
color: #0277BD;
transition: color 0.2s ease-out, transform 0.2s ease-out;
}
[data-read-frog-custom-translation-style='custom']:hover {
color: #01579B;
transform: translateX(2px);
}`"
/>

### Animations [#animations]

```css
[data-read-frog-custom-translation-style="custom"] {
  background: linear-gradient(90deg, #1fe5e1 0%, #a855f7 50%, #0ad6ff 100%);
  background-size: 200% 100%;
  -webkit-background-clip: text;
  background-clip: text;
  -webkit-text-fill-color: transparent;
  animation: gradient-shift 2s ease-in-out infinite;
}

@keyframes gradient-shift {
  0%,
  100% {
    background-position: 0% 50%;
  }
  50% {
    background-position: 100% 50%;
  }
}
```

<CSSStylePreview
  cssCode="`[data-read-frog-custom-translation-style=&#x22;custom&#x22;] {
background: linear-gradient(90deg, #1fe5e1 0%, #a855f7 50%, #0ad6ff 100%);
background-size: 200% 100%;
-webkit-background-clip: text;
background-clip: text;
-webkit-text-fill-color: transparent;
color: transparent;
animation: gradient-shift 2s ease-in-out infinite;
}

@keyframes gradient-shift {
0%, 100% {
background-position: 0% 50%;
}
50% {
background-position: 100% 50%;
}
}`"
/>

## Best Practices [#best-practices]

### Do's ✅ [#dos-]

* Start with simple styles and add complexity gradually
* Test on multiple websites
* Use low-opacity backgrounds to maintain readability
* Include units for length values: `padding: 10px` not `padding: 10`
* Use complete hex codes: `#FF5733` not `#FF`

### Don'ts ❌ [#donts-]

* Avoid `!important` (selector specificity is already high)
* Don't write overly complex styles (focus on essential properties)
* Don't exceed 8KB size limit
* Avoid missing units or incomplete color codes

## Common Properties [#common-properties]

| Property           | Purpose          | Example                            |
| ------------------ | ---------------- | ---------------------------------- |
| `color`            | Text color       | `color: #333;`                     |
| `background-color` | Background color | `background-color: #FFF59D;`       |
| `padding`          | Inner spacing    | `padding: 4px 8px;`                |
| `border`           | Border style     | `border: 1px solid #FFD54F;`       |
| `border-radius`    | Rounded corners  | `border-radius: 4px;`              |
| `font-weight`      | Text boldness    | `font-weight: 600;`                |
| `font-size`        | Text size        | `font-size: 14px;`                 |
| `text-decoration`  | Underline, etc.  | `text-decoration: underline;`      |
| `opacity`          | Transparency     | `opacity: 0.8;`                    |
| `transition`       | Animation timing | `transition: color 0.2s ease-out;` |

## Technical Limitations [#technical-limitations]

* **Maximum size**: 8KB (8,192 characters)
* **Editor**: CodeMirror 6
* **Validation**: CSS Tree parser
* **Selector**: Must use `[data-read-frog-custom-translation-style='custom']`
* **Wrapper class**: Translations are wrapped in `.read-frog-translated-content-wrapper` with `lang` and `dir` attributes
* **Available attributes**: `lang` (ISO 639-1 language codes) and `dir` (ltr/rtl)

## Learning CSS [#learning-css]

If you're new to CSS, these resources will help:

### Beginner Tutorials [#beginner-tutorials]

* [MDN CSS Basics](https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps) - Comprehensive introduction
* [W3Schools CSS Tutorial](https://www.w3schools.com/css/) - Interactive examples
* [CSS-Tricks Guides](https://css-tricks.com/guides/) - Practical CSS techniques

### CSS Properties Reference [#css-properties-reference]

* [MDN CSS Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference) - Complete property documentation
* [CSS Values and Units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units) - Understanding units (px, %, em, etc.)

### Colors [#colors]

* [MDN Color Values](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) - Color formats explained
* [Coolors](https://coolors.co/) - Color palette generator
* [Color Hunt](https://colorhunt.co/) - Color scheme inspiration

### Interactive Practice [#interactive-practice]

* [CSS Diner](https://flukeout.github.io/) - Learn CSS selectors through games
* [Flexbox Froggy](https://flexboxfroggy.com/) - Learn layout (though not needed for basic styling)

## Troubleshooting [#troubleshooting]

### Style Not Applying [#style-not-applying]

1. Check validation status (must be green "Valid")
2. Verify selector is exactly `[data-read-frog-custom-translation-style='custom']`
3. Ensure "Use Custom Style" is toggled ON
4. Refresh the webpage after saving

### Syntax Errors [#syntax-errors]

Common mistakes:

* Missing semicolon: `color: red` → `color: red;`
* Missing unit: `padding: 10` → `padding: 10px`
* Incomplete color: `#FF` → `#FF5733`
* Invalid property: `colour: red` → `color: red`

### Style Conflicts [#style-conflicts]

If styles look unexpected:

* Check if website's CSS is overriding yours
* Increase specificity if needed (though usually not required)
* Test on different websites to identify site-specific issues


# Translation Control (/en/docs/page-translation/translation-control)





Open **Options → Translation → Translation control → Manage controls**.

Six rows live here, and together they answer one question: without you pressing anything, what does Read Frog translate?

<img alt="The Translation control page: the two website lists, the two language rows, the small-paragraph thresholds, and site rules" src="__img0" />

<Callout type="warn">
  None of this decides whether Read Frog may run on a site at all. That is [Site
  Control](/docs/site-control), under **Options → Preferences → Extension activation**. A site
  excluded there has no Read Frog on it to start anything, and adding it here changes nothing.
</Callout>

## Starting by website [#starting-by-website]

Two lists, both taking URL patterns.

| List                                      | What it does                                                                |
| ----------------------------------------- | --------------------------------------------------------------------------- |
| **Auto translate based on website**       | These sites start translating as soon as they open                          |
| **Never auto translate based on website** | These sites never translate on their own, even when a language rule matches |

The never-list is checked first and wins outright. If a page matches both, or matches the never-list while its language is also on your auto-translate language list, nothing starts. It is the way to carve one site out of a rule you otherwise want.

Both lists use the same URL patterns as the rest of Read Frog, so `example.com` means that exact host, and `*.example.com` covers the subdomains and the apex together. A fresh install ships `*.news.ycombinator.com` in the auto-translate list as an example you can delete.

When you use the popup's per-site toggle instead of typing a pattern, Read Frog stores `*.host` for you — you pointed at a site, not at one hostname.

## Starting by language [#starting-by-language]

**Auto translate based on language** starts translation when the page's detected language is one you listed. This is the rule for "translate Japanese pages, wherever they are", as opposed to naming the sites.

It depends on detection actually producing an answer: a page whose language cannot be determined matches no language rule, and one detected as something you did not list is left alone. Detection itself — local or on an LLM — is configured under **Options → API Providers → Language detection**.

## Skipping paragraphs [#skipping-paragraphs]

The two rows above start a translation. The next three decide which paragraphs it leaves out once it is running.

**Auto skip based on language** takes a list of languages. A paragraph detected as one of them is skipped rather than sent — useful on a page that is already part in a language you read.

Under it is a separate switch for the target language: **skip paragraphs already in the target language, without sending a request**. It is on by default, and it is what stops a bilingual page from having its translated half translated again.

Both run a local detector on each paragraph, never a model request, and both decline to guess on short text: skipping by the target language needs at least 50 characters, skipping by your listed languages at least 10. Anything shorter is translated rather than risk a wrong skip.

**Small paragraph filter** is two thresholds, a minimum character count and a minimum word count. Text below either one stays untranslated. Both default to `0`, which means nothing is filtered by length until you set it. A matching [site rule](/docs/site-rules) can override the thresholds for one website.

<Callout type="tip">
  The thresholds are the first place to look when one short line on a page refuses to translate, and
  the filters apply to [hover translation](/docs/page-translation/hover-translation) too — pointing
  at a paragraph does not exempt it.
</Callout>

## Per-site DOM behaviour [#per-site-dom-behaviour]

The last row leads to [Site Rules](/docs/site-rules), which is a different kind of control again: not whether to translate a page, but how to walk it — which elements to treat as content, which to leave alone, and which thresholds to override. Built-in rules ship with the extension and you can add your own.

## Which control to reach for [#which-control-to-reach-for]

| You want                                  | Use                                                                  |
| ----------------------------------------- | -------------------------------------------------------------------- |
| Read Frog absent from a site entirely     | [Site Control](/docs/site-control)                                   |
| A site translated the moment it opens     | Auto translate based on website                                      |
| One site exempt from your automatic rules | Never auto translate based on website                                |
| Every page in a given language translated | Auto translate based on language                                     |
| Half of a bilingual page left as it is    | Auto skip based on language                                          |
| Menus and labels left untranslated        | Small paragraph filter, or **Translation range** set to main content |
| One site's layout handled differently     | [Site Rules](/docs/site-rules)                                       |


# Privacy and Your Data (/en/docs/privacy-and-data)



Read Frog sits between you and whichever translation provider you choose, so the honest answer to "where does my reading go" depends on which provider that is. This page says what leaves your browser, and to whom.

## What stays in your browser [#what-stays-in-your-browser]

Your settings live in the browser profile's extension storage and are never uploaded unless you ask for it:

* providers and API keys;
* target language, translation mode and range;
* custom prompts, custom CSS, glossaries, Custom AI Actions;
* the auto-translate lists and Site Control;
* the translation cache.

Signing in does not change this. Configuration only leaves the profile when you [export it or start a Google Drive sync](/docs/config-backup) yourself.

<Callout type="warn">
  An export that includes API keys is a credential file. Anyone who gets it can spend your provider
  quota. Exclude keys unless you are moving your own configuration through storage you trust.
</Callout>

## What is sent to a translation provider [#what-is-sent-to-a-translation-provider]

To translate a paragraph, that paragraph has to be sent somewhere. Which text is sent, and how much of it, depends on the prompt in use — [Prompt Variables](/docs/page-translation/prompts/variables) shows exactly what each request carries, including the page title, description and the first 2000 characters of page content when your prompt asks for them.

The provider is the one you configured, called with your key, under that provider's own privacy policy. Read Frog does not proxy those requests and does not see their contents — **except** when the provider is one of Read Frog's own built-in options, where the request goes to Read Frog's server so the allowance described in [Account and Plans](/docs/account-and-plans) can be counted.

If you would rather nothing left your machine at all, run a local model through [Ollama](/docs/providers/ollama) or [LM Studio](/docs/providers/lm-studio). Those requests go to `localhost`.

<Callout type="tip">
  AI Smart Context sends a summary of the surrounding page along with each paragraph, so it sends
  more than the paragraph alone. Turn it off on pages you would rather not send in bulk.
</Callout>

## What Read Frog itself receives [#what-read-frog-itself-receives]

**Usage events.** The extension reports that a feature ran, not what it ran on. Each event carries the feature name, the surface it was triggered from, the kind of provider (an LLM or a plain translation API, and which one), whether it succeeded, how long it took, and for a Custom AI Action its id and name. &#x2A;*No page URL, no page content, no translated text, and no API key is included.**

**Your account, if you have one.** A [Notebase](/docs/notebase) is stored on the server by design — that is what makes review and statistics work across devices. What lands there is whatever a Custom AI Action saved, which is usually a word, a definition and the sentence it came from.

**Nothing, if you do not sign in.** Translation works fully signed out, and nothing about your notes exists to store.

## Local files and site access [#local-files-and-site-access]

The extension requests access to all sites because a translation extension that only worked on a list of sites would not be much use. You can narrow that yourself with [Site Control](/docs/site-control), which stops Read Frog running on the sites you exclude.

Reading local files needs a separate permission you grant explicitly in the browser's extension settings; see [Translate Local Web Pages](/docs/local-files).

## Deleting things [#deleting-things]

* **A notebase and its cards** — delete them in the web app; see [Managing Notes](/docs/notebase/manage).
* **Your whole account** — account settings on the website, covered in [Account and Plans](/docs/account-and-plans). Not reversible.
* **Local settings** — Reset in [Configuration, Sync & Backups](/docs/config-backup), or uninstall the extension, which removes the profile's extension storage with it.
* **Cached translations** — Clear cache on the Page Translation and Video Subtitles screens.

The authoritative statements are the [privacy policy](https://readfrog.app/privacy-policy) and [terms of service](https://readfrog.app/terms-of-service); this page describes how the software behaves.


# Built-in Provider Configuration (/en/docs/providers/built-in-providers)



## Add a built-in provider [#add-a-built-in-provider]

Open **Options → API Providers**, choose **Add Provider**, select a built-in provider, enter its API key when required, choose a model if the provider exposes one, and enable it. Use **Test Connection** before selecting the provider for translation, subtitles, or an AI feature.

Translation providers such as Google Translate, Microsoft Translator, DeepL, and DeepLX are suitable for translation features. LLM providers also support AI Smart Context, custom prompts, subtitle AI segmentation, and Custom AI Actions. Custom AI Actions and Notebase structured results require a model with reliable structured output.

## Keep configuration current [#keep-configuration-current]

Provider catalogs, model IDs, quota policies, and supported options change often. Select models from the extension UI or fetch them from a provider when that control is available; do not rely on a documentation list of default models. Use the provider's official documentation for pricing, regions, quotas, and API-key creation.

If a response is malformed, test the connection, confirm the selected model and API key, and review provider-specific options. Disable reasoning output when the provider exposes it and the model adds reasoning text before a structured response.


# DeepL (/en/docs/providers/deepl)



## What is DeepL? [#what-is-deepl]

DeepL is the official paid translation API from DeepL. In Read Frog, it is separate from DeepLX:

* **DeepL** uses DeepL's official API and requires a valid DeepL API key.
* **DeepLX** is an unofficial DeepL-like API with customizable Base URL behavior.

If you want the official DeepL service, choose **DeepL** in the API Providers page.

## How Read Frog Configures DeepL [#how-read-frog-configures-deepl]

DeepL setup in Read Frog is intentionally simple:

* **API Key**: required
* **Base URL**: not shown and not configurable

Read Frog decides the correct DeepL endpoint from your API key automatically:

* Keys ending with `:fx` use `https://api-free.deepl.com`
* All other keys use `https://api.deepl.com`

You do not need to manually choose between Free and Pro endpoints.

## Setting Up DeepL in Read Frog [#setting-up-deepl-in-read-frog]

1. Open the Read Frog extension options.
2. Go to **API Providers**.
3. Select **Official DeepL API**.
4. Paste your DeepL API key into the **API Key** field.
5. Test a translation.

That is all you need. There is no Base URL field for DeepL.

## Free vs Pro DeepL Keys [#free-vs-pro-deepl-keys]

Read Frog uses the API key format to decide which DeepL endpoint to call.

### DeepL Free [#deepl-free]

If your key ends with `:fx`, Read Frog sends requests to:

```text
https://api-free.deepl.com/v2/translate
```

### DeepL Pro [#deepl-pro]

If your key does not end with `:fx`, Read Frog sends requests to:

```text
https://api.deepl.com/v2/translate
```

## Language Handling [#language-handling]

Read Frog adapts some language codes automatically for DeepL:

* Target `zh` becomes `ZH-HANS`
* Target `zh-TW` becomes `ZH-HANT`
* Source `zh-TW` is normalized to `ZH`
* When source language is set to `auto`, Read Frog lets DeepL detect it automatically

## Troubleshooting [#troubleshooting]

### "DeepL API key is not configured" [#deepl-api-key-is-not-configured]

Your API key field is empty. Add a valid DeepL API key in the provider settings.

### "DeepL translation request failed" [#deepl-translation-request-failed]

Usually this means one of the following:

* The API key is invalid
* The API key type does not match your DeepL plan
* The DeepL service rejected the request

### Free key not working [#free-key-not-working]

Make sure your DeepL Free key still ends with `:fx`. Read Frog uses that suffix to select the Free API endpoint.

## When to Use DeepL vs DeepLX [#when-to-use-deepl-vs-deeplx]

Choose **DeepL** if you want:

* The official DeepL API
* Automatic Free/Pro endpoint handling
* A simpler setup with only an API key

Choose **DeepLX** if you want:

* A custom or self-hosted DeepLX provider
* Custom Base URL patterns
* `{{apiKey}}` placeholder support inside the URL


# DeepLX (/en/docs/providers/deeplx)



## What is DeepLX? [#what-is-deeplx]

DeepLX is a free, unofficial API that provides DeepL-like translation quality through reverse engineering. It offers an alternative to the official DeepL API for developers who need high-quality translation services without the cost.

## Flexible BaseURL Configuration [#flexible-baseurl-configuration]

Read Frog supports flexible DeepLX baseURL configuration to work with different DeepLX providers. You can customize the baseURL to match your provider's specific endpoint format.

### Token Placeholder Support [#token-placeholder-support]

You can use the `{{apiKey}}` placeholder in your baseURL to insert your API token at any position. This is useful when different DeepLX providers require tokens in different URL formats.

**Examples:**

1. **Token in path**: `https://api.deeplx.com/{{apiKey}}/translate`
2. **Token as query parameter**: `https://api.deeplx.com/v1/translate?token={{apiKey}}`
3. **Token in subdomain**: `https://{{apiKey}}.api.deeplx.com/translate`

### Special URL Handling [#special-url-handling]

#### Standard DeepLX URLs [#standard-deeplx-urls]

For most DeepLX providers, if your baseURL doesn't end with `/translate`, Read Frog will automatically append it:

* **Input**: `https://deeplx.example.com`
* **Output**: `https://deeplx.example.com/translate`

With API token:

* **Input**: `https://deeplx.example.com` + token `abc123`
* **Output**: `https://deeplx.example.com/abc123/translate`

#### api.deeplx.org Special Logic [#apideeplxorg-special-logic]

For the official `https://api.deeplx.org` endpoint, Read Frog applies special logic to insert the API token between `.org` and `/translate`:

* **Without token**: `https://api.deeplx.org/translate`
* **With token**: `https://api.deeplx.org/your-token/translate`

### Configuration Examples [#configuration-examples]

#### No API Token Required [#no-api-token-required]

Some DeepLX providers don't require authentication:

```
BaseURL: https://deeplx.vercel.app
API Key: (leave empty)
Result: https://deeplx.vercel.app/translate
```

#### Token in Path [#token-in-path]

```
BaseURL: https://api.deeplx.com/{{apiKey}}
API Key: your-secret-token
Result: https://api.deeplx.com/your-secret-token/translate
```

#### Token as Query Parameter [#token-as-query-parameter]

```
BaseURL: https://api.example.com/v1/translate?key={{apiKey}}
API Key: your-api-key
Result: https://api.example.com/v1/translate?key=your-api-key
```

#### Custom Endpoint with Token [#custom-endpoint-with-token]

```
BaseURL: https://deeplx.mydomain.com/api/{{apiKey}}/translate
API Key: abc123
Result: https://deeplx.mydomain.com/api/abc123/translate
```

## Setting Up DeepLX in Read Frog [#setting-up-deeplx-in-read-frog]

1. **Open Extension Options**: Click the Read Frog extension icon and go to Options
2. **Navigate to API Providers**: Go to the API Providers section
3. **Configure DeepLX**:
   * Set your **BaseURL** according to your provider's format
   * Add your **API Key** if required (leave empty for providers that don't need it)
   * Use `{{apiKey}}` placeholder if you need custom token placement
4. **Test Translation**: Try translating some text to verify the configuration works

## Common DeepLX Providers [#common-deeplx-providers]

### Free Providers (No API Key) [#free-providers-no-api-key]

* `https://deeplx.vercel.app`
* `https://deeplx.herokuapp.com`

### Paid/Self-hosted Providers [#paidself-hosted-providers]

* `https://api.deeplx.org` (requires API key)
* Your own self-hosted instance

## Troubleshooting [#troubleshooting]

### URL Construction Issues [#url-construction-issues]

If you're having issues with URL construction:

1. **Check your baseURL format**: Ensure it follows the expected pattern
2. **Verify token placement**: Make sure `{{apiKey}}` is in the correct position
3. **Test without token first**: Try with a free provider to isolate configuration issues

### Common Errors [#common-errors]

* **"API key is required when using `{{apiKey}}` placeholder"**: You specified `{{apiKey}}` in the baseURL but didn't provide an API key
* **"DeepLX translation request failed"**: Check if your baseURL and API key are correct
* **Network errors**: Verify the DeepLX provider is accessible and online

## API Response Format [#api-response-format]

DeepLX providers should return JSON responses in this format:

```json
{
  "data": "translated text here"
}
```

If you're setting up your own DeepLX instance, ensure it returns responses in this expected format.


# LM Studio (/en/docs/providers/lm-studio)









## What is LM Studio? [#what-is-lm-studio]

[LM Studio](https://lmstudio.ai/) is a desktop app for downloading, managing, and running large language models locally. Its Local Server exposes local models through an OpenAI-compatible API, so Read Frog can connect to LM Studio through an OpenAI-compatible custom provider for local translation and reading.

LM Studio's official OpenAI-compatible examples use `http://localhost:1234/v1`. The `1234` part is the Local Server port. In your own setup, always match the port configured in LM Studio's Local Server settings.

## Configure LM Studio Local Server [#configure-lm-studio-local-server]

### 1. Download and install LM Studio [#1-download-and-install-lm-studio]

Download LM Studio from the [official website](https://lmstudio.ai/), install it, and download a model that fits your hardware.

For translation, a smaller and faster model is usually better. For Read Frog's reading, summary, or structured-output features, choose a model that supports structured output.

### 2. Start Local Server [#2-start-local-server]

In LM Studio, open **Developer** -> **Local Server**, make sure a model is loaded, then start the server.

You can also start the server with the LM Studio CLI:

```bash
lms server start --port 1234 --cors
```

If you use another port in the UI, such as `3000`, the Base URL in Read Frog must also be changed to `http://localhost:3000/v1`.

### 3. Configure Server Settings [#3-configure-server-settings]

In **Developer** -> **Local Server** -> **Server Settings**, the recommended setup is:

<img alt="LM Studio Local Server settings" src="__img0" />

| Setting                             | Recommended value          | Notes                                                                                                                                                           |
| ----------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Server Port                         | `1234` or your custom port | The Base URL port must match this value                                                                                                                         |
| Require Authentication              | On                         | Recommended, especially when CORS or LAN access is enabled; after enabling it, Read Frog must use an LM Studio API Token as the API Key to connect successfully |
| Enable CORS                         | On                         | Browser extensions need cross-origin access to the local server                                                                                                 |
| Serve on Local Network              | Off by default             | Only enable it when other devices need access; require authentication if enabled                                                                                |
| Allow per-request MCPs              | Off by default             | Read Frog translation and reading do not need MCP unless you explicitly use it                                                                                  |
| Allow calling servers from mcp.json | Off by default             | This may let API clients call local MCP servers and is usually unnecessary                                                                                      |

<Callout type="warn">
  After CORS is enabled, websites or extensions from other origins can access the LM Studio API. It
  is strongly recommended to enable **Require Authentication** and only configure the API token in
  tools you trust.
</Callout>

### 4. Create an API Token [#4-create-an-api-token]

Open **Server Settings**, enable **Require Authentication**, then click **Manage Tokens** to create a new API Token.

Copy the token immediately after creation. LM Studio only shows it once. Then paste this token into Read Frog's API Key field.

It is recommended to always enable authentication and paste a real LM Studio API Token into Read Frog. This prevents unauthorized clients from calling your local server when CORS or LAN access is enabled.

## Configure LM Studio in Read Frog [#configure-lm-studio-in-read-frog]

### 1. Open the API Providers page [#1-open-the-api-providers-page]

1. Click the Read Frog extension icon in the browser toolbar
2. Click **Options**
3. Open the API Providers / model provider settings page
4. Add an OpenAI-compatible custom provider

<img alt="Read Frog LM Studio provider configuration" src="__img1" />

### 2. Fill in connection settings [#2-fill-in-connection-settings]

If your LM Studio Local Server uses the default `1234` port:

```json
{
  "baseURL": "http://localhost:1234/v1",
  "apiKey": "Paste the API Token created in LM Studio",
  "model": "Select a model with Read Frog's Fetch Models action"
}
```

If your Local Server port is not `1234`, update the Base URL:

```json
{
  "baseURL": "http://localhost:XXXXX/v1"
}
```

After configuring the Base URL and API Key, click **Fetch Models** in Read Frog to read the model list exposed by LM Studio Local Server, then select the model you want to use.

If you need to verify the model list manually, you can also use:

```bash
curl http://localhost:1234/v1/models \
  -H "Authorization: Bearer YOUR_LM_STUDIO_TOKEN"
```

If authentication is disabled, remove the `Authorization` header.

### 3. Test the connection [#3-test-the-connection]

After saving the provider, click **Test Connection**. If it fails, check:

* LM Studio Local Server is running
* Base URL ends with `/v1`
* The port matches the Server Port in LM Studio
* Enable CORS is turned on
* If Require Authentication is enabled, the API Key is your LM Studio token
* The loaded model identifier is correct

## Disable Thinking Mode [#disable-thinking-mode]

Some models support thinking / reasoning mode, such as Qwen models. When enabled, the model may output reasoning content before the final answer. This can be useful for chat, but it can interfere with Read Frog's structured output and prevent translation information from being returned correctly.

If translation contains reasoning text, output format becomes unstable, or JSON parsing fails, disable it in LM Studio:

<img alt="Disable Enable Thinking in LM Studio" src="__img2" />

1. Open the configuration panel for the loaded model
2. Go to **Model Parameters** -> **Custom Fields**
3. Turn off **Enable Thinking**
4. Save it as a no-thinking preset
5. Reload the model or apply the configuration when prompted

The exact field name may vary by model. If you do not see **Enable Thinking**, the current model or runtime may not expose this option.

## Troubleshooting [#troubleshooting]

### Browser extension cannot connect [#browser-extension-cannot-connect]

Make sure Local Server is running and **Enable CORS** is turned on. Browser extensions usually need CORS support when calling a local `localhost` service.

### 401 or authentication errors [#401-or-authentication-errors]

If **Require Authentication** is enabled, requests must include `Authorization: Bearer <token>`. In Read Frog, paste the LM Studio token into the API Key field.

### Port cannot be reached [#port-cannot-be-reached]

`http://localhost:1234/v1` only works when the server port is `1234`. If you configured another Server Port in LM Studio, update the Base URL accordingly.

### LAN devices cannot access the server [#lan-devices-cannot-access-the-server]

If another device needs to access LM Studio, enable **Serve on Local Network** and use the LAN IP of the machine running LM Studio, such as `http://192.168.1.10:1234/v1`. This increases exposure, so **Require Authentication** should also be enabled.

### Reading output has invalid format [#reading-output-has-invalid-format]

Try disabling Thinking mode first, then switch to a model with better structured-output support. Some open-source models have weaker JSON-format reliability and may require a different model or simpler output requirements.

## References [#references]

* [LM Studio Server Settings](https://lmstudio.ai/docs/developer/core/server/settings)
* [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication)
* [LM Studio OpenAI Compatibility](https://lmstudio.ai/docs/developer/openai-compat)
* [LM Studio CLI server start](https://lmstudio.ai/docs/cli/serve/server-start)


# Ollama (/en/docs/providers/ollama)





## What is Ollama Server? [#what-is-ollama-server]

Ollama server is a lightweight, open-source AI model runtime platform that allows users to easily deploy various large language models (LLMs) and AI models locally without complex configuration. It acts as an "AI model manager," simplifying the tedious processes of model downloading, configuration, and runtime into just a few commands—making it accessible even for AI deployment beginners.

## Ollama Local Deployment Tutorial [#ollama-local-deployment-tutorial]

### Download the Installer [#download-the-installer]

You can download the installer from [ollama.ai](https://ollama.ai/).

### Configure Ollama's Cross-Origin Support [#configure-ollamas-cross-origin-support]

Please set the following environment variables:

* Allow cross-origin access: `OLLAMA_ORIGINS=*`

  **macOS / Linux:**

  ```bash
  echo 'export OLLAMA_ORIGINS=*' >> ~/.zshrc
  source ~/.zshrc
  ```

  **Windows (PowerShell in Administrator mode):**

  ```powershell
  [System.Environment]::SetEnvironmentVariable('OLLAMA_ORIGINS', '*', 'User')
  ```

  After setting the environment variable, if you previously started the Ollama service, please close it first and then restart the `ollama serve` command. If you haven't started it yet, you can ignore this step.

* API service listening address: `OLLAMA_HOST=127.0.0.1:11434` (This is the default address and can be left unchanged, but you can modify it based on your needs)

## Common Ollama Commands [#common-ollama-commands]

### 1. Check Ollama Version and Start the Server [#1-check-ollama-version-and-start-the-server]

```bash
ollama version
ollama serve
```

Use these commands to check the currently installed Ollama version, confirm successful installation, view version details, and start the Ollama server.

### 2. Find Available Models and Install [#2-find-available-models-and-install]

You can find available models from [ollama.ai](https://ollama.ai/) and install them.

```bash
ollama pull [model-name]
```

For example, to install the `gemma3:4b` model:

```bash
ollama pull gemma3:4b
```

### 3. List Downloaded Models [#3-list-downloaded-models]

```bash
ollama list
```

This command displays all locally downloaded models, including names, sizes, and creation times, to help users manage local model resources.

### 4. Start the Service [#4-start-the-service]

```bash
ollama serve
```

### 5. Configure Ollama Provider in the Extension [#5-configure-ollama-provider-in-the-extension]

In the extension settings, configure the Ollama provider and select a model.

<img alt="Ollama Provider" src="__img0" />

If you did not change the default address, you can leave baseURL blank or set it to `http://127.0.0.1:11434`.

If you changed the default address, you need to set the baseURL to the address you changed.

```json
{
  "baseURL": "http://127.0.0.1:XXXXX/api"
}
```

You can click the "Test Connection" button to verify if the connection is successful.

### 6. Notes [#6-notes]

* Do not start Ollama Chat graphical client, it will compete with `ollama serve` for the port.
* When configuring the Ollama provider in the extension, the baseURL defaults to `http://127.0.0.1:11434`, if your `OLLAMA_HOST` is this address, you can leave it unchanged.

## Troubleshooting [#troubleshooting]

### Windows: 403 Error When Connecting to Ollama [#windows-403-error-when-connecting-to-ollama]

If you encounter a 403 error when the extension tries to connect to Ollama on Windows, it may be caused by running PowerShell (or the terminal) with administrator privileges. The elevated permissions can prevent the extension from properly accessing the Ollama service.

**Solution:** Close the administrator PowerShell and restart `ollama serve` in a regular (non-administrator) PowerShell window.


# OpenAI-Compatible Custom Providers (/en/docs/providers/openai-compatible-providers)



## Configure an endpoint [#configure-an-endpoint]

In **Options → API Providers**, add an OpenAI-compatible provider, enter the Base URL, API key, and a model identifier, then enable it and use **Test Connection**. The endpoint must be reachable from the browser extension and implement the API operations used by the selected Read Frog feature.

Use custom headers only when your service requires them, and keep secrets out of exported configurations. A custom model can translate text without supporting every AI feature. Custom AI Actions, Notebase structured results, and some context-aware workflows need reliable structured output; test those workflows separately from a simple translation.

## Troubleshooting [#troubleshooting]

For authentication or network failures, verify the Base URL, API key, CORS/proxy policy, and provider account limits. For malformed structured output, choose a model with stronger JSON or structured-output support and disable reasoning output if available. Model availability and provider names change frequently, so use your provider's dashboard and the extension UI as the source of truth.


# Set Up Providers and API Keys (/en/docs/providers/overview)



## Choose the right provider [#choose-the-right-provider]

Open **Options → API Providers** and add a provider. Google Translate, Microsoft Translator, DeepL, and DeepLX are translation providers. LLM providers can translate and also power AI Smart Context, personalized prompts, subtitle AI segmentation, and Custom AI Actions. A model that supports structured output is required for Custom AI Actions and saving structured results to Notebase.

Read Frog's built-in **Free AI Service** is available for selection Custom AI Actions only; it is not a whole-page translation provider.

## Add and verify a connection [#add-and-verify-a-connection]

Choose a built-in provider or an OpenAI-compatible custom endpoint, enter its API key and required connection options, select or fetch a model where the provider supports it, then enable the provider. Use **Test Connection** before assigning it to a feature. Keep API keys private and remove them before sharing an exported configuration.

Custom endpoints may need a Base URL, custom headers, or provider-specific options. Reasoning output can interfere with structured responses on some models; disable it when a provider offers that control and a Custom AI Action or translation response is malformed.

## Next steps [#next-steps]

Use the provider-specific guides for [built-in providers](/docs/providers/built-in-providers), [OpenAI-compatible endpoints](/docs/providers/openai-compatible-providers), [DeepL](/docs/providers/deepl), [DeepLX](/docs/providers/deeplx), [Ollama](/docs/providers/ollama), or [LM Studio](/docs/providers/lm-studio). Provider catalogs and model availability change frequently, so use the API Providers screen as the current source of truth.


# Pure Translation Providers (/en/docs/providers/pure-translation-providers)



## What a pure translation provider is [#what-a-pure-translation-provider-is]

A pure translation provider does one thing: you send it text, it sends back a translation. There is no model to pick, no prompt to write, and no conversation. Read Frog groups these under **Pure translation providers** in **Options → API Providers → Add Provider**.

An LLM provider translates by being asked to translate. That extra step is what makes page context, your own prompt wording and your glossary possible — and it is also why it costs more tokens and usually takes longer.

## What they cannot do [#what-they-cannot-do]

Pure translation providers can be assigned to page translation, video subtitles, selection toolbar translation and input translation. They cannot carry anything that depends on a prompt:

* **AI Smart Context** has no prompt to enrich, so the setting does nothing for these providers.
* **Personalized translation prompts** are greyed out in the popup when the selected provider is not an LLM.
* **Custom AI Actions** and note suggestion require an LLM provider and will not accept one of these.
* **Subtitle AI segmentation** is skipped; subtitles are translated cue by cue as they arrive.
* **Glossary terms are ignored.** The glossary travels inside the system prompt, so it only reaches LLM translation.

<Callout type="warn">
  If your glossary suddenly stops taking effect on a page, check which provider that feature is
  using. Each feature picks its own provider, so page translation can be on DeepL while your
  selection toolbar is still on an LLM.
</Callout>

## The providers in this group [#the-providers-in-this-group]

### DeepL [#deepl]

The official DeepL API. It needs an **API Key** and nothing else — there is no Base URL field, because Read Frog picks the Free or Pro endpoint from the shape of your key. See [DeepL](/docs/providers/deepl) for the details and its language-code handling.

### DeepLX [#deeplx]

An unofficial DeepL-compatible API. It needs a **Base URL**, and an API key only if your instance asks for one, so a free public instance works with the key field left empty. The Base URL may contain an `{{apiKey}}` placeholder when your provider expects the token somewhere other than the path. See [DeepLX](/docs/providers/deeplx).

### Google Translate and Microsoft Translator [#google-translate-and-microsoft-translator]

These belong to the same family but need no setup at all: they ship already added and enabled, have no credentials to fill in, and cannot be removed. You will not find them in the **Add Provider** dialog for that reason.

<Callout type="info">
  Microsoft Translator cannot be paired with Translation Only page mode. Its endpoint does not
  preserve markup, so Read Frog blocks that combination instead of letting it corrupt the page.
</Callout>

## Add and enable one [#add-and-enable-one]

<Steps>
  <Step>
    Open the Read Frog options and go to 

    **API Providers**

    .
  </Step>

  <Step>
    Click **Add Provider** and pick a provider from the **Pure translation providers** group.
  </Step>

  <Step>
    Fill in the fields that provider shows — an API key for DeepL, a Base URL (and optionally a key)
    for DeepLX.
  </Step>

  <Step>
    Use 

    **Test Connection**

     next to the API Key field and wait for the result.
  </Step>

  <Step>
    Turn on the **Enabled** switch, then assign the provider to a feature under **Feature
    providers**.
  </Step>
</Steps>

A provider that is added but not enabled will not appear in the feature pickers. Assigning it to a feature from its own editor enables it for you.

## Testing the connection [#testing-the-connection]

**Test Connection** is not a ping — it translates the word `Hi` through your real settings, so a green check means this exact configuration produced a translation.

* A green check means success; an hourglass means it worked but took longer than three seconds.
* A red cross means the request failed. The reason is not shown on the button, so try a translation on a real page to see the error text.
* The button is disabled while the API key field is empty, except for DeepLX, which is allowed to run without a key.
* The result clears after a few seconds, and resets as soon as you edit the provider, the key or the URL — so a stale check never vouches for a configuration you have since changed.

## When to pick one of these [#when-to-pick-one-of-these]

Choose a pure translation provider when:

* You translate long pages or full subtitle tracks and want the lowest latency per request.
* You want predictable cost. DeepL bills characters, not tokens, and a free DeepL key or a public DeepLX instance costs nothing.
* Your LLM quota is scarce and you would rather spend it on Custom AI Actions than on bulk page translation.

Stay on an LLM provider when:

* You rely on a glossary, a personalized prompt or AI Smart Context.
* The text needs judgement rather than literal accuracy — idioms, jokes, domain jargon.
* You want one provider to serve both translation and the AI features, instead of maintaining two.

A good middle ground is to run page translation on a pure translation provider and keep the selection toolbar on an LLM, so the fast path is cheap and the careful path is still available on the words you stop to look at.

## Troubleshooting [#troubleshooting]

### "DeepL API key is not configured" [#deepl-api-key-is-not-configured]

The API Key field is empty. DeepL has no keyless mode.

### "DeepL translation request failed" or "DeepLX translation request failed" [#deepl-translation-request-failed-or-deeplx-translation-request-failed]

The provider answered with an error status. Read Frog appends the status code and the provider's own error body to this message, which is usually the fastest thing to read. Common causes are an invalid or expired key, a key that does not match the plan, and an exhausted character quota.

### "API key is required when using `{{apiKey}}` placeholder in DeepLX baseURL" [#api-key-is-required-when-using-apikey-placeholder-in-deeplx-baseurl]

Your Base URL contains the placeholder but the API Key field is empty. Either fill in the key or remove the placeholder from the URL.

### "Unexpected response format from DeepLX translation API" [#unexpected-response-format-from-deeplx-translation-api]

The request succeeded but the body was not what a DeepLX instance returns. Read Frog expects JSON with the translation in a `data` string field. Public instances that have been repurposed or put behind a login page often fail here.

### "Network error during DeepL/DeepLX translation" [#network-error-during-deepldeeplx-translation]

The request never reached the server: the instance is offline, the host does not resolve, or its CORS headers reject the extension. Self-hosted instances must be reachable from the browser, not only from your terminal.

### Translations are fine but my terms are wrong [#translations-are-fine-but-my-terms-are-wrong]

That is expected on these providers — see What they cannot do above. Move that feature to an LLM provider if the glossary matters more than the speed.

## Related pages [#related-pages]

[Providers overview](/docs/providers/overview) · [DeepL](/docs/providers/deepl) · [DeepLX](/docs/providers/deeplx) · [Built-in providers](/docs/providers/built-in-providers) · [OpenAI-compatible providers](/docs/providers/openai-compatible-providers)


# Request Control & Batch Translation (/en/docs/request-control)





Open **Options → Translation → Request Control** to tune webpage request pacing. Video subtitles have an independent copy of these settings under **Options → Video Subtitles**.

## Defaults at a glance [#defaults-at-a-glance]

| Setting                      | Default | Applies to                                     |
| ---------------------------- | ------: | ---------------------------------------------- |
| Average Requests Per Second  |     `8` | All provider requests in that translation flow |
| Maximum Burst Request Count  |    `60` | All provider requests in that translation flow |
| Maximum Characters Per Batch |  `1000` | LLM providers only                             |
| Maximum Paragraphs Per Batch |     `4` | LLM providers only                             |

## How the Token Bucket works [#how-the-token-bucket-works]

Read Frog uses a continuously refilled Token Bucket:

1. The bucket starts full with **Maximum Burst Request Count** tokens.
2. Starting one queued request consumes one token.
3. **Average Requests Per Second** adds tokens continuously until the bucket is full again.
4. Whenever tokens are available, due requests can start.

This distinction matters: **burst capacity is not a concurrency limit**. With the default capacity of `60`, a fresh bucket may immediately release up to 60 queued requests. The system does not promise that only 60 network requests will be in flight at once.

Decimal rates are valid. A rate of `0.25` adds one token every four seconds; `0.5` adds one every two seconds.

<Callout type="warn">
  Do not copy a provider's “requests per minute” number directly into the per-second field. Divide
  it by 60, then consider whether that provider also limits short bursts.
</Callout>

## Choosing rate and burst capacity [#choosing-rate-and-burst-capacity]

Match the sustained rate first, then choose how much initial traffic the provider accepts.

| Provider quota example                  | Conservative starting point                                   |
| --------------------------------------- | ------------------------------------------------------------- |
| 60 requests/minute, no documented burst | rate `1`, capacity `1`                                        |
| 15 requests/minute                      | rate `0.25`, capacity `1`                                     |
| 1 request every 10 seconds              | rate `0.1`, capacity `1`                                      |
| High-throughput local model             | keep `8` / `60`, then tune after observing latency and memory |

If you receive HTTP 429 or quota errors, set capacity to `1` first and lower the rate to the provider's sustained limit. Increasing batching may reduce request count for LLMs, but it does not make an excessive burst safe.

## When LLM batching runs [#when-llm-batching-runs]

Batch translation is used only when the selected provider is recognized as an LLM provider. Ordinary translation services continue sending their normal requests even when batch limits are visible.

Compatible items share a batch when they have the same provider, source language, target language, and context. A batch is sent when any of these happens:

* adding another item would exceed the character limit;
* the paragraph/segment count reaches its limit;
* the character count reaches its limit;
* the short collection window (about `100` ms) expires.

The `1000`-character and `4`-paragraph defaults balance request savings with predictable structured output. Larger batches can lower request overhead, but a slow or malformed result affects more paragraphs and may exceed a model or gateway limit.

## Structured results, retries, and fallback [#structured-results-retries-and-fallback]

Read Frog expects one translated result for each source item in an LLM batch. If the model returns the wrong number of items, Read Frog retries that malformed batch up to three times, then falls back to individual translations for those items. Normal request failures are also handled by the request queue's retry policy; they are not the same as a batch-count mismatch.

Duplicate in-flight items are deduplicated, and successful translations can be reused from cache. The **Statistics** page compares original paragraph requests with actual batched requests so you can confirm whether batching helps on your sites.

<img alt="Batch request savings shown on the Statistics page" src="__img0" />

## Practical presets [#practical-presets]

### Strict free tier [#strict-free-tier]

* rate: the provider's documented per-second rate, often `0.1`–`1`;
* burst capacity: `1`;
* maximum characters: `600`–`1000`;
* maximum paragraphs: `2`–`4`.

### Fragile structured-output model [#fragile-structured-output-model]

Keep rate within quota, then reduce batches to `500`–`800` characters and `2` paragraphs. This trades request savings for more reliable one-to-one output.

### Fast local model [#fast-local-model]

Start with the defaults. Increase batch size gradually while watching response time, memory use, and malformed batch fallbacks. A large burst can still overload a local server even when no remote quota exists.

## Page and subtitle settings are separate [#page-and-subtitle-settings-are-separate]

Page translation and video subtitles do not share a bucket or batch configuration. Tune each workload under its own settings page. Subtitle traffic is often more time-sensitive, while webpage translation can tolerate a slower conservative rate.


# The Review Session (/en/docs/review)











A review session is one notebase at a time. Open the notebase and click **Review** in the top right.

<img alt="The Review button on a notebase page" src="__img0" />

Two things can happen instead of a session starting:

* With no notes, the button is disabled and says **Add a note to start reviewing**.
* With notes but no card template, it takes you to the template editor first. Create the template and the session begins right after — the button there reads **Create & start reviewing**.

## Answering a card [#answering-a-card]

<Steps>
  <Step>
    **Read the front and try to recall the answer**

    The card shows its template's name at the top, the front below it, and **Answer hidden** where the back will be.

        <img alt="A review card showing only its front" src="__img1" />
  </Step>

  <Step>
    **Reveal the answer**

    Click **Reveal Answer** or press <kbd>Space</kbd>. The back appears, and an **Edit** button appears with it — you can fix the note without leaving the session.

        <img alt="The same card with the back revealed" src="__img2" />
  </Step>

  <Step>
    **Say how it went**

    Four buttons, each showing the interval it would schedule.

        <img alt="The four grade buttons with their intervals" src="__img3" />
  </Step>
</Steps>

## The four grades [#the-four-grades]

The number above each button is the real interval that answer would produce for this card, computed from its own history. It is not a fixed ladder — the same four buttons offer different intervals on different cards.

| Grade     | Key          | Say this when                                                                                                                                                                        |
| --------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Again** | <kbd>1</kbd> | You did not recall it. The card comes back within minutes, and on a card that had reached real intervals it counts as a lapse — see [How Scheduling Works](/docs/review/scheduling). |
| **Hard**  | <kbd>2</kbd> | You got there, but slowly or with a wrong first guess.                                                                                                                               |
| **Good**  | <kbd>3</kbd> | You recalled it without much effort. This is the answer to reach for.                                                                                                                |
| **Easy**  | <kbd>4</kbd> | It was instant and the interval felt too short.                                                                                                                                      |

<kbd>Space</kbd> does double duty: it reveals the answer, and once the answer is shown it grades
**Good**. Holding a key down does nothing extra — each press registers once, so you cannot reveal
and grade in one accidental keystroke.

Answer honestly rather than generously. The grade is the only thing the scheduler knows about how the card actually went, and [the schedule it builds](/docs/review/scheduling) is only as good as that input.

## The header [#the-header]

| Control                          | What it does                                                                                |
| -------------------------------- | ------------------------------------------------------------------------------------------- |
| **Synced** / **Syncing**         | Whether your last answer has reached the server. Answers queue locally and sync behind you. |
| Three counts, e.g. `12 + 3 + 41` | What is **left** today: new, then learning, then review. Not what you have done.            |
| **Undo**                         | Reverses the last thing you did to a card.                                                  |
| **⋮**                            | **Skip today** and **Suspend card**.                                                        |

The three counts fall as you work, and the middle one can go back up: grading a new card **Again** moves it into learning, where it is waiting for its next step in the same session.

### Undo [#undo]

**Undo** or <kbd>Mod</kbd> + <kbd>Z</kbd> steps back one action at a time — a grade, a skip, or a suspend — restoring the card and the due date it had beforehand. Press it repeatedly to walk back through the session you are in. It does not reach into earlier sessions, and an answer that has already been superseded by a newer one on the same card is refused rather than silently applied.

### Skip today and Suspend [#skip-today-and-suspend]

Both live in the &#x2A;*⋮** menu, and both are for cards, not for the session.

* **Skip today** (<kbd>=</kbd>) puts this card aside until tomorrow without recording an answer. Use it when the card is fine but you have hit something you would rather not judge right now.
* **Suspend card** (<kbd>!</kbd>) takes the card out of the rotation indefinitely. Use it for a card that is wrong, duplicated, or one you have decided not to learn.

Both are reversible from the **Cards** list in **Templates & Cards**, where they show as **Skipped today** and **Suspended** with **Unskip today** and **Unsuspend** beside them.

## Done for today [#done-for-today]

When the queue empties you get **Done for today**. That means no card in this notebase is due before the study day ends — a study day runs from 04:00 to 04:00 in your timezone, so a late-evening session and the next morning's are the same day.

It does not always mean you have finished everything. A daily limit can end a day early, and so can having every remaining card scheduled for a later date. [Study Settings](/docs/review/study-settings) covers both.

## Where to go next [#where-to-go-next]

* [Study Settings](/docs/review/study-settings) — daily limits and target retention, per notebase
* [How Scheduling Works](/docs/review/scheduling) — why the intervals look the way they do


# How Scheduling Works (/en/docs/review/scheduling)



Read Frog schedules with **FSRS**, an open-source spaced-repetition algorithm. This page is about what it is doing and why, not about which numbers to set — for those, see [Study Settings](/docs/review/study-settings).

## Three numbers per card [#three-numbers-per-card]

FSRS keeps a small model of your memory of each card, and it is made of three quantities.

* **Stability** — how long this card stays learned. Concretely, how many days can pass before your chance of recalling it drops to about 90%. A new card has stability measured in minutes; a card you have known for a year has stability measured in months.
* **Difficulty** — how hard this particular card is for you. It rises when you answer **Again** or **Hard**, falls slowly when you answer **Easy**, and it governs how much each successful review is worth: a difficult card's stability grows more slowly than an easy one's.
* **Retrievability** — the chance you would recall the card *right now*. It starts near certain after a review and decays from there, faster on a low-stability card.

Only stability and difficulty are stored. Retrievability is computed from them and from how long it has been since you last saw the card.

## Where the interval comes from [#where-the-interval-comes-from]

The next due date is the moment your retrievability for that card is predicted to fall to the **memory retention** you asked for — 90% by default.

That single sentence explains most of the behaviour you will notice:

* The interval is not a multiplier on the last one. It is recomputed from the card's new stability each time.
* Raising target retention shortens every interval, because the predicted curve reaches a higher number sooner.
* A card whose stability barely moved gets barely more time than last time, however patiently you keep answering **Good**.

Your answer is what moves stability. **Good** on a card you recalled after a long gap moves it a great deal — the long gap is itself the evidence that the memory was strong. The same **Good** ten minutes after the last look moves it very little, because recalling something you just read proves almost nothing.

That is also why **Again**, **Hard**, **Good** and **Easy** are worth using honestly rather than kindly. They are the entire input. A card you always mark **Good** while actually struggling gets intervals built for someone who knows it.

## The first day, and going wrong [#the-first-day-and-going-wrong]

A brand-new card does not get days at all. It walks two short steps in the same session — about a minute, then about ten — so you see it a few times before it leaves for a real interval. This is what the **learning** count in the session header is: cards partway through those steps.

Answering **Again** on a card that had reached real intervals is a **lapse**. The card drops back to a ten-minute step, its stability falls, and its difficulty rises. It then climbs again from a lower base, which is why one forgotten card can cost several weeks of apparent progress.

A card that keeps lapsing eventually stops being worth the room it takes. After **eight lapses**, Read Frog suspends it automatically and it leaves the rotation. You will find it under **Suspended** in the notebase's **Cards** list. A card that gets there is usually asking to be rewritten rather than re-learned: split it, add context to the front, or drop it.

## Why two cards differ so much [#why-two-cards-differ-so-much]

Everything above is per card, so two cards you created on the same day diverge as soon as their histories do. Beyond that, three rules shape what you see:

* **The four intervals are always ordered.** Easy is never shorter than Good, Good never shorter than Hard. The numbers above the grade buttons are real previews for this card, and they will never invert.
* **Intervals are capped**, at 100 years — high enough that you will not meet the cap.
* **Intervals are not jittered.** Some schedulers add a little randomness to stop cards created together from staying together. Read Frog does not, so two cards with genuinely identical histories get genuinely identical dates.

## The optimizer [#the-optimizer]

FSRS ships with default parameters fitted to a large body of other people's reviews. Your memory, your material and your grading habits are not that average, so Read Frog retrains the model on your own history, per notebase.

A training run works on a notebase's review log and produces a candidate set of parameters. It keeps the candidate only if it predicts your actual answers better than the parameters currently in use — measured on how well each one would have predicted reviews it was not fitted on, so a set that merely memorises your history does not win. The same run also recomputes recommended learning and relearning steps from the same data.

Roughly when it happens:

* A notebase becomes eligible once about **64 of its cards** have come back after a real interval. Reviews concentrated on a handful of cards do not count for much here — the model needs breadth, not volume.
* After that, it retrains once another **64 or so reviews** have accumulated.
* Runs happen on the server, about once a week. Nothing to start, and nothing to wait for.

When a run has changed something, a notification appears on the notebase list: *the new review schedule better reflects your memory patterns*, with how much better it scored and how many review records it learned from. Dismiss it and carry on; your existing due dates are not rewritten, and the new parameters apply from your next answer onward.

<Callout type="info">
  Until a notebase reaches that threshold it runs on the defaults, and the defaults are good. There
  is nothing to configure and nothing to fix — a young notebase is simply scheduled by other
  people's averages for a while.
</Callout>

## Looking at one card [#looking-at-one-card]

In **Templates & Cards**, every card has a **View memory** button. It opens that card's forgetting curve — the decay from its last review, where it sits now, where the due date falls, and your target retention as a line across it — above the full review history with the grade, the elapsed time and the stability before each answer.

It is the honest way to settle an argument with the schedule. A card that feels overdue usually turns out to have a stability you had over-estimated, and one whose interval looks absurdly long usually earned it.

## Across a notebase [#across-a-notebase]

The **Statistics** tab on a notebase, and the **Statistics** page across all of them, plot reviews per day, time spent, and **long-term memory growth** — the number of cards whose stability has passed 21 days. That last one is the closest thing to a measure of progress here: not how much you have saved, and not how much you have reviewed, but how much has actually settled.


# Study Settings (/en/docs/review/study-settings)



Study settings belong to a notebase, not to your account. A 300-word exam list and a slow-burning notebase of reading notes can run at completely different paces.

## Where they are [#where-they-are]

Go to [readfrog.app/home](https://readfrog.app/home), open the **Actions** menu on the notebase's row, and choose **Options**. Three fields, and that is the whole of it.

## Daily limits [#daily-limits]

**New cards per day** and **Review cards per day** cap how many of each the session hands you in one study day. `-1` means unlimited, which is what both start as.

The two limits are counted separately and independently. Hitting the new-card limit does not stop reviews from coming, and vice versa.

What counts against a limit is the first answer you give a card that day. Undoing an answer gives the allowance back, and a card you skip or suspend never spends any.

### Which one to set [#which-one-to-set]

**Review cards per day** is the honest brake. Reviews are what a backlog is made of, and a cap here is what keeps a day you cannot finish from turning into a week you cannot start.

**New cards per day** is the one that decides the size of that backlog weeks from now. Every new card you take on today becomes roughly ten reviews spread over the following months. If you are saving words faster than you can keep up with them, this is the number to bring down — long before you touch the review cap.

<Callout type="tip">
  A limit does not lose cards; it defers them. Cards over the limit stay due and come back the next
  day, so a week of 20-a-day on a notebase producing 40 a day quietly builds a queue. When **Done
  for today** keeps arriving early and the queue keeps growing, the new-card limit is too high, not
  too low.
</Callout>

## Memory retention [#memory-retention]

**Memory retention** is your target: the chance you want of recalling a card at the moment it next comes up. The default is `90%`, and the accepted range is `30%` to `100%`.

It is the one knob that changes the intervals themselves rather than how many you see. Ask for more retention and every interval shortens, so you remember more and review more. Ask for less and intervals stretch, so you review less and forget more.

| Setting     | Effect                                                                                        |
| ----------- | --------------------------------------------------------------------------------------------- |
| Above `90%` | Noticeably more reviews for a small gain. Worth it for a deadline, not for a habit.           |
| `90%`       | The default, and a good balance for most material.                                            |
| `80–85%`    | Fewer reviews, more forgotten cards to re-learn. Reasonable for a large, low-stakes notebase. |
| Below `80%` | You will meet **Again** often enough that the lapses cost more than the savings.              |

Changing it takes effect on your next answer for each card; it does not rewrite due dates that already exist.

## The study day [#the-study-day]

Everything above is measured in **study days**, and a study day runs from **04:00 to 04:00** in your timezone. A session at 1 a.m. belongs to the previous day, which is the point: a late night does not silently consume tomorrow's allowance.

Your timezone comes from **Settings → Preferences → Language & time → Timezone**. It is worth checking once if you have travelled or if your reviews seem to reset at an odd hour.

## One card per note per day [#one-card-per-note-per-day]

This one is not configurable, and it is the setting people look for and do not find.

If a note has several cards — because the notebase has several card templates — only one of them comes up on a given day. Answer it and the note's other cards step aside until tomorrow. Two templates therefore do not double your daily load on the same material.

## What you cannot change here [#what-you-cannot-change-here]

The scheduler has more parameters than these three. They are stored per notebase but are not exposed in the interface, and they hold values chosen to be sensible:

| Parameter        | Value                | What it is                                                             |
| ---------------- | -------------------- | ---------------------------------------------------------------------- |
| Learning steps   | 1 minute, 10 minutes | The same-session steps a new card walks before it gets a real interval |
| Relearning step  | 10 minutes           | Where a lapsed card restarts                                           |
| Maximum interval | 36,500 days          | The ceiling on any one interval — effectively none                     |
| Leech threshold  | 8 lapses             | After this many lapses a card is suspended automatically               |
| Interval fuzz    | Off                  | Whether intervals are jittered to spread future days apart             |

The learning and relearning steps are not fixed forever, though: the optimizer recomputes them from your own review history along with the rest of the memory model. [How Scheduling Works](/docs/review/scheduling) explains what it does and when.


# Selection Translation (/en/docs/selection-translation)





Select some text, and a small toolbar appears next to it. Its **Translate** button sends that selection off to be translated and opens a panel beside it, where the translation arrives word by word.

Nothing on the page is replaced. This is the reading gesture for a phrase you want to look at closely — a sentence, a quote, a term — not for the article around it.

<img alt="The selection toolbar over a selected phrase, with its Translate, Speak and Dictionary buttons" src="__img0" />

## Three ways in [#three-ways-in]

| How                                  | What it needs                                                             |
| ------------------------------------ | ------------------------------------------------------------------------- |
| The toolbar's **Translate** button   | The toolbar enabled, and the Translate action switched on                 |
| <kbd>Alt</kbd> + <kbd>T</kbd>        | A selection. Without one you get an error toast instead of an empty panel |
| Right-click → &#x2A;*Translate "…"** | The context menu entry point switched on                                  |

All three open the same panel and run the same request. The shortcut is ignored while your cursor sits in a text box, so it will not fire as you type; you can change it on the [Shortcuts](/docs/shortcuts) page.

Which buttons the toolbar carries, and where it is allowed to appear at all, are covered in [Entry Points](/docs/entry-points).

## What the panel gives you [#what-the-panel-gives-you]

The translation streams in rather than landing all at once, so a long selection starts reading before it has finished. On a reasoning model, the model's thinking is shown above the result while it works.

Above the result sits the text you selected, so you can compare the two without turning back to the page. Under it, once there is something to act on, are a **copy** button and a **speak** button that reads the translation aloud with your [Text to Speech](/docs/tts) voice.

The header carries a target-language selector. Changing it retranslates immediately — and it is your real target language, the same one page translation uses, not a setting local to this panel.

The header also has a **pin**. A pinned panel keeps its position and size, and reuses itself for your next selection instead of reopening somewhere else.

In the footer are three controls: the provider in use, a **regenerate** button that runs the request again, and a button that shows the page context being sent along — the page title, and the paragraphs the selection sits in.

## Which provider runs it [#which-provider-runs-it]

Selection toolbar translation has its own provider assignment, separate from page translation and subtitles. Set it in [API Providers](/docs/providers/overview), or change it from the panel's footer — that dropdown writes the assignment, so the next selection uses it too.

Both LLM providers and pure translation providers work here. What follows from the choice:

* On an **LLM provider**, your [glossary](/docs/glossary) reaches the request, and so do the prompts you manage under [Custom Prompts](/docs/page-translation/prompts) — the page-translation set, not the subtitle one.
* On a **pure translation provider** such as Google Translate or DeepL, there is no prompt to carry either of those. See [Pure Translation Providers](/docs/providers/pure-translation-providers).

AI Smart Context applies either way when it is on: the page title, description, and a summary of the page are offered to the model so a pronoun or a term in your selection can be resolved from what surrounds it. It is configured in [Translation Control](/docs/page-translation/translation-control).

## Not the same thing as hover translation [#not-the-same-thing-as-hover-translation]

These two are easy to confuse and they work differently.

|                | Selection translation                                        | [Hover translation](/docs/page-translation/hover-translation) |
| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------- |
| What it takes  | Text you have already selected                               | The paragraph under your pointer                              |
| How you start  | A button, <kbd>Alt</kbd> + <kbd>T</kbd>, or the context menu | Holding a key, or press-and-hold the mouse                    |
| Where it lands | A panel beside the selection                                 | In the page, next to the paragraph                            |
| Undo           | Close the panel                                              | Trigger the same paragraph again                              |

<Callout type="warn">
  Press-and-hold belongs to hover translation and to nothing else. Selection translation has no
  long-press trigger — it needs text you have already selected, so there is nothing for a hold to
  point at.
</Callout>

## Where to go next [#where-to-go-next]

The same panel is where [note suggestions](/docs/notebase) surface: after an AI translation finishes, Read Frog can offer the words in your selection that are worth keeping.

For the rest of the toolbar — the Dictionary button in the screenshot above, and any action you write yourself — see [Custom AI Actions](/docs/custom-actions).


# Shortcuts (/en/docs/shortcuts)





Six things in Read Frog can be triggered from the keyboard. They all live in one place: **Options → Shortcuts**.

<img alt="The Shortcuts page with six rows, each carrying its own key field" src="__img0" />

## What each one does [#what-each-one-does]

| Shortcut                  | What it triggers                                                    | Default                                          |
| ------------------------- | ------------------------------------------------------------------- | ------------------------------------------------ |
| **Page translation**      | Translates the whole page, and translates it back on a second press | <kbd>Alt</kbd> + <kbd>E</kbd>                    |
| **Translation mode**      | Switches between bilingual and translation only                     | <kbd>Alt</kbd> + <kbd>Shift</kbd> + <kbd>M</kbd> |
| **Selection translation** | Translates the text you have selected                               | <kbd>Alt</kbd> + <kbd>T</kbd>                    |
| **Subtitle translation**  | Turns translated video subtitles on or off                          | <kbd>Alt</kbd> + <kbd>C</kbd>                    |
| **Paragraph translation** | Translates the one paragraph under your pointer                     | <kbd>Ctrl</kbd> held — see below                 |
| **Translation Hub**       | Opens [Translation Hub](/docs/translation-hub) in a new tab         | <kbd>Alt</kbd> + <kbd>Shift</kbd> + <kbd>H</kbd> |

## Recording a new one [#recording-a-new-one]

Click a shortcut's field and press the combination you want. It is saved the moment you press it — there is no confirm step.

Three things are worth knowing while the field is recording:

* A shortcut needs **at least one modifier** plus one ordinary key. Pressing <kbd>T</kbd> alone records nothing and the field keeps waiting.
* <kbd>Esc</kbd> cancels and leaves the old shortcut alone.
* <kbd>Backspace</kbd> or <kbd>Delete</kbd> clears the field, which turns that shortcut off. An
  empty field is a valid state.

On macOS, <kbd>⌘</kbd> and <kbd>Ctrl</kbd> are recorded as distinct keys and displayed with their usual symbols, so a combination you record on a Mac reads the way the rest of the system does.

## Paragraph translation is the odd one [#paragraph-translation-is-the-odd-one]

Its field is a dropdown rather than a recorder, because what it takes is a single **held** key, not a combination. The five choices are <kbd>⌃ Control</kbd>, <kbd>⌥ Alt</kbd>, <kbd>⇧ Shift</kbd>, <kbd>\` backtick</kbd>, and **click and hold** — press and hold the mouse button instead of a key.

This page only sets the key. Whether the feature runs at all is a switch on the Page Translation screen. See [Hover Translation](/docs/page-translation/hover-translation) for both halves.

<Callout type="warn">
  Long press belongs to paragraph translation and nothing else. Selection translation has no
  press-and-hold variant — it needs text you have already selected.
</Callout>

## Where the keys work, and where they do not [#where-the-keys-work-and-where-they-do-not]

Every one of these is handled by Read Frog on the page itself, not registered with the browser. Two consequences follow.

They only work on pages where Read Frog is allowed to run. On a site you have excluded in [Site Control](/docs/site-control), and on the browser's own internal pages, nothing listens for them. They also stay quiet while your cursor is inside a text box, so typing <kbd>Alt</kbd> + <kbd>E</kbd> into a search field does not translate the page under it.

And `chrome://extensions/shortcuts` has nothing to show for Read Frog. There are no browser-level commands to assign there; this page is the only place shortcuts are set.

<Callout type="tip">
  If a shortcut stops working on one site, the page has probably claimed the same combination for
  itself. Record a different one here rather than fighting the site for it.
</Callout>

## Related [#related]

Input translation is triggered by three taps on the space bar rather than a shortcut — see [Input Translation](/docs/input-translation). The floating button, the selection toolbar, and the context menu are covered in [Entry Points](/docs/entry-points).


# Site Control (/en/docs/site-control)





Site control is the outermost switch Read Frog has. It decides whether the extension loads on a page in the first place — before any question of translating it comes up.

Open **Options → Preferences → Extension activation → Manage sites**.

<img alt="Extension activation: the two mode options and the URL pattern list under them" src="__img0" />

## The two modes [#the-two-modes]

**Only disable on listed sites** is the default. Read Frog runs everywhere except the addresses you list. Use it to carve out the handful of sites where the extension is in the way — your bank, an internal tool, a page whose own shortcuts you want left alone.

**Only run on listed sites** inverts that. Read Frog stays out of every site except the ones you list. Use it when you read in another language on a few known places and would rather the extension were absent everywhere else.

Each mode keeps its own list. Switching modes does not empty the list you are leaving, so you can switch back and find it intact.

## What "off" actually means [#what-off-actually-means]

On a site the current mode excludes, Read Frog's page scripts never load. That takes out everything that lives on the page at once: the floating button, the selection toolbar, [input translation](/docs/input-translation), every [shortcut](/docs/shortcuts), [hover translation](/docs/page-translation/hover-translation), and page translation itself — including any automatic translation the site would otherwise have started.

This is not the same as turning individual features off. It is the extension not being there.

## Writing patterns [#writing-patterns]

The field takes the same URL patterns as every other site list in Read Frog.

| Pattern               | Matches                                                                    |
| --------------------- | -------------------------------------------------------------------------- |
| `example.com`         | That host alone, on any path — `www.example.com` is a different host       |
| `*.example.com`       | `example.com` and every subdomain — `docs.example.com`, `mail.example.com` |
| `example.*`           | Any top-level domain — `example.com`, `example.net`, `example.co.uk`       |
| `example.com/admin/*` | Only that section of the site                                              |
| `https://example.com` | Only over HTTPS; without a scheme, both HTTP and HTTPS match               |

Ports are not supported, and neither are schemes other than `http` and `https`. A pattern that cannot be understood is dropped rather than applied loosely.

## The fast way to add a site [#the-fast-way-to-add-a-site]

You do not have to come here to exclude the page you are on. Open the Read Frog popup on it and use the site switch — it reads **Disable extension on this site** in blacklist mode and **Enable extension on this site** in whitelist mode, and it writes to whichever list the current mode uses.

## Site control is not auto-translate [#site-control-is-not-auto-translate]

This is the distinction people lose most often, so it is worth stating plainly.

| Question                                     | Where it is answered                                                                       |
| -------------------------------------------- | ------------------------------------------------------------------------------------------ |
| May Read Frog run on this site at all?       | **Site control** — this page                                                               |
| Should translation start on its own?         | Auto-translate lists, in [Translation Control](/docs/page-translation/translation-control) |
| Should this one tool appear on this site?    | The per-tool disabled lists in [Entry Points](/docs/entry-points)                          |
| Should this site's DOM be handled specially? | [Site Rules](/docs/site-rules)                                                             |

The auto-translate and never-auto-translate lists assume Read Frog is already running; all they choose is whether it starts translating without being asked. Site control comes first and overrides them: a site in your auto-translate list that is also excluded here translates nothing, because nothing of Read Frog ever loaded.

<Callout type="warn">
  Whitelist mode is easy to forget you turned on. If Read Frog seems dead everywhere — no floating
  button, no toolbar, no shortcuts — check the mode here before looking anywhere else.
</Callout>


# Site Control & Site Rules (/en/docs/site-rules)



Read Frog has two website controls with different purposes:

| Feature      | Location                 | Purpose                                                                           |
| ------------ | ------------------------ | --------------------------------------------------------------------------------- |
| Site Control | **Options → General**    | Allows or blocks the extension on whole hostnames using a blacklist or whitelist. |
| Site Rules   | **Options → Site Rules** | Changes how matching webpages are parsed, laid out, filtered, or styled.          |

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 [#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-rule-url-patterns]

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

| Pattern                     | Matches                                        |
| --------------------------- | ---------------------------------------------- |
| `github.com`                | HTTP or HTTPS pages on `github.com`            |
| `*.example.com`             | the apex host and its subdomains               |
| `docs.example.com/guides/*` | guide paths on that host                       |
| `https://example.com/*`     | HTTPS pages only                               |
| `www.amazon.*`              | matching Amazon hosts across top-level domains |
| `javdb*.com`                | hostnames with matching text after `javdb`     |

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 [#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 [#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.

| Field                        | Meaning                                          |
| ---------------------------- | ------------------------------------------------ |
| `id`                         | Stable, unique rule identifier.                  |
| `description`                | Optional human-readable purpose.                 |
| `matches` / `excludeMatches` | URL pattern or list of patterns.                 |
| `enabled`                    | Enables or disables the user rule.               |
| `excludeSelectors`           | Nodes Read Frog must not translate.              |
| `includeSelectors`           | Explicit areas Read Frog should consider.        |
| `forceBlockSelectors`        | Treat matching nodes as block content.           |
| `forceInlineSelectors`       | Keep matching nodes in the inline text flow.     |
| `preserveTextSelectors`      | Preserve matching source text.                   |
| `minCharacters` / `minWords` | Override small-paragraph filtering for the site. |
| `injectedCss`                | CSS inserted on matching pages.                  |

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

## Safe example [#safe-example]

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

```json
[
  {
    "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 [#adjusting-an-earlier-rule]

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

```json
[
  {
    "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 [#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.

<Callout type="warn">
  Injected CSS runs on every page matched by the rule. Keep patterns narrow, scope selectors to the
  target site, and avoid hiding security or account controls.
</Callout>

## Debugging checklist [#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.


# Statistics (/en/docs/statistics)



**Statistics** on [readfrog.app](https://readfrog.app) shows what your reviewing has actually produced. It covers every notebase by default; the **Notebase** filter narrows it to one, and the range selector offers the last 7 days, 30 days, 3 months, year, or all time.

## The numbers at the top [#the-numbers-at-the-top]

* **Reviews** — how many times you graded a card in the range. One card reviewed three times counts three.
* **Review time** — how long you spent, which is often the more honest number: a high review count in very little time usually means you were pressing Good without reading.
* **Active days** — days with at least one review. For spaced repetition this matters more than volume; the schedule assumes you turn up.

## Activity [#activity]

A heatmap of the last year, one square per day, darker for more activity. Under it, the same range as counts of **learned cards** and **new notes**.

The two lines answer different questions. New notes is how much you are collecting — easy to run ahead on, because saving a word takes a second. Learned cards is how much you are actually turning into memory. A heatmap that keeps growing on notes and stays pale on reviews is the usual shape of a stalled deck.

## Long-term memory growth [#long-term-memory-growth]

A card counts toward long-term memory once its scheduled interval is long enough that you are no longer relearning it. The chart tracks that count over time, with the daily change beneath.

This is the closest thing to a progress bar that spaced repetition offers. It moves slowly on purpose: a card only joins after surviving several correct recalls at widening intervals, so a burst of reviewing today shows up here weeks later. Reviews you get wrong pull cards back out of it.

## Note growth [#note-growth]

How many notes exist over time, which is the collection side rather than the memory side. Useful mainly next to the memory chart — the gap between the two lines is your backlog.

## One card's forgetting curve [#one-cards-forgetting-curve]

Open a card from its notebase to see its own memory history rather than the aggregate:

* **Memory stability** — roughly how long this card can go before recall drops to the target. It grows each time you recall the card correctly.
* **Retrievability** — the estimated chance you would recall it right now. Falls between reviews.
* **Lapses** — how many times you forgot it after having learned it. A card with many lapses is usually a card that needs rewriting, not more reviews.
* **Review history** — every grade with its time, duration, and the card's state and stability beforehand.

The chart draws three curves: the forgetting curve after your most recent review, the reference curve for a card with no review history, and your target retention. The distance between the first two is what your reviewing has bought.

<Callout type="tip">
  A card you keep forgetting is rarely a scheduling problem. It is usually two things fused into one
  card, or a definition with no sentence around it. Rewrite it — see [Managing
  Notes](/docs/notebase/manage).
</Callout>

## Where the numbers come from [#where-the-numbers-come-from]

Every grade is recorded with its rating and timing, and the scheduler derives stability and the next interval from that history — see [How Scheduling Works](/docs/review/scheduling). Nothing here is an estimate of your language level; it only describes the cards you have reviewed.

Days are bucketed in your own timezone, so a review at 1 a.m. lands on the day you experienced, not UTC's.


# Translation Hub (/en/docs/translation-hub)





Translation Hub is a full page of its own rather than a settings screen. Open it from **Options → Translation Hub**; it opens in a new tab, so your settings stay where they were.

<img alt="Translation Hub with the language selectors, the text box, and five providers listed" src="__img0" />

## What it is for [#what-it-is-for]

Page translation gives you one translation, from one provider, in place. Translation Hub does the opposite: it takes one piece of text and runs it through **several providers at once**, so you can read the results next to each other.

That makes it the right place to:

* decide which provider to assign to page translation or subtitles, using your own text instead of a benchmark;
* see how a custom prompt actually changes the output before you make it the active one;
* translate a paragraph that is not on a web page at all — something from a PDF, an email, or a chat.

## Translate something [#translate-something]

<Steps>
  <Step>
    Set **Source Language** and **Target Language**. Source defaults to `auto`, which detects the
    language from the text you paste. The arrows between the two selectors swap them.
  </Step>

  <Step>
    Open the **Translation Providers** dropdown and pick which ones take part. The badge next to it
    shows how many are currently selected, and the list on the right shows them in order; the `×` on a
    row removes it from this comparison.
  </Step>

  <Step>
    Choose a prompt from the dropdown next to the providers. It lists the same page-translation
    prompts you manage in [Prompts](/docs/page-translation/prompts) — including any you have added
    yourself — so **Default** here means the same thing it means there.
  </Step>

  <Step>
    Paste your text and press **Translate**, or use the <kbd>⌘</kbd>/<kbd>Ctrl</kbd> +{" "}
    <kbd>Enter</kbd> shortcut shown on the button. Each provider returns into its own card.
  </Step>
</Steps>

## What affects the result [#what-affects-the-result]

The prompt selector only reaches providers that can take a prompt. A pure translation provider such as Google Translate or Microsoft Translator has no prompt to receive, so it returns the same output whichever prompt is selected — that difference between the cards is expected, not a bug. See [Pure Translation Providers](/docs/providers/pure-translation-providers) for what those providers can and cannot do.

Only providers you have already added and enabled in [API Providers](/docs/providers/overview) can be selected here, and each one is called with its own credentials and quota. Comparing five providers on a long passage sends five requests.

<Callout type="tip">
  Compare on text that is actually hard — a sentence with a pronoun that needs context, a technical
  term, or an idiom. Everything translates the same easy sentence well, so easy text tells you
  nothing about which provider to pick.
</Callout>

## Where to go next [#where-to-go-next]

Once you have decided, assign the provider to the feature that should use it in [API Providers](/docs/providers/overview), and keep terminology consistent across features with a [Glossary](/docs/glossary).


# Troubleshooting (/en/docs/troubleshooting)



Each feature page has its own troubleshooting section. This page is the index: find the symptom, follow the link.

## Nothing happens at all [#nothing-happens-at-all]

| What you see                                        | Usually                                                                                                                             |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| No floating button, no toolbar, nothing on one site | The site is excluded in [Site Control](/docs/site-control)                                                                          |
| Nothing anywhere, on every site                     | The extension is disabled in the browser's extensions page                                                                          |
| The floating button is there but does nothing       | No enabled provider — check [API Providers](/docs/providers/overview)                                                               |
| The shortcut does nothing                           | Another extension or the site took the key; rebind it in [Shortcuts](/docs/shortcuts)                                               |
| Right-click menu entries do nothing                 | The site is excluded in [Site Control](/docs/site-control). The menu entries stay visible on excluded sites and silently do nothing |

## Part of the page is not translated [#part-of-the-page-is-not-translated]

Read Frog skips text on purpose more often than people expect.

* **Navigation, headers and footers stay in the original** — Translation range is set to Main Content. Change it on [Page Translation](/docs/page-translation).
* **Short lines stay in the original** — the small-paragraph filter in [Translation Control](/docs/page-translation/translation-control) has a minimum length.
* **Some paragraphs stay in the original on a mixed-language page** — language skipping decided they were already in the target language. Same page.
* **Text inside a widget, canvas or unusual element** — the content detector did not see it as text. A per-site fix belongs in [Site Rules](/docs/site-rules).
* **Nothing new translates as you scroll** — pre-translation distance, in [Request Control](/docs/request-control).

## The translation itself is wrong [#the-translation-itself-is-wrong]

* **A name or term keeps changing between paragraphs** — give it a fixed translation in the [Glossary](/docs/glossary). Note that a glossary only reaches LLM providers.
* **Correct but stilted** — try the Polished rewrite prompt, or write your own; see [Custom Prompts](/docs/page-translation/prompts).
* **Pronouns and references are wrong** — turn on AI Smart Context on [Page Translation](/docs/page-translation).
* **The reply contains instructions, labels or `%%` marks instead of a translation** — the prompt lost a placeholder or contradicts the batch rules. [How a Request Is Assembled](/docs/page-translation/prompts/pipeline) explains what the model is being asked for.
* **A paragraph came back empty** — the model decided it was already in the target language, and an empty translation renders nothing. See [How a Request Is Assembled](/docs/page-translation/prompts/pipeline), under "Resolve 'nothing to translate'".

## It is slow, or it stops partway [#it-is-slow-or-it-stops-partway]

* **Slow, or requests failing in bursts** — lower the rate and burst in [Request Control](/docs/request-control). Free provider tiers are strict.
* **Long pages stop translating partway** — same page: the queue gave up after retries. Lower the batch size.
* **Every translation is slow on a local model** — raise the batch size instead; local models pay per request, not per token.
* **Something changed after you edited a prompt** — editing a prompt discards cached translations, so the next read re-requests everything.

## Layout looks broken [#layout-looks-broken]

* **Translations overlap or push the page around** — try a different preset style, or write your own; see [Translation Style](/docs/page-translation/style).
* **Only on one site** — [Site Rules](/docs/site-rules) can override selectors and thresholds for that site alone.
* **Subtitles sit in the wrong place or overlap the player** — [Subtitle Style](/docs/video-subtitles/style).

## Subtitles [#subtitles]

* **No translate button in the player** — the video has no captions YouTube exposes, or subtitles are off in [Video Subtitles](/docs/video-subtitles).
* **Lines are cut mid-sentence** — turn on AI smart segmentation in [AI Segmentation and Subtitles Quota](/docs/video-subtitles/ai-segmentation).
* **Lines drift out of sync after turning that on** — AI segmentation sets its own timing; turn it off if drift bothers you more than the cutting did.

## Account, saving and review [#account-saving-and-review]

* **The popup still says Guest after signing in on the website** — reload the page you are on; the extension reads the session when a tab loads.
* **No way to save a result to a notebase** — the Custom AI Action has no Notebase connection, or its provider does not support structured output. See [Saving from the Extension](/docs/notebase/save-from-extension).
* **A Custom AI Action returns nothing or malformed fields** — the model does not support structured output well. Try another, or disable reasoning if the provider offers that control.
* **An assistant cannot connect over MCP** — MCP requires the Ultra plan; see [Connecting](/docs/mcp/connect).

## Nothing here matches [#nothing-here-matches]

Export your configuration **without API keys** from [Configuration, Sync & Backups](/docs/config-backup) and attach it to a [GitHub issue](https://github.com/mengxi-ream/read-frog/issues), or ask in [Discord](https://discord.gg/ej45e3PezJ). The export says which providers, prompts and rules are in play, which is usually the whole answer.


# Text to Speech (/en/docs/tts)



Open **Options → Text to Speech** to configure the voice used by Read Frog's Speak actions. TTS is currently labeled **Public Beta**, but it does not require enabling Beta Experience.

## Where speech is available [#where-speech-is-available]

The selection toolbar can show a **Speak** action for selected text. Other Read Frog surfaces may also expose speech when TTS is enabled. Translation providers do not generate the audio; Read Frog uses its Edge TTS voice configuration.

## Voice mapping [#voice-mapping]

Assign a voice to each language you regularly read. Read Frog chooses the mapping for the detected language and falls back to the default voice when no language-specific mapping exists.

Use the preview control before saving a mapping. Voice availability and quality can vary by language, operating environment, and the upstream speech service.

<Callout type="tip">
  If mixed-language text sounds wrong, add explicit mappings for both languages instead of relying
  on one default voice.
</Callout>

## Rate, pitch, and volume [#rate-pitch-and-volume]

All three controls accept integer values from `-100` to `100`; the default is `0`.

| Control | Lower values  | Higher values |
| ------- | ------------- | ------------- |
| Rate    | slower speech | faster speech |
| Pitch   | lower voice   | higher voice  |
| Volume  | quieter       | louder        |

Start with small changes such as `-10` or `10`. Extreme combinations can sound unnatural or make speech difficult to understand.

## Troubleshooting [#troubleshooting]

* **Speak is not visible:** enable it under **Options → Selection Toolbar**.
* **Wrong language voice:** create a mapping for the detected language and preview it.
* **No audio:** confirm the tab and operating system are not muted, then try another voice.
* **Speech is clipped or unstable:** return rate, pitch, and volume to `0` and test again.
* **Feature changes unexpectedly:** remember that TTS is Public Beta; export your configuration before a large voice-mapping change.

Voice settings are included in configuration exports and backups. See [Configuration, Sync & Backups](/docs/config-backup) for recovery options.


# AI Segmentation & Quota (/en/docs/video-subtitles/ai-segmentation)



Two things on this screen both say "AI" and are often mistaken for each other. They solve different problems, cost different resources, and one of them makes the other unnecessary.

|              | AI smart segmentation                  | AI subtitles quota                         |
| ------------ | -------------------------------------- | ------------------------------------------ |
| Needs        | An LLM provider that can generate text | A signed-in Pro or Ultra account           |
| What it uses | Your provider's tokens                 | Transcription minutes from your plan       |
| What it does | Re-cuts captions the video already has | Produces captions for a video with none    |
| Where        | A switch under **Basics**              | A usage panel, plus a button in the player |

## AI smart segmentation [#ai-smart-segmentation]

YouTube's auto-generated captions arrive as word-level fragments, each with its own start and end time. Read Frog can regroup them with rules alone, but on a talkative video the result still breaks mid-clause.

With **AI smart segmentation** on, those fragments are sent to your LLM provider, which returns them re-cut into complete sentences — punctuated and capitalised — and assigns each new line a start and end time taken from the first and last word it contains.

That timing is the trade-off. The model is deriving timestamps, not reading them off a clock, so lines can land slightly early or late, and a line that was easy to follow can drift out of sync. Turn it off if the captions stop matching the speech.

Concretely, with it on:

* Captions are cut into sentences rather than at arbitrary word boundaries, which also gives the translator whole sentences to work with.
* Each look-ahead window is one extra model request, so it costs tokens and adds latency before captions appear.
* It needs a provider that can generate text. On Google Translate or DeepL the switch has no effect and the rule-based cut is used instead.
* It does nothing to captions that already come as sentences. Some YouTube tracks do, and AI-generated subtitles always do.

The switch is off on a fresh install, and it is under **Options → Video Subtitles → Basics**.

## AI subtitles quota [#ai-subtitles-quota]

This is speech recognition, not translation. When a video has no captions at all — or only ones you would rather not read — the **Request AI subtitles** control in the player's Read Frog settings sends the video off to be transcribed, and the result comes back as a subtitle track Read Frog can then translate like any other.

It needs you signed in, and it needs a Pro or Ultra plan. Transcription is metered in minutes, and the panel on the settings screen shows what you have left: one bar per pool, labelled with the date the monthly quota resets, or the date a one-time grant expires.

Read Frog checks entitlement before it switches tracks, not after, so a refusal does not destroy the captions you were already watching. What you see depends on what is missing:

| Situation                  | What happens                                             |
| -------------------------- | -------------------------------------------------------- |
| Not signed in              | A toast with a log-in button; the panel shows the same   |
| Signed in, no subscription | A toast with an upgrade button                           |
| Minutes used up            | A toast naming the date your quota comes back            |
| Video too long             | A toast saying so, with no button — no plan changes this |
| Still transcribing         | A toast asking you to click again in a few minutes       |

A request runs in the background and can take a few minutes on a long video; the player shows it as loading meanwhile. If you give up waiting, the transcription keeps running on the server and the result is kept, so clicking again resumes the same job rather than starting a second one.

<Callout type="info">
  AI subtitles come back already cut into sentences, so AI smart segmentation is skipped for them
  entirely. The two features never run on the same track.
</Callout>

## Clear AI segmentation cache [#clear-ai-segmentation-cache]

A segmentation result is stored the first time it is produced, keyed to the caption fragments and the provider that cut them, so replaying a video you have already watched costs nothing.

**Clear AI segmentation cache**, at the bottom of the Video Subtitles screen, throws that store away. It asks for confirmation and cannot be undone. Reach for it when segmentation produced timings you want re-derived, or after switching to a provider whose cuts you expect to be better — otherwise the stored result is what you keep seeing.

It is a separate store from the translation cache on the [Translation Control](/docs/page-translation/translation-control) screen. Clearing one leaves the other alone, and neither touches your providers, prompts, or styles.

## Where to go next [#where-to-go-next]

Everything else about subtitles — enabling them, the provider, auto-start, display and request pacing — is in [Video Subtitles](/docs/video-subtitles). The prompt the translation itself uses is in [Subtitle Prompts](/docs/video-subtitles/prompts).


# Video Subtitles (/en/docs/video-subtitles)













Read Frog can translate captions in normal YouTube videos, YouTube Shorts, and embedded YouTube players on other websites. The video must have captions that YouTube exposes to the player.

<img alt="A YouTube player showing bilingual subtitles" src="__img0" />

## Enable subtitle translation [#enable-subtitle-translation]

1. Open **Options → Video Subtitles**.
2. Enable **Video Subtitles**.
3. Select an enabled translation provider.
4. Open a supported YouTube video and use the Read Frog control in the player.

<img alt="The Video Subtitles settings, from the enable switch down to the cache controls" src="__img1" />

<img alt="The Read Frog translation control in a YouTube player" src="__img2" />

**Auto-Enable Subtitles** starts Read Frog translation whenever a supported player loads. It does not manufacture captions: videos without available captions still cannot be translated.

<img alt="The auto-start setting for video subtitles" src="__img3" />

## Display and style [#display-and-style]

Choose bilingual, original-only, or translation-only captions. For bilingual captions, place the translation above or below the source. Style controls include font family, size or scale, weight, text colors, background opacity, and player position.

<img alt="Video subtitle style controls" src="__img4" />

These values affect the player overlay only. They do not change page-translation layout or [Custom CSS](/docs/page-translation/style). For effects the controls do not cover — blurring the translation, dimming the original, reshaping the caption box — see [Custom Subtitle Styles](/docs/video-subtitles/style).

## AI Smart Segmentation [#ai-smart-segmentation]

AI Smart Segmentation uses an LLM to regroup raw caption fragments into more natural reading units. It can improve sentences split at awkward boundaries, but it:

* requires an LLM provider;
* adds model latency and token cost;
* can occasionally make timing less exact;
* stores a cached segmentation result for reuse.

Clear the segmentation cache when you want the next playback to process the captions again. If subtitles disappear or lag, first turn segmentation off to separate caption availability from LLM processing.

## Independent request settings [#independent-request-settings]

Video subtitles have their own provider, prompt, request rate, burst capacity, and LLM batch limits. Changing them does not change webpage translation.

The defaults are `8` requests/second, burst capacity `60`, `1000` characters per batch, and `4` caption segments per batch. Rate and capacity use the same Token Bucket semantics described in [Request Control & Batch Translation](/docs/request-control): capacity is an immediately available burst, not a concurrency limit. Batch translation applies only to LLM providers.

For a low-quota subtitle provider, start with burst capacity `1` and the documented sustained rate. For example, `0.25` requests/second releases one request every four seconds.

## Troubleshooting [#troubleshooting]

* **No Read Frog control:** confirm Video Subtitles is enabled, then reload the video tab.
* **No translated captions:** verify that the video has captions and that the selected provider passes **Test Connection**.
* **Frequent 429 errors:** lower the subtitle rate and set burst capacity to `1`.
* **Awkward caption boundaries:** try AI Smart Segmentation with an LLM provider.
* **Timing became worse:** disable Smart Segmentation or clear its cache and retry.

<Callout type="info">
  The screenshots show the same controls described here; small visual details can differ as the
  YouTube player and extension UI evolve.
</Callout>


# Subtitle Prompts (/en/docs/video-subtitles/prompts)





Open **Options → Video Subtitles → Custom subtitle prompts → Manage prompts**.

This list is separate from the page-translation one, and nothing crosses between them: selecting a prompt here does not change what a web page is translated with, and the page's prompt list cannot be used for subtitles. Everything else about the editor — the two fields, the copy-a-built-in workflow, import and export — works exactly as it does in [Custom Prompts](/docs/page-translation/prompts).

<img alt="The subtitle prompt list, with the built-in prompt and the editor's variable buttons" src="__img0" />

## What is different [#what-is-different]

Subtitles ship one built-in prompt, and they take a different set of variables.

| Variable             | Subtitle prompts | Page prompts |
| -------------------- | ---------------- | ------------ |
| `{{targetLanguage}}` | Yes              | Yes          |
| `{{input}}`          | Yes              | Yes          |
| `{{webTitle}}`       | Yes              | Yes          |
| `{{webDescription}}` | Yes              | Yes          |
| `{{videoSummary}}`   | Yes              | —            |
| `{{webContent}}`     | —                | Yes          |
| `{{webSummary}}`     | —                | Yes          |

`{{videoSummary}}` stands where the two page variables would be: a video has no article body to quote, so the context a subtitle request carries is a summary of the video itself. Filling it requires AI Smart Context; without that, the variable is replaced with `No summary available`.

`{{input}}` here is caption lines rather than paragraphs, and a batch of them is separated the same way a batch of paragraphs is.

A variable from the other column is not an error — it is simply not substituted, and the literal `{{webContent}}` is sent to the model. The buttons under each field only offer the ones this list can fill.

For the sample value each variable is replaced with, see [Prompt Variables](/docs/page-translation/prompts/variables).

## One rule that is not appended [#one-rule-that-is-not-appended]

When a page-translation request carries several paragraphs, Read Frog appends an extra instruction telling the model how to mark a paragraph that already reads as the target language. Subtitles get the multi-item rules but **not** that one.

So a subtitle prompt never has to account for the sentinel marker, and a caption already in your target language is translated rather than flagged. The full ordering — which rule blocks are appended when, and what happens to the reply — is in [How a Request Is Assembled](/docs/page-translation/prompts/pipeline).

<Callout type="tip">
  Subtitles are read at the pace of the video, so brevity matters more here than in an article. A
  subtitle prompt that asks for short, spoken-sounding lines is usually worth more than one asking
  for a polished rewrite.
</Callout>


# Custom Subtitle Styles (/en/docs/video-subtitles/style)



The subtitle style page covers font, scale, weight, color and background opacity. Custom CSS is for everything those sliders do not reach: covering the translation with a blur until you actually need it, underlining it, pushing the original into the background, or reshaping the caption box.

It applies to the Read Frog subtitle overlay only. Webpage translation has its own, separate stylesheet — see [Custom Translation Styles](/docs/page-translation/style).

## Open the editor [#open-the-editor]

1. Open **Options → Video Subtitles**.
2. Open **Subtitle style** with **Customize style**.
3. Scroll to **Custom CSS** and open it.
4. Write your CSS. The preview above the editor updates as you type.
5. Press **Save**.

Saving reaches players that are already open, so you can keep a video in another tab and watch each save land. Clearing the editor and saving again removes the CSS and hands the subtitles back to the sliders.

## Start from a preset template [#start-from-a-preset-template]

The **Preset template** dropdown carries three ready-made blocks. Choosing one **appends** it to the end of the editor rather than replacing what is already there, so templates stack: blur the translation *and* dim the original by picking two.

### Blur translation [#blur-translation]

Listen first, and read only when you give up. The blur lifts while the pointer is over the line.

```css
.subtitles-translation {
  filter: blur(6px);
  transition: filter 0.15s ease;
}

.subtitles-translation:hover {
  filter: none;
}
```

<SubtitleStylePreview
  cssCode="`.subtitles-translation {
filter: blur(6px);
transition: filter 0.15s ease;
}

.subtitles-translation:hover {
filter: none;
}`"
/>

### Dashed translation [#dashed-translation]

Marks the translation as a helper rather than the main text.

```css
.subtitles-translation {
  text-decoration: underline dashed;
  text-decoration-thickness: 1px;
  text-underline-offset: 0.25em;
}
```

<SubtitleStylePreview
  cssCode="`.subtitles-translation {
text-decoration: underline dashed;
text-decoration-thickness: 1px;
text-underline-offset: 0.25em;
}`"
/>

### Dim original [#dim-original]

Keeps the source line available without letting your eye fall on it first.

```css
.subtitles-main {
  opacity: 0.6;
}
```

<SubtitleStylePreview
  cssCode="`.subtitles-main {
opacity: 0.6;
}`"
/>

## Selectors you can target [#selectors-you-can-target]

The overlay is deliberately small. Three class names are part of the contract and will not be renamed:

```html
<div class="read-frog-subtitles-box">
  <div class="subtitles-main">Mr. Kamiya isn't confronting the world…</div>
  <div class="subtitles-translation" lang="zh" dir="ltr">神谷先生…</div>
</div>
```

| Selector                   | What it matches                                                            |
| -------------------------- | -------------------------------------------------------------------------- |
| `.read-frog-subtitles-box` | the box both lines sit in — background, padding, corners, width, alignment |
| `.subtitles-main`          | the original caption line                                                  |
| `.subtitles-translation`   | the translated line                                                        |

The translation line carries two extra hooks:

* `lang` and `dir` follow your target language, so `.subtitles-translation[lang='ja']` and `.subtitles-translation[dir='rtl']` both work.
* `data-pending="true"` is set while a translation is still on its way back.

```css
.subtitles-translation[data-pending="true"] {
  opacity: 0.35;
}
```

<Callout type="info">
  The original always comes first in the DOM; **Translation position** flips the two visually with
  `order`. Match on the class names rather than on `:first-child`.
</Callout>

## Working with the style controls [#working-with-the-style-controls]

The font, scale, weight and color you pick in the UI reach each line as CSS variables that a stylesheet rule turns into declarations. Your CSS is injected after that rule, so an ordinary declaration wins — **`!important` is not needed**:

```css
.subtitles-translation {
  color: #ffd479;
  font-weight: 600;
}
```

<SubtitleStylePreview
  cssCode="`.subtitles-translation {
color: #ffd479;
font-weight: 600;
}`"
/>

Two exceptions are worth knowing before you spend time on them.

### Set the properties, not the `--rf-subtitle-*` variables [#set-the-properties-not-the---rf-subtitle--variables]

The variables behind those four controls are written inline on each line, and an inline declaration outranks every stylesheet rule. Writing `--rf-subtitle-color` in custom CSS does nothing:

```css
/* Ignored — the variable is set inline. */
.subtitles-main {
  --rf-subtitle-color: #7cf;
}

/* Works. */
.subtitles-main {
  color: #7cf;
}
```

### The box background needs `!important` [#the-box-background-needs-important]

**Background opacity** is written inline on the box for the same reason, and this is the one place custom CSS has to insist:

```css
.read-frog-subtitles-box {
  background-color: rgba(24, 20, 48, 0.85) !important;
  border-radius: 10px;
  padding: 8px 14px;
}
```

<SubtitleStylePreview
  cssCode="`.read-frog-subtitles-box {
background-color: rgba(24, 20, 48, 0.85) !important;
border-radius: 10px;
padding: 8px 14px;
}`"
/>

Everything else on the box — padding, corners, width, alignment — takes a plain declaration.

### Size in `em`, not `px` [#size-in-em-not-px]

The overlay's root font size is derived from the video's height, which is how subtitles stay proportionate when a video goes fullscreen or shrinks into a mini player. `1em` on a line means "the size the player would use"; a size in `px` freezes and stops following the video.

```css
.subtitles-translation {
  font-size: 1.15em;
}
```

## More recipes [#more-recipes]

### Outline the text and drop the box [#outline-the-text-and-drop-the-box]

Good on bright footage, where a dark plate is more intrusive than the captions themselves.

```css
.read-frog-subtitles-box {
  background-color: transparent !important;
}

.subtitles-main,
.subtitles-translation {
  text-shadow:
    0 0 4px rgba(0, 0, 0, 0.95),
    0 1px 3px rgba(0, 0, 0, 0.9);
}
```

<SubtitleStylePreview
  cssCode="`.read-frog-subtitles-box {
background-color: transparent !important;
}

.subtitles-main,
.subtitles-translation {
text-shadow:
0 0 4px rgba(0, 0, 0, 0.95),
0 1px 3px rgba(0, 0, 0, 0.9);
}`"
/>

### Let the translation lead [#let-the-translation-lead]

Shrinks the source line to a reference and gives the translation the weight.

```css
.subtitles-main {
  font-size: 0.75em;
  opacity: 0.65;
}

.subtitles-translation {
  font-size: 1.1em;
  font-weight: 600;
}
```

<SubtitleStylePreview
  cssCode="`.subtitles-main {
font-size: 0.75em;
opacity: 0.65;
}

.subtitles-translation {
font-size: 1.1em;
font-weight: 600;
}`"
/>

### Left-align long lines [#left-align-long-lines]

Center alignment is hard to read once a caption wraps onto three lines.

```css
.read-frog-subtitles-box {
  max-width: 70%;
  text-align: left;
}
```

<SubtitleStylePreview
  cssCode="`.read-frog-subtitles-box {
max-width: 70%;
text-align: left;
}`"
  originalText="Mr. Kamiya isn't confronting the world; he's confronting something that might make the world turn its head, and he has been doing it quietly for years."
  translationText="神谷先生不是在对抗世界，而是在对抗可能让世界为之侧目的事物，而且这件事他已经默默做了很多年。"
/>

### Per-language typography [#per-language-typography]

Useful when you read in more than one target language and want each to look right.

```css
.subtitles-translation[lang="ja"] {
  font-family: "Hiragino Mincho ProN", "Yu Mincho", serif;
}

.subtitles-translation[dir="rtl"] {
  font-size: 1.05em;
}
```

## Scope and limits [#scope-and-limits]

The overlay is rendered inside a shadow root in the player. That boundary is what keeps your CSS from leaking onto the page — and it also decides what quietly does nothing:

* **Works, and stays inside the overlay:** `@keyframes`, `@media`, `@supports`, transitions, pseudo-classes, and CSS variables you define yourself.
* **Ignored:** `@font-face` and `@property`. A shadow root cannot register either, so pick fonts already available on the system instead of loading your own.
* **Matches nothing:** `:root` and `body`. There is no page-level element inside the overlay — target the three classes above.
* **Out of reach:** the YouTube player's controls, the page behind it, and the native captions. Custom CSS cannot style anything outside the subtitle overlay.
* **Size limit:** 8 KB. The editor checks syntax as you type and blocks **Save** while the CSS is invalid or too long.

```css
/* Animations are fine, and stay contained. */
@keyframes rf-fade-in {
  from {
    opacity: 0;
  }
  to {
    opacity: 1;
  }
}

.subtitles-translation {
  animation: rf-fade-in 0.2s ease-out;
}
```

## Troubleshooting [#troubleshooting]

* **Nothing changed after saving:** confirm the status line reads *CSS is valid* and the button reads *Saved*, then check that the rule targets one of the three class names.
* **A background color on the box is ignored:** add `!important`. The opacity slider writes that property inline.
* **A `--rf-subtitle-*` override is ignored:** set `color`, `font-size`, `font-family` or `font-weight` directly instead.
* **Text size jumps when going fullscreen:** switch that `font-size` from `px` to `em`.
* **A font never applies:** `@font-face` does not work inside the overlay; use a font installed on the system.
* **Save is disabled:** the editor found a syntax error, or the stylesheet is over 8 KB.
* **The overlay looks broken:** empty the editor and save. The CSS is removed immediately and the style controls take over again.

Custom CSS is stored with the rest of your settings, so it travels with a configuration export — see [Configuration, Sync & Backups](/docs/config-backup). For everything else about the overlay, see [Video Subtitles](/docs/video-subtitles).