DeepL Pro API는 단순 텍스트 번역을 넘어 문서 단위의 비동기 처리, 용어집(Glossary) 적용, 서식 보존까지 지원해 팀 단위 번역 워크플로에 적합합니다. 이 글은 실제 운영에 바로 넣을 수 있는 파이프라인 설계, 품질·비용 최적화, 에러 대응 팁을 단계별로 정리합니다.
연동 전 체크리스트
- 인증 키 보관: 환경 변수나 시크릿 매니저에 저장하고 코드·로그에 노출하지 않습니다.
- 요금제·한도: 사용량(문자 기준)과 동시 작업 수 제한을 확인해 배치 크기와 큐를 설계합니다.
- 지원 포맷: docx, pptx, xlsx, pdf, html, txt 등 문서 번역 대상 형식을 사전 점검합니다.
- 개인정보·보안: 문서 내 PII는 마스킹/가명처리 후 전송하고, 원문·결과물 보관 정책을 명확히 합니다.
- 언어 옵션: 대상 언어, 문체(formality), 문장 분할(split) 등 파라미터를 요구사항에 맞춰 표준화합니다.
번역 파이프라인 아키텍처
규모가 커질수록 “업로드 → 상태 확인 → 결과 다운로드”의 비동기 흐름에 큐·재시도·모니터링을 더한 파이프라인이 안정적입니다.
권장 흐름
- 수집: 사용자가 업로드한 문서를 스토리지(Object Storage)에 저장하고 작업 메타를 생성합니다.
- 업로드: DeepL Pro API 문서 엔드포인트로 업로드하고 document_id, document_key를 안전하게 보관합니다.
- 큐잉: 작업 큐(예: SQS, Redis)로 상태 폴링/콜백 태스크를 스케줄링합니다.
- 상태 확인: 완료/실패/진행률을 주기적으로 조회하거나, 내부 스케줄러에서 백오프를 적용해 폴링합니다.
- 다운로드: 번역이 끝나면 결과 파일을 내려받아 버전 태그를 붙여 저장합니다.
- 후처리: 용어 일치 검수, 링크/숫자/단위 점검, QA 리포트를 생성합니다.
의존성·중복 방지
- 멱등성 키: 파일 해시를 작업 키로 삼아 같은 파일이 재요청돼도 중복 과금·중복 번역을 막습니다.
- 버전 관리: 원문 v1 → 번역 v1처럼 페어링 규칙을 정해 롤백과 비교 검수가 쉽도록 합니다.
문서 번역 실무 팁
- 스캔 PDF는 OCR 전처리: 스캔본은 텍스트 추출 품질에 따라 결과가 크게 달라집니다. OCR 후 깨진 글꼴·줄바꿈을 정리하고 번역하세요.
- 서식 보존: 문서 번역 엔드포인트는 원본 레이아웃을 최대한 유지합니다. 표/머리글/각주가 무너진다면 원문 스타일을 정리하고 다시 시도합니다.
- 대용량 분할: 한 번에 처리하기 어려운 경우 파일을 논리 단위로 분할해 병렬 처리하되, 최종 병합 시 머리글/목차 재작성 규칙을 둡니다.
용어집 관리 전략
용어집(Glossary)은 브랜드·제품명·전문용어를 일관되게 만드는 핵심 도구입니다.
- 형식: 일반적으로 탭 구분(TSV) “원문↔대상어” 쌍을 사용합니다. 대소문자/복수형 등 변형 케이스를 별도 행으로 관리합니다.
- 언어쌍 분리: EN→KO, KO→EN처럼 방향별 용어집을 분리해 예외 처리와 QA가 쉬워집니다.
- 버전·승인: PR 형태 리뷰로 v1.2, v1.3처럼 배포 버전을 명시하고, 번역 전에 어느 버전을 적용했는지 메타에 기록합니다.
- 도메인별 운영: 법무/마케팅/개발 문서처럼 도메인별 용어집을 분리하고 작업별로 선택 적용합니다.
- 자동 검증: 번역 결과에서 용어 미적용·오용 사례를 추출해 용어집 보강 루프를 만듭니다.
HTML·웹 콘텐츠 번역시 주의
웹 콘텐츠는 문서 번역 대신 텍스트 번역 엔드포인트에 HTML 핸들링 옵션을 주는 것이 유리할 때가 많습니다.
POST https://api.deepl.com/v2/translate
- parameters:
text=<p class="desc">Welcome <strong>developers</strong>!</p>
target_lang=KO
tag_handling=html
ignore_tags=code,pre
split_sentences=1
preserve_formatting=1
이렇게 하면 코드 블록을 건드리지 않고 텍스트만 자연스럽게 번역할 수 있습니다.
에러 핸들링과 재시도
- 429(요청 과다): 지수 백오프(예: 1s→2s→4s)와 Jitter를 적용합니다.
- 4xx(잘못된 요청): 파라미터·파일 포맷·언어 코드를 점검해 즉시 실패 처리하고 재시도하지 않습니다.
- 5xx(서버 오류): 짧은 백오프 후 제한된 횟수 내 재시도하고, 초과 시 운영자 알림을 보냅니다.
- 타임아웃: 문서 크기에 따라 처리 시간이 길 수 있으므로 상태 폴링 간격과 전체 타임아웃을 현실적으로 설정합니다.
사용량 모니터링
사용량 엔드포인트로 일간·월간 문자 수를 수집하고 임계치 알림을 설정하세요.
curl -s -H "Authorization: DeepL-Auth-Key <YOUR_API_KEY>" \
https://api.deepl.com/v2/usage
데이터를 대시보드로 시각화하면 과금 급증이나 비정상 트래픽을 조기 감지할 수 있습니다.
비용 최적화 체크리스트
- 중복 제거: 문단/문서 해시로 캐싱해 동일 콘텐츠 재번역을 막습니다.
- 부분 업데이트: 변경분만 추출해 증분 번역을 적용합니다. CMS와 Git diff를 활용하면 좋습니다.
- 엔드포인트 선택: 단락·웹 UI 텍스트는 텍스트 번역, 레이아웃이 중요한 보고서는 문서 번역을 사용합니다.
- 전처리로 쓰레기 줄이기: 불필요한 공백·머리글·주석을 제거해 문자 수를 절감합니다.
- QA 루프: 용어·숫자·단위 자동 검사를 통해 재작업(재번역) 비용을 낮춥니다.
보안·개인정보 보호
- 토큰 관리: 서버 사이드에서만 API 키를 사용하고, 프론트엔드 직접 호출을 금지합니다.
- PII 마스킹: 이메일, 전화번호, 주민(외국인)등록번호 등 식별값은 토큰 형태로 치환했다가 사후 복원합니다.
- 감사 로그: 누가 어떤 문서를 언제 번역했는지 작업·접근 로그를 남기고 보관 기간을 명시합니다.
문서 번역 요청의 표준 절차(개요)
- 업로드: 파일과 대상 언어를 전송하고 document_id, document_key를 받습니다.
- 상태 조회: 일정 간격으로 상태를 확인해 완료/실패를 판정합니다.
- 다운로드: 결과 파일을 저장소에 보관하고 메타데이터(언어, 용어집 버전, 처리 시간)를 기록합니다.
# Pseudo-flow (언어 불문)
1) POST /v2/document (file, target_lang, source_lang?) → {document_id, document_key}
2) GET/POST /v2/document/{document_id} (document_key) → {status, seconds_remaining?}
3) GET/POST /v2/document/{document_id}/result (document_key) → binary file
SDK를 사용하면 업로드·상태 확인·다운로드를 단일 호출로 감싸는 기능을 제공하므로, 내부적으로만 폴백 로직을 더해 안정성을 높이면 됩니다.
사람-기계 협업(HAIT) 운영
- 고위험 문서: 계약, 규정, 의학·법률처럼 오류 비용이 큰 문서는 반드시 2차 휴먼 리뷰를 거칩니다.
- 샘플링 QA: 낮은 위험 문서라도 무작위 샘플을 정기 검수해 품질 드리프트를 막습니다.
- 피드백 루프: 리뷰 코멘트를 용어집·스타일 가이드에 반영하고 다음 배치에 자동 적용합니다.
운영 자동화 팁
- CI/CD: 번역 서비스 컨테이너 이미지를 고정 태그로 배포하고, API 키는 런타임에 주입합니다.
- 알림: 상태 실패·재시도 초과·사용량 임계 알림을 Slack/메일로 통합합니다.
- 대체 경로: 외부 장애 시 대기열 정지, 업로드 보류, 관리자 승인 후 재개 같은 수동 플랜을 마련합니다.
빠른 시작을 위한 cURL 예시
텍스트 번역
curl -s -X POST https://api.deepl.com/v2/translate \
-H "Authorization: DeepL-Auth-Key <YOUR_API_KEY>" \
-d "text=Hello, world!" \
-d "target_lang=KO"
용어집 생성(예: EN→KO)
curl -s -X POST https://api.deepl.com/v2/glossaries \
-H "Authorization: DeepL-Auth-Key <YOUR_API_KEY>" \
-F name=my-enko-glossary \
-F source_lang=EN \
-F target_lang=KO \
-F entries=@terms.tsv;type=text/tab-separated-values
문서 번역(개요)
# 1) 업로드
curl -s -X POST https://api.deepl.com/v2/document \
-H "Authorization: DeepL-Auth-Key <YOUR_API_KEY>" \
-F "file=@report.docx" \
-F "target_lang=KO"
# 2) 상태 확인 / 3) 결과 다운로드
# document_id, document_key를 응답에서 받아 안전하게 저장한 뒤
# 상태 확인과 결과 다운로드 요청에 함께 전달합니다.
체크리스트로 마무리
- 비동기 파이프라인: 큐·재시도·멱등성으로 안정성 확보
- 용어집 운영: 버전·도메인 분리와 자동 검증 루프
- 품질·서식: OCR·전처리, HTML 태그 보존, 후처리 QA
- 에러·모니터링: 백오프·임계 알림·사용량 대시보드
- 비용: 중복 제거·증분 번역·엔드포인트 선택
위 원칙만 지켜도 DeepL Pro API를 팀 워크플로에 자연스럽게 녹여, 문서 번역의 속도·일관성·안정성을 모두 끌어올릴 수 있습니다.
