How to Trigger a Translation in FluentRead: 3 Methods Explained

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 and handled in 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, the available triggers are defined as:

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:

this.inputBoxTranslationTrigger = 'disabled';

Implementation and Key Detection

The setupInputBoxTranslation() function in 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 lines 677-727, maintaining a counter that resets after the timeout window expires.

Enabling Triple-Space Translation

To activate this trigger programmatically:

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 (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 (lines 38-48).

The Screen Object and Event Loop

The core translation logic resides in 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

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. To disable it, set the value to "none".

During initialization, setupFloatingBall() in entrypoints/content.ts (lines 435-470) mounts the 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:

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.
• 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 component via toggleFloatingBall().
• All trigger configurations are defined in entrypoints/utils/option.ts and persisted through the storage layer, while 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 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, 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 and processed by the screen object in 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.

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

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

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