Pi Thinking Translator

Translate Pi assistant thinking blocks for display without sending those translations back into future model context.

This package is a Pi extension for users who prefer to inspect visible assistant thinking/reasoning summaries in another language. By default, it only translates thinking blocks and does not choose a translator model automatically.

Features

• Translates configured visible assistant content blocks when an assistant message ends.
• Uses a model already configured in Pi's model registry.
• Shows translations as transient Pi UI notifications instead of persistent widgets or message-stream entries.
• Does not modify assistant messages, future model context, compaction input, or provider cache keys.
• Supports optional translation of normal assistant text answers when explicitly enabled.
• Supports global config with project-level overrides.

Install

Install from npm:

pi install npm:pi-thinking-translator

Install from GitHub:

pi install git:github.com/wplct/pi-thinking-translator@v0.1.6

For local development from a checkout:

pi -e /absolute/path/to/pi-thinking-translator

Quick Start

1. Install the extension:

   pi install npm:pi-thinking-translator
   

2. Create a global config template from inside Pi:

   /thinking-translator init --global
   

3. Edit the generated file:

   ~/.pi/agent/thinking-translator.json
   

4. Enable translation and point the extension at a Pi model:

   {
     "enabled": true,
     "translatorModel": {
       "provider": "deepseek",
       "id": "deepseek-v4-flash"
     }
   }
   

5. Check the effective config:

   /thinking-translator status
   

The provider and id must match a model visible to Pi, for example a model configured in ~/.pi/agent/models.json or provided by a built-in provider.

Commands

/thinking-translator
/thinking-translator status
/thinking-translator clear
/thinking-translator init
/thinking-translator init --global
/thinking-translator init --project

• /thinking-translator and /thinking-translator status show the effective config, config file paths, and translator model availability.
• /thinking-translator clear clears any old temporary translation widget left by versions 0.1.3/0.1.4.
• /thinking-translator init creates the global config, same as /thinking-translator init --global.
• /thinking-translator init --global creates ~/.pi/agent/thinking-translator.json if it does not already exist.
• /thinking-translator init --project creates .pi/thinking-translator.json in the current project if it does not already exist.

The init commands create a disabled template and do not write a default model. You must explicitly set translatorModel and enable translation.

Configuration

The extension does not create a config file automatically and does not choose a default translator model. Built-in defaults are used unless you explicitly override them:

{
  "enabled": true,
  "targetLanguage": "Simplified Chinese",
  "contentTypes": ["thinking"],
  "minLatinChars": 24
}

Configuration files are optional partial overrides. They follow Pi's global/project convention:

1. Built-in defaults
2. Global config: ~/.pi/agent/thinking-translator.json
3. Project config: .pi/thinking-translator.json

Project config overrides global config.

Example: global translator model

{
  "enabled": true,
  "translatorModel": {
    "provider": "deepseek",
    "id": "deepseek-v4-flash"
  }
}

Example: enable normal answer translation for one project

Create .pi/thinking-translator.json in that project:

{
  "contentTypes": ["thinking", "text"]
}

When text is enabled, the translated answer is shown as a temporary UI notification. The extension still leaves the original assistant answer unchanged.

Options

Option	Type	Default	Description
enabled	boolean	true	Enables translation processing. If no translatorModel is configured, translation is skipped with a warning.
targetLanguage	string	"Simplified Chinese"	Target language passed to the translator model.
contentTypes	string[]	["thinking"]	Visible assistant block types to translate. Supported values: thinking, reasoning, reasoning_summary, text.
minLatinChars	number	24	Minimum number of Latin letters required before a block is considered translatable.
translatorModel	object	unset	Pi model reference: { "provider": "...", "id": "..." }.

If translation is enabled but translatorModel is missing, cannot be found, or the Pi model registry is unavailable, the extension shows a warning and skips translation without affecting the main assistant message. If a configured model request or credential lookup fails, the extension keeps the original assistant message unchanged and shows a warning for the first occurrence of that error.

How It Works

1. During an agent turn, the extension listens for completed assistant messages that contain configured translatable blocks.
2. After an assistant message ends, it sends the original visible block text to the configured Pi model with strict JSON-output instructions.
3. It parses only { "translation": "..." }; non-JSON or malformed outputs are rejected instead of displayed.
4. It shows the cleaned translation via a transient Pi UI notification.
5. It does not call sendMessage, append a custom message, or return a modified assistant message, so translations are not written to the session file or future context.

This design lets you inspect translations briefly to catch model drift while avoiding display translations becoming future model input or provider cache material.

Security Notes

Pi extensions run with full system permissions. Review extension source before installing third-party packages.

Translation backends may receive the visible blocks enabled by contentTypes, including final assistant answers if text is enabled. Use a local model if that content should not leave your machine.

The current implementation displays translations through transient UI notifications instead of widgets or assistant messages, so display translations do not enter future model context or compaction summaries.

Development

pnpm install
pnpm check

Package Layout

pi-thinking-translator/
  package.json
  README.md
  TODO.md
  extensions/
    thinking-translator.ts
  tests/
    thinking-translator.test.ts

Roadmap

• Add optional API translator backends.
• Add more runtime validation around context and compaction isolation.