pi-prompt-translate

pi-prompt-translate is a pi package that lets you use pi in your preferred language while keeping the coding-agent workflow in English. It translates each normal user prompt to English before the agent starts and forces the agent run to stay in English. Final assistant-answer translation is optional and is off by default.

This is useful when you want localized interaction without making the agent issue tool calls, file edits, shell commands, or intermediate reasoning in a non-English language.

README languages

• English
• 한국어
• 日本語
• 中文
• Español
• Français
• Deutsch
• Italiano
• Português
• Русский
• Nederlands
• Polski
• Türkçe
• Tiếng Việt
• ไทย
• Bahasa Indonesia
• العربية
• हिन्दी

Features

• Translates user prompts to English before they reach the pi agent.
• Can translate the final assistant work briefing/final answer back to the configured target language for CLI display when response translation is enabled.
• Keeps translated final answers out of future LLM context by restoring the original English final answer when pi builds the next provider request.
• Injects an English-only instruction so the actual agent run, tool-use planning, tool call arguments, intermediate assistant messages, and pre-translation final answer stay in English.
• Skips assistant messages that contain tool calls and waits for the final assistant message after tool execution.
• Uses the currently selected pi model for translation by default.
• Can instead use pi's configured default model or a dedicated <provider>/<model> translation model.
• Shows a UI notification while the initial prompt is being translated.
• Does not expose tools to translation-only LLM calls.
• Protects action-like XML tags and pi-autoprompt-next machine-readable blocks during final-answer translation so they remain byte-for-byte unchanged.
• Omits volatile timestamps from translation-only LLM messages to improve provider prompt-cache reuse.
• Uses a compact translation output-token budget instead of a large fixed cap.
• Leaves slash commands and prompts with attached images unchanged.
• Falls back safely to the original prompt or original final answer if translation fails.
• Persists package settings in the pi session history.

How it works

1. When a normal user input arrives, the package translates that input to English.
2. The translated English prompt is sent to the pi agent.
3. Before the agent starts, the package appends an instruction that tells the agent to work and answer in English during the run.
4. Tool-calling assistant messages are left untouched so tool execution continues normally.
5. By default, the final assistant answer remains in English and no response-translation LLM call is made.
6. If response translation is enabled, the package translates the final answer to the configured target language for display in the CLI.
7. The package records the English final answer alongside the displayed translation.
8. On later provider requests, the package replaces displayed translated assistant answers with their original English text in the LLM context.

When response translation is enabled, the package translates only the final answer after the coding task is complete. Intermediate messages and tool calls remain in English to avoid corrupting commands, paths, JSON, code, or structured tool arguments. Future LLM requests also see the English version of prior translated final answers, which improves prompt-cache reuse and avoids spending context tokens on translated assistant history.

Installation

Install from npm:

pi install npm:@kim05/pi-prompt-translate

Run once without installing permanently:

pi -e npm:@kim05/pi-prompt-translate

Default settings

Setting	Default	Description
Input translation	true	Prompt translation starts enabled.
Response translation	false	Final assistant answers are not translated by default, so no response-translation LLM call is made unless you enable it.
Target language	Korean	Used when response translation is enabled.
Translation model	current	Uses the currently selected pi model.
Debug	false	Debug notifications are disabled by default.

Commands

All commands are available through /prompt-translate.

/prompt-translate on
/prompt-translate off
/prompt-translate input on
/prompt-translate input off
/prompt-translate responses on
/prompt-translate responses off
/prompt-translate status
/prompt-translate lang Korean
/prompt-translate lang Japanese
/prompt-translate lang Chinese
/prompt-translate lang Spanish
/prompt-translate lang French
/prompt-translate lang German
/prompt-translate model current
/prompt-translate model default
/prompt-translate model <provider>/<model>
/prompt-translate debug on
/prompt-translate debug off
/prompt-translate reset

Command reference

