| name | ppt-translator |
| description | Amazon Bedrock 기반 PowerPoint(.pptx) 번역. 서식·레이아웃·차트 메타(제목/축 등)를 보존하며 텍스트를 한국어(ko) 등 대상 언어로 변환. CLI(`python -m ppt_translator.cli`)·SQLite 캐시·용어집· 원문 언어 자동 감지. PPT/슬라이드 번역, pptx 한국어, Bedrock 프레젠테이션 번역, batch translate, dry-run 비용 추정. |
PPT Translator (한국어 변환)
Directory Convention (경로 혼동 방지)
스킬 설치 위치는 두 가지 중 하나다. 실행 전에 먼저 존재 여부를 확인한다.
| 케이스 | 경로 | 비고 |
|---|
| A. 글로벌 스킬 | ~/.claude/skills/ppt-translator | Claude Code 기본 설치 위치 (대부분의 환경) |
| B. 프로젝트 번들 | {WORKING_DIR}/skills/ppt-translator | application/ 하위에 동봉된 경우 |
먼저 ls ~/.claude/skills/ppt-translator/SKILL.md 또는 B 경로를 확인해 SKILL_DIR을 고정한 뒤 그 경로를 모든 명령의 cwd로 사용한다. python -m ppt_translator.cli가 ppt_translator 패키지를 찾으려면 CWD가 SKILL_DIR이어야 한다.
번들 구성
SKILL_DIR 기준의 상대 경로:
| 항목 | 경로 |
|---|
| 에이전트 지침 | SKILL.md (이 파일) |
| 패키지 | ppt_translator/ |
| CLI | python -m ppt_translator.cli (Click) |
| 의존성 | requirements.txt |
| 용어집 예시 | glossary.yaml — CWD에 ./glossary.yaml 이 있으면 자동 탐색 |
전체 옵션: python -m ppt_translator.cli --help 및 각 서브커맨드 --help.
구조·클래스: ppt_translator/ppt_handler.py (FormattingExtractor, TextFrameUpdater, PowerPointTranslator).
upstream 문서: ppt-translator
데이터 흐름 (수정 시 이 순서 유지)
- 진입:
cli.py (Click).
- 오케스트레이션:
ppt_handler.PowerPointTranslator — 슬라이드·도형·노트·차트 대상, 서식 보존 번역.
- LLM:
translation_engine.py + bedrock_client.py, config.Config 의 모델·토큰 한도.
- 원문:
language_detection.py — 자동 감지(옵션); 원문==대상이면 API 생략.
- 차트:
chart_handler.py — 메타 텍스트만 번역, 수치 유지.
- 후처리:
post_processing.py — PowerPointPostProcessor 등.
- 캐시·비용:
cache.py, pricing.py.
- 용어·프롬프트:
glossary.py, prompts.py.
별도 스크립트로 "간단 번역" 파이프라인을 만들지 말고 위 모듈을 확장한다.
한국어(ko) 기본값
ppt_translator/config.py 의 Config.DEFAULT_TARGET_LANGUAGE 는 기본 ko. 언어 미지정 시 대상은 한국어로 둔다. 한국어 폰트는 FONT_KOREAN / FONT_MAP['ko'].
사전 조건
- Python 3.11+
- AWS 자격 증명 + Bedrock 모델 액세스 (
AWS_REGION, BEDROCK_MODEL_ID 등 — ppt_translator/config.py)
- 선택:
SKILL_DIR/.env (config 가 패키지 상위 루트의 .env 를 로드)
실행 방법
Claude Code Bash tool (권장)
번역 실행은 반드시 dangerouslyDisableSandbox: true 로 호출한다. 기본 샌드박스는 두 가지를 모두 막는다:
- Bedrock API 호출의 SigV4 서명이 프록시에서 손상되어
IncompleteSignatureException 발생
~/Downloads/ 등 허용 목록 밖 경로에 쓰기 불가 (Operation not permitted)
사전에 사용자에게 외부 네트워크/쓰기 의도를 알리고 승인받는다.
python3 -c "import pptx, boto3, click, dotenv, yaml, tenacity, rich" \
|| pip install -r "$SKILL_DIR/requirements.txt" -q
cd "$SKILL_DIR" && python3 -m ppt_translator.cli translate \
INPUT.pptx -t ko --source-language en \
-o OUTPUT_ko.pptx 2>&1 | tail -60
translate 는 정상 완료 시 마지막 줄에 ✅ Translation completed: ... 를 찍고, 캐시 히트율·토큰 수를 요약해준다. tail 은 핵심 요약만 볼 수 있게 해준다.
execute_code / subprocess (대안)
import subprocess, sys, os
SKILL_DIR = "/Users/<user>/.claude/skills/ppt-translator"
subprocess.run([sys.executable, "-m", "ppt_translator.cli",
"translate", input_file, "-t", "ko", "-o", output_file],
cwd=SKILL_DIR, capture_output=False, text=True)
capture_output=False 를 유지해 진행 상황을 스트리밍한다.
CLI 서브커맨드 & 옵션 레퍼런스
공통 주의: 출력 경로는 --output이 아니라 반드시 -o / --output-file 을 사용한다.
translate — 전체 슬라이드 번역
python -m ppt_translator.cli translate INPUT_FILE [OPTIONS]
| 옵션 | 단축 | 설명 |
|---|
--target-language | -t | 대상 언어 (기본 ko) |
--output-file | -o | 출력 파일 경로 |
--model-id | -m | Bedrock 모델 ID |
--source-language | | 원문 언어 코드 (예: en). 생략 시 자동 감지 |
--no-detect-source | | 원문 언어 자동 감지 비활성화 (모델이 컨텍스트로 판단) |
--no-polishing | | 자연어 다듬기(polishing) 비활성화 |
--glossary | -g | 용어집 YAML 파일 (기본: CWD의 ./glossary.yaml) |
--cache-backend | | sqlite(기본) / memory / none |
--cache-path | | SQLite 캐시 경로 |
--no-cache | | 캐시 비활성화 |
--dry-run | | 비용 추정만 (번역·저장 없음) |
--no-charts | | 차트 메타 번역 건너뜀 |
translate-slides — 특정 슬라이드만 번역
python -m ppt_translator.cli translate-slides INPUT_FILE -s "1,3,5" -t ko -o output.pptx
python -m ppt_translator.cli translate-slides INPUT_FILE -s "2-4" -t ko -o output.pptx
| 옵션 | 단축 | 설명 |
|---|
--slides | -s | 슬라이드 번호. 쉼표 "1,3,5" 또는 범위 "2-4" (필수) |
(이하 translate와 동일) | | |
batch-translate — 폴더 내 전체 .pptx 일괄 번역
python -m ppt_translator.cli batch-translate INPUT_FOLDER -t ko -o OUTPUT_FOLDER
| 옵션 | 단축 | 설명 |
|---|
--target-language | -t | 대상 언어 |
--output-folder | -o | 출력 폴더 경로 |
--workers | -w | 병렬 처리 워커 수 (기본 4) |
--recursive / --no-recursive | -r / -R | 하위 폴더 재귀 처리 (기본: 활성화) |
(캐시·용어집·dry-run 등 translate와 동일) | | |
info — 슬라이드 정보 미리보기
python -m ppt_translator.cli info INPUT_FILE
함정 & 트러블슈팅
실제 실행에서 반복되는 이슈들:
- Bedrock
IncompleteSignatureException — 샌드박스가 SigV4 요청을 손상시킨다. dangerouslyDisableSandbox: true 로 실행해야 한다. (pip install/파일 읽기만 하는 단계에서는 샌드박스를 유지)
PermissionError: ~/Downloads/... — 같은 원인. 출력 파일이 ~/Downloads/, ~/Desktop/ 등 허용 목록 밖이면 샌드박스 비활성화 필요. 또는 {WORKING_DIR}/artifacts/ 등 쓰기 가능 경로로 출력.sqlite3.OperationalError: unable to open database file — 기본 캐시 경로(~/.ppt-translator/cache.db)가 샌드박스에서 못 열린다. --cache-backend memory 로 우회하거나 샌드박스를 비활성화한다. memory 캐시는 세션 종료 시 사라지므로 재실행 비용이 늘어남을 유의.- 원문 언어 감지는 1회 Bedrock 호출 —
language_detection.py 는 langdetect 패키지가 아니라 Bedrock 모델에 한 번 물어본다. 원문 언어를 이미 알면 --source-language en 을 명시해 불필요한 호출·비용을 줄인다.
- 로그가 매우 김 — 각 슬라이드마다 INFO 로그 수십 줄. Bash tool에서
2>&1 | tail -60 으로 잘라 요약만 확인한다. 실패 시 더 긴 tail 로 재확인.
--output 플래그 없음 — 반드시 -o / --output-file 사용.- 캐시 히트 278/278 등으로 토큰 0 — 이미 같은 원문을 번역했다는 뜻.
--no-cache 또는 캐시 경로 변경으로 재번역 강제 가능.
- 차트 숫자가 바뀐 것처럼 보일 때 —
chart_handler.py 는 메타 텍스트(제목/축)만 번역하고 수치는 그대로 둔다. 진짜 숫자가 바뀌었다면 버그이므로 --no-charts 로 재현 확인.
