# pi-prompt-translate

`pi-prompt-translate`는 코딩 에이전트 워크플로는 영어로 유지하면서 pi를 원하는 언어로 사용할 수 있게 해 주는 pi 패키지입니다. 일반 사용자 프롬프트를 에이전트가 시작되기 전에 영어로 번역하고, 에이전트 실행은 영어로 유지하도록 강제한 뒤, 최종 assistant 답변만 설정한 대상 언어로 다시 번역합니다.

도구 호출, 파일 편집, 셸 명령, 중간 추론이 비영어 언어로 생성되는 것을 피하면서 현지화된 상호작용을 원할 때 유용합니다.

## 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 에이전트에 도달하기 전에 영어로 번역합니다.
- 최종 assistant 작업 브리핑/최종 답변만 CLI 표시용으로 설정된 대상 언어로 다시 번역합니다.
- 이후 LLM 컨텍스트를 만들 때는 표시된 번역문을 원래 영어 최종 답변으로 되돌려, 번역된 최종 답변이 향후 LLM 요청에 들어가지 않게 합니다.
- 실제 에이전트 실행, 도구 사용 계획, 도구 호출 인자, 중간 assistant 메시지, 번역 전 최종 답변이 영어로 유지되도록 영어 전용 지시를 삽입합니다.
- 도구 호출이 포함된 assistant 메시지는 건너뛰고, 도구 실행 후의 최종 assistant 메시지를 기다립니다.
- 기본적으로 현재 선택된 pi 모델을 번역에 사용합니다.
- 대신 pi에 설정된 기본 모델이나 전용 `<provider>/<model>` 번역 모델을 사용할 수 있습니다.
- 초기 프롬프트를 번역하는 동안 UI 알림을 표시합니다.
- 번역 전용 LLM 호출에는 도구를 노출하지 않습니다.
- slash command와 이미지가 첨부된 프롬프트는 변경하지 않습니다.
- 번역 실패 시 원래 프롬프트 또는 원래 최종 답변으로 안전하게 fallback 합니다.
- 패키지 설정을 pi 세션 기록에 유지합니다.

## 동작 방식

1. 일반 사용자 입력이 들어오면 패키지가 해당 입력을 영어로 번역합니다.
2. 번역된 영어 프롬프트가 pi 에이전트로 전달됩니다.
3. 에이전트가 시작되기 전에, 패키지는 에이전트가 실행 중 영어로 작업하고 답변하도록 지시를 추가합니다.
4. 도구 호출 assistant 메시지는 그대로 두어 도구 실행이 정상적으로 이어지게 합니다.
5. 최종 assistant 답변이 생성되면, 패키지가 그 최종 답변을 CLI 표시용으로 설정된 대상 언어로 번역합니다.
6. 패키지는 표시된 번역문과 함께 원래 영어 최종 답변을 기록합니다.
7. 이후 provider 요청에서는 표시된 번역 assistant 답변을 LLM 컨텍스트에서 원래 영어 텍스트로 바꿉니다.

이 패키지는 코딩 작업이 완료된 뒤 최종 답변만 의도적으로 번역합니다. 중간 메시지와 도구 호출은 영어로 유지하여 명령, 경로, JSON, 코드, 구조화된 도구 인자가 손상되는 것을 방지합니다. 향후 LLM 요청도 이전 최종 답변의 영어 버전을 보게 되므로 prompt cache 재사용에 유리하고, 번역된 assistant 기록을 누적하는 것보다 보통 토큰 사용량을 줄일 수 있습니다.

## 설치

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 모델을 번역에 사용합니다. 주요 코딩 모델은 에이전트 작업에 남겨 두고, 더 빠르거나 저렴한 모델을 번역에 사용하고 싶을 때 유용합니다.

## 번역하지 않는 항목

이 패키지는 다음 입력을 의도적으로 변경하지 않고 통과시킵니다.

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