# pi-prompt-translate

`pi-prompt-translate` 是一个 pi 包，让你可以用偏好的语言使用 pi，同时让编码 agent 的工作流保持英文。它会在 agent 启动前把普通用户提示翻译成英文，强制 agent 运行过程保持英文，然后只把最终 assistant 回答翻译回你配置的目标语言。

当你希望进行本地化交互，但不希望 agent 用非英文生成工具调用、文件编辑、shell 命令或中间推理时，这个包会很有用。

## README 语言

- [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)

## 功能

- 在用户提示到达 pi agent 之前将其翻译成英文。
- 只将最终 assistant 工作简报/最终回答翻译成配置的目标语言，用于 CLI 显示。
- 在之后构建 LLM 上下文时，把已显示的译文恢复为原始英文最终回答，避免翻译后的最终回答进入后续 LLM 请求。
- 注入仅使用英文的指令，让实际 agent 运行、工具使用规划、工具调用参数、中间 assistant 消息以及翻译前的最终回答都保持英文。
- 跳过包含工具调用的 assistant 消息，并等待工具执行后的最终 assistant 消息。
- 默认使用当前选择的 pi 模型进行翻译。
- 也可以改用 pi 配置的默认模型，或专用的 `<provider>/<model>` 翻译模型。
- 在翻译初始提示时显示 UI 通知。
- 不向翻译专用 LLM 调用暴露工具。
- slash command 和带图片的提示保持不变。
- 翻译失败时安全回退到原始提示或原始最终回答。
- 将包设置持久保存在 pi 会话历史中。

## 工作方式

1. 当普通用户输入到达时，包会把该输入翻译成英文。
2. 翻译后的英文提示会发送给 pi agent。
3. 在 agent 启动前，包会追加一条指令，要求 agent 在运行期间用英文工作和回答。
4. 工具调用 assistant 消息会保持不变，以便工具执行正常继续。
5. 当最终 assistant 回答生成后，包会把该最终回答翻译成配置的目标语言用于 CLI 显示。
6. 包会记录显示的译文以及原始英文最终回答。
7. 在之后的 provider 请求中，包会在 LLM 上下文里把显示的已翻译 assistant 回答替换回原始英文文本。

这个包有意只在编码任务完成后翻译最终回答。中间消息和工具调用保持英文，以避免破坏命令、路径、JSON、代码或结构化工具参数。后续 LLM 请求也会看到先前最终回答的英文版本，这有利于 prompt cache 复用，并且通常比累积本地化 assistant 历史更节省 token。

## 安装

从 npm 安装：

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

不永久安装，仅运行一次：

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

## 默认设置

| 设置 | 默认值 | 说明 |
| --- | --- | --- |
| 启用 | `true` | 提示翻译默认启用。 |
| 目标语言 | `Korean` | assistant 最终回答默认翻译为韩语。 |
| 翻译模型 | `current` | 使用当前选择的 pi 模型。 |
| 调试 | `false` | 调试通知默认关闭。 |

## 命令

所有命令都通过 `/prompt-translate` 使用。

```text
/prompt-translate on
/prompt-translate 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
```

### 命令参考

| 命令 | 说明 |
| --- | --- |
| `/prompt-translate on` | 启用提示和最终回答翻译。别名：`enable`。 |
| `/prompt-translate off` | 禁用翻译。别名：`disable`。 |
| `/prompt-translate status` | 显示启用状态、目标语言、配置的翻译模型、解析后的翻译模型、当前模型和调试状态。 |
| `/prompt-translate lang <language>` | 设置 assistant 最终回答的目标语言。别名：`language`、`target`。 |
| `/prompt-translate model current` | 使用当前选择的 pi 模型进行翻译。 |
| `/prompt-translate model default` | 使用 pi 用户设置中的 `defaultProvider/defaultModel`。 |
| `/prompt-translate model <provider>/<model>` | 使用特定模型进行翻译，例如 `openai/gpt-4.1-mini`。 |
| `/prompt-translate debug on` | 启用调试 UI 通知。 |
| `/prompt-translate debug off` | 禁用调试 UI 通知。 |
| `/prompt-translate reset` | 恢复默认设置。 |
| `/prompt-translate help` | 显示简短命令摘要。 |

## 语言名称和别名

你可以向 `/prompt-translate lang` 传入普通语言名称。常见别名会自动规范化：

| 输入示例 | 保存的目标语言 |
| --- | --- |
| `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` |

其他语言名称即使不在上表中，也会在去除首尾空白后按原样接受。

## 翻译模型选项

### `current`

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

使用 pi 中当前选择的模型。这是默认选项，通常也是最简单的选择。

### `default`

```text
/prompt-translate model default
```

使用 pi 用户设置中的 `defaultProvider` 和 `defaultModel`。如果这些设置缺失或找不到模型，`status` 会报告解析错误。

### 专用模型

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

使用一个已注册的特定 pi 模型进行翻译。如果你想把主要编码模型留给 agent 工作，并使用更快或更便宜的模型进行翻译，这会很有用。

## 不会翻译的内容

这个包会有意让以下输入原样通过：

- `/help` 或 `/prompt-translate status` 等 slash command。
- 扩展发送的输入。
- 带有图片附件的提示。
- 请求使用工具的 assistant 消息。

## 失败行为

如果提示翻译失败，pi 会继续使用原始用户提示并显示错误通知。如果最终回答翻译失败，pi 会保留原始英文最终回答并显示错误通知。这样可以避免编码工作流被翻译问题阻塞。

## 开发

安装依赖并运行 TypeScript 检查：

```bash
npm install
npm run check
```

包入口是 `index.ts`，pi 通过 `package.json` 中的 `pi.extensions` 字段加载它。

## 包

- npm 包：`@kim05/pi-prompt-translate`
- 许可证：MIT