# 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](./README.md)
- [한국어](./README.ko.md)
- [日本語](./README.ja.md)
- [中文](./README.zh.md)
- [Español](./README.es.md)
- [Français](./README.fr.md)
- [Deutsch](./README.de.md)
- [Italiano](./README.it.md)
- [Português](./README.pt.md)
- [Русский](./README.ru.md)
- [Nederlands](./README.nl.md)
- [Polski](./README.pl.md)
- [Türkçe](./README.tr.md)
- [Tiếng Việt](./README.vi.md)
- [ไทย](./README.th.md)
- [Bahasa Indonesia](./README.id.md)
- [العربية](./README.ar.md)
- [हिन्दी](./README.hi.md)

## 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:

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

Run once without installing permanently:

```bash
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`.

```text
/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`

```text
/prompt-translate model current
```

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

### `default`

```text
/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

```text
/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:

```bash
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