maenjh / ko-paper

# ko-paper
논문 PDF(기본 영어, 독일어·프랑스어·일본어 등 10개 언어)를 그림·표·수식 위치를 유지한 채 한글 PDF로 번역한다.
레이아웃 처리는 BabelDOC, 번역은 Claude(또는 Codex)가 맡는다.
Claude Code나 Codex에 스킬로 설치하면 "이 논문 번역해줘" 한마디로 쓸 수 있다.
 예시는 이 README를 위해 직접 쓴 샘플 논문이다(HTML ·
원문 PDF · 한글본 ·
병기본). 2쪽, Claude Sonnet, 약 40초. 
> **각자 자기 컴퓨터에서, 자기 계정으로 쓰는 도구다.** 기본 백엔드는 로컬에 로그인된
> Claude Code(`claude -p`), 또는 Codex(`codex exec`)라서 번역에 쓰는 사용량은 실행한 사람의
> 구독에서 나간다. 이 백엔드로 서버를 띄워 다른 사람에게 번역을 제공하면 안 된다. 그런 용도라면
> `KOPAPER_BACKEND=anthropic-api`(API 키, 종량제)를 쓴다. 웹 UI도 항상 127.0.0.1에만 열린다.
## 사용 예시
**그림·표·수식은 그 자리에 그대로 둔다.** 그림 안의 범례와 항목 이름, 표의 머리글과 셀까지 번역하고,
수식과 숫자는 건드리지 않는다. 세로로 회전된 축 이름처럼 일부 글자는 원문으로 남을 수 있다.
**웹 UI** — PDF를 끌어다 놓고 원문 언어·모델·출력 형식을 고르면 된다. 완료된 작업에서 한글본을
바로 열거나, 용어집을 고쳐 바뀐 문단만 다시 번역할 수 있다.
## 공유·사용 전에 알아 둘 것
- **번역은 내 구독 사용량을 쓴다.** 각자 자기 Claude 또는 ChatGPT 계정으로 번역한다. 예를 들어 31쪽 논문을
 Claude Sonnet으로 번역했을 때 호출 약 200회, 토큰 약 67만 개가 들었다. 구독 등급에 따라 한도에 금방
 닿을 수 있다. 같은 논문을 다시 번역하면 캐시를 써서 훨씬 적게 든다.
- **논문 본문이 AI 회사로 전송된다.** 번역을 위해 PDF의 텍스트가 Anthropic(Claude) 또는 OpenAI(Codex)로 간다.
 기밀 문서, 공개 전 원고, 개인정보가 담긴 문서에는 쓰지 않는다. 일반 모드는 참고문헌을 보내지 않지만,
 간이 모드는 에이전트가 PDF 전체를 읽는다.
- **번역본은 개인 학습용이다.** 원 논문의 저작권은 저자와 출판사에 있다. 번역한 PDF를 다시 배포하기 전에
 원문의 라이선스를 확인한다.
- **내 구독으로 서비스를 열지 않는다.** 이 도구로 서버를 띄워 다른 사람에게 번역을 제공하면 안 된다.
 그런 용도라면 `KOPAPER_BACKEND=anthropic-api`(API 키, 종량제)를 쓴다.
- **알려진 한계:** Windows에서 Smart App Control이 켜져 있으면 레이아웃 유지 번역이 막힌다(아래
 Windows Smart App Control). 작은 대문자 제목, 회전된 축 이름처럼 일부 레이아웃은
 완벽하지 않다(레이아웃 보정).
- **문제가 생기면** 이슈로 남겨 준다. 운영체제, 설치 방법,
 `ko-paper doctor` 출력을 함께 적어 주면 빨리 고칠 수 있다.
## 스킬로 설치 (권장)
준비물: Claude Code 또는 Codex 로그인,
uv, git. BabelDOC과 Python 의존성은 처음 실행할 때 자동으로 설치된다.
번역 백엔드는 `claude`가 있으면 Claude Code, 없고 `codex`만 있으면 Codex로 자동으로 고른다.
**에이전트에게 맡기기** — 아래 글을 Claude Code나 Codex에 그대로 붙여 넣으면 묻지 않고 끝까지 설치한다.
 [code] 
**플러그인으로** (Claude Code)
 [code] 
**스크립트로** (`~/.ko-paper/src`에 받고, 찾은 에이전트마다 스킬을 복사)
 [code] 
**Windows** (PowerShell)
 [code] 
git이 필요하다(`winget install --id Git.Git -e`). Windows의 Claude Code는 Git Bash로 명령을 실행하므로
스킬은 `kopaper.sh`를, Codex·PowerShell에서는 `kopaper.ps1`을 쓴다.
`ko-paper update`(또는 설치 명령을 다시 실행)로 최신 버전을 받는다. 처음 설치한 에이전트에만 다시 설치한다.
## ChatGPT·Claude·Codex 앱만 쓴다면
터미널 도구 없이 ChatGPT, Claude, Codex **앱**만 쓰는 사람도 설치할 수 있다. 명령을 직접 실행할 수 있는 앱
(Claude 데스크톱 앱의 Code·Cowork, Codex 앱)은 알아서 설치까지 끝낸다. 실행할 수 없는 채팅 앱은 터미널에
붙여 넣을 명령을 알려 주고 결과를 보고 다음 단계를 안내한다. 문구에 "묻지 말라"를 넣어 두어, 앱이 첫 답변에서 바로 설치 명령을 준다. 번역은 내 Claude 또는 ChatGPT 구독으로 돌아간다(Claude 구독은
Claude Code로, ChatGPT 구독은 Codex CLI로 로그인해서 쓴다).
아래 글을 그대로 복사해 ChatGPT, Claude, Codex 앱에 붙여 넣는다.
 [code] 
설치가 끝나면 앱 없이도 쓸 수 있다.
 [code] 
**Claude 데스크톱 앱의 Code 탭**은 Claude Code와 같아서, 위 "에이전트에게 맡기기"처럼 말하면 알아서
설치한다. claude.ai·ChatGPT의 웹 채팅이 자체 샌드박스에서 PDF를 직접 번역하는 것은 지원하지 않는다
(BabelDOC과 내 구독 로그인이 내 컴퓨터에 있어야 한다).
설치 후 Claude Code에서 PDF 경로와 함께 요청하면 된다.
 [code] 
결과는 입력 파일 옆에 ` .ko.pdf`(한글본)와 ` .ko.dual.pdf`(원문 병기본)로 생긴다.
스킬로 실행할 때 캐시·용어집·작업 로그는 `~/.ko-paper/data`에 쌓인다.
## Windows Smart App Control
Windows 11의 **Smart App Control**(SAC)은 서명이 없고 평판이 쌓이지 않은