Command	Description
/prompt-translate on	Enable input prompt translation. Alias: enable.
/prompt-translate off	Disable input prompt translation. Alias: disable.
/prompt-translate input on	Enable input prompt translation. Aliases: prompt, prompts.
/prompt-translate input off	Disable input prompt translation. Aliases: prompt, prompts.
/prompt-translate responses on	Enable final assistant-answer translation. Aliases: response, answer, answers, reply, replies.
/prompt-translate responses off	Disable final assistant-answer translation. Aliases: response, answer, answers, reply, replies.
/prompt-translate status	Show input and response translation state, target language, configured translation model, resolved translation model, current model, and debug state.
/prompt-translate lang <language>	Set the target language for final assistant answers. Aliases: language, target.
/prompt-translate model current	Use the currently selected pi model for translation.
/prompt-translate model default	Use defaultProvider/defaultModel from pi user settings.
/prompt-translate model <provider>/<model>	Use a specific model for translation, for example openai/gpt-4.1-mini.
/prompt-translate debug on	Enable debug UI notifications.
/prompt-translate debug off	Disable debug UI notifications.
/prompt-translate reset	Restore the default settings.
/prompt-translate help	Show a compact command summary.

Language names and aliases

You can pass a plain language name to /prompt-translate lang. Common aliases are normalized automatically:

Input examples	Stored target language
ko, kor, korean, 한국어, 한글	Korean
ja, jp, japanese, 일본어	Japanese
zh, zh-cn, cn, chinese, 중국어, 中文	Chinese
es, esp, spanish, 스페인어, español	Spanish
fr, fra, fre, french, 프랑스어, français	French
de, deu, german, 독일어, deutsch	German
en, eng, english, 영어	English
it, ita, italian, 이탈리아어, italiano	Italian
pt, por, portuguese, 포르투갈어, português	Portuguese
ru, rus, russian, 러시아어, русский	Russian
nl, nld, dutch, 네덜란드어, nederlands	Dutch
pl, pol, polish, 폴란드어, polski	Polish
tr, tur, turkish, 터키어, türkçe	Turkish
vi, vie, vietnamese, 베트남어, tiếng việt	Vietnamese
th, tha, thai, 태국어, ไทย	Thai
id, ind, indonesian, 인도네시아어, bahasa indonesia	Indonesian
ar, arabic, 아랍어, العربية	Arabic
hi, hin, hindi, 힌디어, हिन्दी	Hindi

Other language names are accepted as written after trimming whitespace, even if they are not listed above.

Translation model options

current

/prompt-translate model current

Uses the model currently selected in pi. This is the default and is usually the simplest option.

default

/prompt-translate model default

Uses defaultProvider and defaultModel from your pi user settings. If those settings are missing or the model cannot be found, status will report the resolution error.

Dedicated model

/prompt-translate model <provider>/<model>

Uses a specific registered pi model for translation. This can be helpful if you want to reserve your main coding model for agent work and use a faster or cheaper model for translation.

What is not translated

The package deliberately passes the following inputs through unchanged:

• Slash commands, such as /help or /prompt-translate status.
• Inputs sent by extensions.
• Prompts with attached images.
• Assistant messages that request tool use.

Conversation history and caching

When response translation is enabled, translated final answers are meant for the user's CLI display. For future LLM requests, pi-prompt-translate restores those assistant messages to their original English text through pi's context hook. This keeps the provider-facing conversation history in English, which is better for prompt-cache hits and usually reduces token usage compared with accumulating localized assistant replies.

Failure behavior

If prompt translation fails, pi continues with the original user prompt and shows an error notification. If response translation is enabled and final-answer translation fails, pi keeps the original English final answer and shows an error notification. If a displayed final answer has no recorded English counterpart, it is left unchanged in the context. This keeps the coding workflow from being blocked by translation issues.

Development

Install dependencies, run the TypeScript check, and run unit tests:

npm install
npm run check
npm test

Unit tests are written with Vitest in index.test.ts. The package entry point is index.ts, and pi loads it through the pi.extensions field in package.json.

Package

• npm package: @kim05/pi-prompt-translate
• License: MIT