# pi-trans

[English](README.md) · **한국어** · [日本語](README.ja.md) · [简体中文](README.zh-CN.md)

**Pi와 내 언어로 이야기하세요. 에이전트는 그대로 영어로 일합니다.**

한국어, 일본어, 중국어, 스페인어…로 입력하면 모델에게는 깔끔한 영어가 전달됩니다. 모델은 영어로
답하고, 문단마다 바로 아래에 차분한 번역이 붙습니다. 코드는 손대지 않습니다.

```
pi install npm:@wkbae/pi-trans
```

## 왜 쓰나요

- **생각은 내 언어로, 세션은 영어로.** 모델은 언제나 영어만 읽습니다. 그래서 답변도, 레포에 남기는
  것(주석, 커밋 메시지, 문서)도 나머지 코드처럼 영어로 나옵니다.
- **원문을 읽고, 번역은 곁눈질로.** 영어가 본문으로 남아 정확한 표현과 기술 용어를 그대로 볼 수 있고,
  번역은 그 아래 흐린 색으로 붙어 필요할 때만 보면 됩니다.
- **기다림이 없습니다.** Enter를 누르기 전에 프롬프트의 영어가 이미 준비돼 있고, 답변은 백그라운드에서
  번역되어 에이전트를 붙잡지 않습니다.

## 무엇을 해주나요

**입력하는 동안 영어 미리보기.** 편집기 위 한 줄에 모델이 읽을 영어가 보입니다(`EN ▸ …`). Enter를
누르면 그 영어가 그대로 전송되고, 추가 왕복은 없습니다. 대화 기록에는 내가 입력한 문장이 남고, 그 아래에
영어가 붙습니다:

```
users.js의 loadUsers가 왜 느린지 한 문장으로 말하고 바로 고쳐줘

  ↳ In one sentence, tell me why users.js's loadUsers is slow, then fix it right away
```

**코드를 아는 번역.** 코드 블록, `인라인 코드`, 경로, URL, 플래그, `snake_case`, `camelCase`,
`dotted.members`는 번역기로 보내지 않습니다. 자리표시자로 바꿔 보냈다가 바이트 하나 다르지 않게 되돌려
놓습니다. 제목, 목록, 인용, 표도 줄 단위로 모양을 유지합니다.

**답변 보기 방식 선택.** `/translate view <mode>`로 대화 기록 전체를 다시 그립니다:

| 보기 | 보이는 모습 |
| --- | --- |
| `stacked` | 모델이 쓴 문단 그대로, 바로 아래에 들여쓰고 흐리게 처리한 번역 |
| `side` | 왼쪽 영어, 오른쪽 번역, 블록 단위로 나란히 |
| `translated` | 번역만, 코드는 제자리에 |
| `interleave` | 문단마다 그 번역을 인용으로 |
| `below` | 영어 답변 전체 뒤에 번역 전체 |
| `original` | 영어만 |
| `auto` (기본) | 터미널이 140칸 이상이면 `side`, 아니면 `stacked` |

**어떤 언어든, 어떤 번역기든.** 기본으로는 Pi에 이미 로그인해 둔 제공자의 작은 모델(Haiku 모델이 있으면
그것)이 번역합니다. 따로 설정할 것이 없습니다. 다른 번역기를 쓰고 싶다면 OpenAI 호환 서버(Ollama,
LM Studio, DeepSeek, OpenRouter)나 직접 만든 프로그램(Apple Translation, DeepL, Papago)에 연결하면 됩니다.

## 사용법

| 명령 | |
| --- | --- |
| `/translate` | 번역 켜기/끄기 |
| `/translate view <mode>` | 답변 보기 방식 바꾸기 |
| `/translate status` | 언어, 엔진, 보기 방식, 대기열 |
| `/translate:settings` | 아래 옵션 바꾸기 |

푸터에 지금 돌아가는 것이 보입니다. 예: `ko↔en · claude-haiku-4-5 · 2 queued`.

## 내 언어 설정

pi-trans는 다음 순서로 언어를 정합니다: 자신의 `language` 옵션, 시스템 로케일(`LC_ALL`,
`LC_MESSAGES`, `LANG`). 코드(`ko`, `ja`, `zh`, `es`)도 이름(`Korean`, `日本語`)도 됩니다. 아무것도
설정돼 있지 않거나 영어라면 아무 일도 하지 않습니다.

## 번역 엔진

| 엔진 | 설정 | 비고 |
| --- | --- | --- |
| `model` (기본) | 없음 | Pi 제공자의 모델을 사용. `model` 옵션으로 고름 |
| `openai` | `openaiBaseUrl`, `openaiModel`, 선택 `openaiApiKey` | OpenAI 호환 서버 아무거나: Ollama, LM Studio, DeepSeek, OpenRouter… |
| `command` | `command` | 직접 만든 프로그램: stdin으로 `{"from","to","lines":[…]}`, stdout으로 `{"lines":[…]}` |

`openai`나 `command`가 실패하면 `model`이 대신 번역합니다(`fallback`을 끄지 않았다면).

## 옵션

`/translate:settings`에서 바꾸거나, `~/.pi/agent/pi-trans.json`에 적고 `/reload` 하세요:

```json
{ "language": "ko", "defaultView": "stacked" }
```

| 옵션 | 기본값 | |
| --- | --- | --- |
| `language` | 비어 있음 | 내 언어. 비워 두면 시스템 로케일을 따름 |
| `engine` | `model` | `model` · `openai` · `command` |
| `defaultOn` | `true` | Pi를 시작할 때 번역을 켬 |
| `defaultView` | `auto` | 위의 보기 방식 참고 |
| `preview` | `true` | 입력 중 영어 미리보기 |
| `model` | 비어 있음 | model 엔진이 쓰는 모델. `provider/id` 또는 id. 비워 두면 Haiku 모델, 없으면 세션의 모델 |
| `openaiBaseUrl` · `openaiModel` · `openaiApiKey` | | openai 엔진용 |
| `command` | | command 엔진용 |
| `fallback` | `true` | 실패하면 model 엔진으로 대신 번역 |

## 자주 묻는 질문

**내 코드가 번역기로 가나요?** 아니요. 보내는 건 글뿐입니다. 코드 블록은 건너뛰고, 인라인 코드, 경로,
URL, 식별자는 밖으로 나가기 전에 자리표시자로 바꿉니다.

**비용은 얼마나 드나요?** 기본 엔진에서는 번역이 내 계정으로 그 모델을 호출하는 것입니다. 짧은 글만 보내고,
각 줄은 세션 동안 캐시되므로 같은 줄을 두 번 번역하지 않습니다. 끝난 번역은 세션 파일에 저장되므로, 세션을
다시 열어도 다시 요청하지 않고 그대로 보여 줍니다. `openai`(예: 로컬 Ollama)나 `command`를 쓰면 그
엔진의 비용만 듭니다.

**번역이 실패하면요?** 프롬프트는 입력한 그대로 전송되고 알림으로 이유를 알려 줍니다. 답변 블록은 영어로
남고 번역이 실패했다고 표시됩니다. 무엇도 막히지 않습니다.

**print 모드나 RPC 모드에서도 되나요?** 프롬프트는 모든 모드에서 번역됩니다. 답변 번역은 대화형
터미널에서만 그려집니다.

## 개발

```
npm install
pi -e .                 # load it for one run
npm test
npm run check           # tsc
vhs demo/demo.tape && demo/render.sh   # record a demo (needs vhs, ffmpeg, gifsicle)
```

단위 모델과 표시 규칙은 [DESIGN.md](DESIGN.md)(영어)에 있습니다.

## 라이선스

MIT
