pi-quick-translate

pi extension: double-click a word in the fullscreen transcript to copy it and pop up a translation.

Packages

Package details

extension

Install pi-quick-translate from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:pi-quick-translate
Package
pi-quick-translate
Version
0.1.0
Published
Nov 7, 2026
Downloads
393/mo · 31/wk
Author
simplast
License
MIT
Types
extension
Size
38.3 KB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-quick-translate

English | 简体中文

pi's fullscreen view copies on select: double-click a word and it is on your clipboard. For anyone reading English in a second language, the next step is always the same — paste it into a translator. This extension removes that step.

Double-click a word, keep the copy, and get the translation in a small window on top of the transcript:

╭─────────────────────────────────────╮
│ cache                               │
│                                     │
│ 缓存                                │
│                                     │
│ click to close · 12s                │
╰─────────────────────────────────────╯

The window never takes the keyboard: you can keep typing while it is open, it disappears on its own after 12 seconds, and a click closes it early.

Install

pi install npm:pi-quick-translate

Or try it without installing:

pi -e npm:pi-quick-translate

Restart pi afterwards. Nothing else is needed: the default backend is a key-less Google lookup, so there is no API key and no config file.

Use it

Action Result
Double-click a word copies it, opens the translation
Drag-select a short phrase same, as long as it stays within the length filter
Click the window closes it
/translate <text> translates anything, including text too long for the filter
/translate translates the last thing you selected
/translate-toggle turns the double-click window on or off for this run

Selections that look like prose are filtered out, so dragging over a code block or a paragraph does not open a window: a selection must be at most 4 words, at most 48 characters, contain Latin letters, and contain none of the characters that show up in paths, identifiers, or code (/ { } ( ) = _ $ # …). Selections containing CJK script are skipped too — those are your own words, not something to look up.

Requirements

  • pi 1.4.0 or newer.
  • tuiMode: "fullscreen" (the default). In regular mode your terminal emulator owns selection, so pi never sees the copy and the extension cannot hook it. It says so once and leaves you with /translate.
  • Mouse reporting enabled in your terminal (iTerm2, kitty, WezTerm, Ghostty, Terminal.app, tmux all work).

Configuration

Everything lives in the environment, so uninstalling leaves nothing behind:

Variable Default Meaning
PI_TRANSLATE_PROVIDER google google, llm, or command
PI_TRANSLATE_TARGET zh-CN target language code
PI_TRANSLATE_MODEL session model provider/model for the llm backend
PI_TRANSLATE_CMD — shell command for the command backend
PI_TRANSLATE_MAX_WORDS 4 longer selections count as prose
PI_TRANSLATE_MAX_CHARS 48 hard length cap
PI_TRANSLATE_POPUP_SECONDS 12 0 keeps the window until you click it
PI_TRANSLATE 1 0 disables the window at startup

Backends

google — translate.googleapis.com, no key, answers a word in a few hundred milliseconds. It is an undocumented endpoint, so treat it as convenient rather than guaranteed, and note that it is unreachable from some networks.

llm — sends the selection to the model pi is already configured with. Slower, and it costs a request, but it reads context and can annotate a word with its part of speech. This is the backend that works behind a firewall:

PI_TRANSLATE_PROVIDER=llm pi
PI_TRANSLATE_PROVIDER=llm PI_TRANSLATE_MODEL=deepseek/deepseek-chat pi

command — hands the text to a translator you already have:

PI_TRANSLATE_PROVIDER=command PI_TRANSLATE_CMD='trans {text}' pi

{text} is replaced by the single-quoted selection. Without a placeholder the text is appended as the last argument. Stdout becomes the window's content.

How it works

pi's fullscreen renderer owns selection, and it does not emit an event when it copies. Worse for an extension, it consumes mouse input before extension input listeners see it, so a double-click is not observable from the outside either. The one place a copy surfaces is the clipboard callback pi injects into that renderer.

The extension borrows the live renderer instance — ctx.ui.setWidget() hands it to a widget factory, and a widget that renders zero lines in the belowEditor slot changes nothing visually — and wraps the injected callback:

  1. pi copies the selection to the clipboard exactly as before, "Copied!" included;
  2. if the copy succeeded, the selection is checked against the filter;
  3. a pass opens a nonCapturing overlay; the translation fills it in when it arrives;
  4. the overlay is dismissed by a click or by its timer.

If a future pi build moves that callback, the extension reports it once and keeps /translate working. Nothing is patched on the prototype and no other renderer behaviour is touched.

What it touches on your system

  • No daemon, no watcher, no timers beyond the popup's. The extension lives exactly as long as pi does.
  • No postinstall hook. Installing runs nothing on your machine.
  • No config file. Every setting is an environment variable for that run.
  • One network call per translated selection, to your chosen backend. Nothing else is sent, there is no telemetry, and results are cached in memory only (200 entries, gone when pi exits).
  • The only persistent side effect is the clipboard entry pi already writes when you select text.

If you would rather the selection never leave the machine, PI_TRANSLATE_PROVIDER=command with a local dictionary is the way; nothing about the copy behaviour changes either way.

Development

npm install
npm test        # 44 tests
npm run typecheck
pi --extension ./index.ts

License

MIT