# How to Trigger a Translation in FluentRead: 3 Methods Explained

> Discover the 3 easy ways to trigger a translation in FluentRead: input shortcuts, hotkeys, and mouse gestures. Customize your translation experience today.

- Repository: [ThinkStu/fluentread](https://github.com/bistutu/fluentread)
- Tags: how-to-guide
- Published: 2026-02-26

---

**FluentRead supports three distinct ways to trigger a translation: input-box shortcuts for text fields, page-wide hotkeys and mouse gestures for general browsing, and a dedicated floating-ball shortcut, all configurable via [`entrypoints/utils/option.ts`](https://github.com/bistutu/fluentread/blob/main/entrypoints/utils/option.ts) and handled in [`entrypoints/content.ts`](https://github.com/bistutu/fluentread/blob/main/entrypoints/content.ts).**

FluentRead is an open-source browser extension designed for seamless web page translation. Knowing how to trigger a translation in FluentRead allows you to customize the interaction model to match your workflow, whether you prefer keyboard shortcuts, mouse gestures, or touch inputs. The extension's trigger architecture is modular, with distinct handlers for text input contexts, global page events, and UI components.

## Input-Box Translation Triggers

Input-box translation allows users to translate text directly inside `<input>`, `<textarea>`, or content-editable elements without leaving the field. This feature is controlled by the `inputBoxTranslationTrigger` configuration option.

### Configuration Options

In [`entrypoints/utils/option.ts`](https://github.com/bistutu/fluentread/blob/main/entrypoints/utils/option.ts), the available triggers are defined as:

```typescript
export const option = {
  inputBoxTranslationTrigger: [
    {value: "disabled",     label: "关闭"},
    {value: "triple_space", label: "连按三下空格"},
    {value: "triple_equal", label: "连按三下等号(=)"},
    {value: "triple_dash",  label: "连按三下短横线(-)"},
    // (Legacy) Ctrl+Enter is supported in the code but not exposed in UI
  ],
};

```

The default state disables this feature entirely, as seen in [`entrypoints/utils/model.ts`](https://github.com/bistutu/fluentread/blob/main/entrypoints/utils/model.ts):

```typescript
this.inputBoxTranslationTrigger = 'disabled';

```

### Implementation and Key Detection

The `setupInputBoxTranslation()` function in [`entrypoints/content.ts`](https://github.com/bistutu/fluentread/blob/main/entrypoints/content.ts) registers a **keydown** listener on the document. The handler performs the following checks:

1.  Verifies `config.inputBoxTranslationTrigger` is not set to **disabled**.
2.  Confirms the active element is an input field using `isInputElement()`.
3.  For **Ctrl + Enter**, it triggers immediately when `event.ctrlKey && event.key === 'Enter'`.
4.  For **triple-key triggers** (space, equals, or dash), it counts consecutive presses of the target key within `TRIPLE_KEY_TIMEOUT` (1 second). When the third press occurs, it invokes `handleInputBoxTranslation()` (lines 947-978) to process the translation.

The counting logic resides in [`content.ts`](https://github.com/bistutu/fluentread/blob/main/content.ts) lines 677-727, maintaining a counter that resets after the timeout window expires.

### Enabling Triple-Space Translation

To activate this trigger programmatically:

```typescript
storage.setItem('local:config', JSON.stringify({ 
  inputBoxTranslationTrigger: 'triple_space' 
}));

```

Once enabled, typing three consecutive spaces in any text box will replace the input with the translated text.

## Page-Wide Translation Triggers

For general page content, FluentRead uses the `config.hotkey` setting to determine how translations are initiated. This supports both pointer and touch interactions.

### Hotkey-Based Activation

The primary hotkey is defined in [`entrypoints/utils/option.ts`](https://github.com/bistutu/fluentread/blob/main/entrypoints/utils/option.ts) (lines 242-254) and includes:

-   **Control** (default): Hold the Control key while hovering over text.
-   **DoubleClick**: Double-click any word to translate.
-   **LongPress**: Press and hold the mouse button for approximately 600ms.
-   **MiddleClick**: Click the middle mouse button.
-   **Custom combos**: Such as `Alt+T` or `F9`.

The constants for these values are centralized in [`entrypoints/utils/constant.ts`](https://github.com/bistutu/fluentread/blob/main/entrypoints/utils/constant.ts) (lines 38-48).

### The Screen Object and Event Loop

The core translation logic resides in [`entrypoints/content.ts`](https://github.com/bistutu/fluentread/blob/main/entrypoints/content.ts), where a `screen` object (lines 139-320) tracks mouse coordinates, key states, and hotkey activation. When `screen.hotkeyPressed && config.on` evaluates to true, the code calls `translateSelection()` to fetch and display the translation.

For touch devices, the same configuration supports `DoubleClickScreen` (two-finger tap) and `TripleClickScreen` (three-finger tap). These are handled in the event loop's switch statement (lines 330-338), which derives the `requiredTouches` count from the hotkey setting.

### Example: Configuring Double-Click Translation

```typescript
storage.setItem('local:config', JSON.stringify({ 
  hotkey: 'DoubleClick' 
}));

```

After setting this, double-clicking any word on a webpage will immediately display the translation tooltip.

## Floating Ball Shortcut

The floating ball provides persistent UI access without requiring specific page interactions. It appears as an overlay that can be summoned via a dedicated shortcut.

### Configuration and Mounting

The shortcut is configured via `config.floatingBallHotkey`, defaulting to `"Alt+T"` in [`entrypoints/utils/option.ts`](https://github.com/bistutu/fluentread/blob/main/entrypoints/utils/option.ts). To disable it, set the value to `"none"`.

During initialization, `setupFloatingBall()` in [`entrypoints/content.ts`](https://github.com/bistutu/fluentread/blob/main/entrypoints/content.ts) (lines 435-470) mounts the [`FloatingBall.vue`](https://github.com/bistutu/fluentread/blob/main/FloatingBall.vue) component and registers the keyboard listener. When the configured shortcut is pressed, `toggleFloatingBall()` switches the component's visibility.

### Customizing the Floating Ball Hotkey

To change the shortcut to Ctrl+Shift+F:

```typescript
storage.setItem('local:config', JSON.stringify({ 
  floatingBallHotkey: 'Ctrl+Shift+F' 
}));

```

Pressing **Ctrl + Shift + F** will now show or hide the floating translation interface.

## Summary

- **Input-box triggers** support triple-tap sequences (space, equals, or dash) and legacy Ctrl+Enter, configured via `inputBoxTranslationTrigger` and processed by `setupInputBoxTranslation()` in [`content.ts`](https://github.com/bistutu/fluentread/blob/main/content.ts).
- **Page-wide triggers** rely on `config.hotkey` with options including Control hover, DoubleClick, LongPress, and multi-finger touch gestures, handled by the `screen` object in the central event loop.
- **Floating-ball access** uses `floatingBallHotkey` (default Alt+T) to toggle the [`FloatingBall.vue`](https://github.com/bistutu/fluentread/blob/main/FloatingBall.vue) component via `toggleFloatingBall()`.
- All trigger configurations are defined in [`entrypoints/utils/option.ts`](https://github.com/bistutu/fluentread/blob/main/entrypoints/utils/option.ts) and persisted through the storage layer, while [`entrypoints/content.ts`](https://github.com/bistutu/fluentread/blob/main/entrypoints/content.ts) orchestrates the runtime event handling.

## Frequently Asked Questions

### How do I enable the triple-space translation trigger?

Set `inputBoxTranslationTrigger` to `'triple_space'` in your extension configuration. This activates a keydown listener in [`content.ts`](https://github.com/bistutu/fluentread/blob/main/content.ts) that counts three consecutive space presses within a 1-second window, then invokes `handleInputBoxTranslation()` to replace the input text with the translated version.

### What hotkey options are available for page-wide translation?

According to [`entrypoints/utils/option.ts`](https://github.com/bistutu/fluentread/blob/main/entrypoints/utils/option.ts), available `hotkey` values include `Control` (default), `DoubleClick`, `LongPress`, `MiddleClick`, `DoubleClickScreen`, `TripleClickScreen`, and various keyboard combinations like `Alt+T` or `F9`. These constants are defined in [`entrypoints/utils/constant.ts`](https://github.com/bistutu/fluentread/blob/main/entrypoints/utils/constant.ts) and processed by the `screen` object in [`content.ts`](https://github.com/bistutu/fluentread/blob/main/content.ts).

### Can I disable the floating ball shortcut?

Yes, set `floatingBallHotkey` to `"none"` in your configuration. This prevents `setupFloatingBall()` from registering the keyboard shortcut, though you can still programmatically toggle the ball using the `toggleFloatingBall()` function imported from [`entrypoints/content.ts`](https://github.com/bistutu/fluentread/blob/main/entrypoints/content.ts).

### Where does FluentRead handle touch gestures like two-finger taps?

Touch gestures are handled in the central event loop within [`entrypoints/content.ts`](https://github.com/bistutu/fluentread/blob/main/entrypoints/content.ts) (lines 330-338). The code checks `config.hotkey` against touch constants from [`constant.ts`](https://github.com/bistutu/fluentread/blob/main/constant.ts) (such as `TwoFinger` or `ThreeFinger`) and sets the `requiredTouches` count accordingly to detect the gesture.