---
name: pdf-translate
description: PDF 문서 번역 스킬. pdf-translate MCP 서버를 활용하여 PDF 파일을 통째로 번역한 새 PDF를 생성한다. 사용자가 로컬 파일 경로를 제공하며 "번역해줘", "translate", "한국어로", "일본어로" 등의 표현을 사용할 때 반드시 이 스킬을 사용한다. 논문, 보고서, 매뉴얼, 일반 문서 등 모든 PDF에 적용된다. 파일 경로가 포함된 번역 요청이 보이면 항상 이 스킬을 트리거할 것 — 사용자가 PDF를 채팅에 업로드할 필요 없이 로컬 경로만으로 번역이 가능하다.
---

# PDF Translate Skill

pdf-translate MCP 서버를 사용하여 PDF 문서를 번역된 PDF로 변환하는 스킬이다.
이 MCP는 사용자의 로컬 머신에서 동작하므로, **파일 경로만 있으면 PDF를 업로드받지 않아도 번역할 수 있다.**

## 핵심 원칙

- 사용자가 파일 경로를 제공하면 바로 번역을 진행한다.
- 파일이 존재하는지 확인하려고 시도하지 않는다. MCP가 로컬에서 직접 접근한다.
- 경로를 그대로 `extract_segments`의 `file` 파라미터에 전달한다.
- **중요:** `file` 파라미터에는 반드시 사용자가 메시지에 입력한 로컬 절대 경로를 사용한다. 첨부 파일의 내부 경로(`/mnt/user-data/uploads/...`)는 MCP 서버에서 접근할 수 없으므로 절대 사용하지 않는다.

## 번역 워크플로우 (5단계)

모든 MCP 호출은 비동기이다. check 툴은 내부에서 대기 후 결과를 반환하므로, 진행 중 응답이 오면 바로 다시 호출하면 된다.

### 1단계: 세그먼트 추출 시작

`pdf-translate:extract_segments` 호출:

| 파라미터 | 설명 | 기본값 |
|---------|------|--------|
| `file` | PDF 절대 경로 (사용자 제공 그대로) | 필수 |
| `lang_in` | 원본 언어 | `en` |
| `lang_out` | 번역 대상 언어 | `ko` |
| `output_dir` | 출력 디렉토리 (비우면 원본과 같은 위치) | `""` |
| `pages` | 번역할 페이지 범위 (예: `'1-7,10'`). 아래 "페이지 제외 처리" 참고. | `""` (전체) |

반환값: `session_dir` (세그먼트는 포함되지 않음, 비동기 처리)

### 2단계: 추출 완료 확인

`pdf-translate:check_extraction_status` 호출. 서버가 내부에서 대기 후 응답하므로 별도 대기 불필요.

| 파라미터 | 설명 | 기본값 |
|---------|------|--------|
| `session_dir` | 1단계에서 받은 세션 디렉토리 경로 | 필수 |
| `offset` | 세그먼트 시작 인덱스 | `0` |

- `status: "extracting"` → 아직 진행 중. 바로 다시 호출.
- `status: "done"` → 완료. 세그먼트와 번역 instruction 포함.
- `has_more: true` → 세그먼트가 더 있음. `offset`을 늘려서 다시 호출.

### 3단계: 세그먼트 번역

반환된 세그먼트를 Claude가 직접 번역한다.

**필수 규칙:**
- `{v0}`, `{v1}` 같은 **수식 플레이스홀더는 절대 건드리지 않는다.** 그대로 유지한다.
- MCP가 반환하는 instruction이 있다면 그것을 우선적으로 따른다.
- 전체 세그먼트를 먼저 훑어 용어를 파악하고, 일관된 용어를 사용한다.

번역 완료 후, `save_translated_segments(session_dir, segments_json)` 툴을 호출하여 저장한다.
여러 번 호출하면 누적 저장된다.

### 4단계: 번역 PDF 조립 시작

`pdf-translate:assemble_translated` 호출:

| 파라미터 | 설명 |
|---------|------|
| `session_dir` | 1단계에서 받은 세션 디렉토리 경로 |
| `glossary_json` | (선택) 용어집 JSON 문자열 |

비동기로 실행됨. 즉시 반환.

### 5단계: 조립 완료 확인

`pdf-translate:check_assembly_status` 호출. 서버가 내부에서 대기 후 응답.

| 파라미터 | 설명 |
|---------|------|
| `session_dir` | 세션 디렉토리 경로 |

- `status: "assembling"` → 아직 진행 중. 바로 다시 호출.
- `status: "success"` → 완료. 출력 PDF 경로 포함.

완료되면 출력 PDF 경로를 사용자에게 알려준다.

## 언어 코드 가이드

사용자 표현에서 언어를 추론한다:

| 표현 | lang_out |
|------|----------|
| 한국어로 / 한글로 | `ko` |
| 일본어로 | `ja` |
| 중국어로 | `zh` |
| 영어로 | `en` |
| 불어로 / 프랑스어로 | `fr` |
| 독일어로 | `de` |
| 스페인어로 | `es` |

명시하지 않으면 기본값 `ko` (한국어).

원본 언어(`lang_in`)도 마찬가지로 추론하되, 대부분 영어(`en`)이므로 명시하지 않으면 `en`.

## 페이지 제외 처리

사용자가 특정 페이지를 번역에서 제외하고 싶다고 하면, `pages` 파라미터로 변환한다.
`pages`는 **번역할 페이지**를 지정한다 (제외할 페이지가 아님).

### 변환 예시

| 사용자 요청 | pages 값 | 설명 |
|------------|----------|------|
| "참고문헌은 8-9페이지야" (10페이지 PDF) | `1-7,10` | 8-9 제외 |
| "뒤에 3페이지 빼줘" (15페이지 PDF) | `1-12` | 13-15 제외 |
| "1~7페이지만 번역해" | `1-7` | 8페이지 이후 제외 |
| "앞에 목차 2페이지 빼고" | `3-` | 1-2 제외 |
| 제외 요청 없음 | (비움) | 전체 번역 |

### 주의사항

- 사용자가 "제외"로 말하면 나머지를 `pages`로 변환해야 한다
- 전체 페이지 수를 모르면 사용자에게 물어본다
- `pages` 형식: 콤마로 구분, 범위는 하이픈 (예: `1-7,10,12-15`)
- `3-` = 3페이지부터 끝까지, `-5` = 처음부터 5페이지까지

## 예시 시나리오

**예시 1: 기본 번역**
```
사용자: '/Users/me/paper.pdf' 이거 한국어로 번역해줘
→ lang_out="ko"로 extract_segments 호출
```

**예시 2: 다른 언어**
```
사용자: '/Users/me/report.pdf' 일본어로 번역해줘
→ lang_out="ja"로 extract_segments 호출
```

**예시 3: 페이지 제외**
```
사용자: '/Users/me/paper.pdf' 번역해줘. 참고문헌은 22-24페이지야
→ pages="1-21"로 extract_segments 호출
```

**예시 4: 비연속 페이지**
```
사용자: '/Users/me/thesis.pdf' 번역해줘. 8-9페이지는 부록이라 빼줘 (총 10페이지)
→ pages="1-7,10"로 extract_segments 호출
```
