팀에서 문서 번역을 자동화하려면 품질·비용·속도 사이의 균형이 필요합니다. DeepL Pro API는 높은 번역 품질과 문서 서식 보존을 강점으로 하지만, 올바른 연동과 파이프라인 설계 없이는 기대만큼의 효율을 얻기 어렵습니다. 이 글은 DeepL Pro API로 문서 번역 시스템을 구축·운영할 때 꼭 알아야 할 설정, 용어집 관리, 형식 보존, 오류·비용 대처 팁을 실무 관점에서 정리했습니다.
1) 시작 전 준비 체크리스트
- 계정·요금제: 문서 번역 및 용어집 기능 지원 여부, 문자 수 과금/제한 정책을 확인합니다.
- 인증 키 관리: 서버 측 안전한 저장소(예: 환경변수, 시크릿 매니저) 사용, 키 회전 계획을 마련합니다.
- 네트워크/보안: 방화벽 아웃바운드 허용, 요청/응답 로그에서 원문 민감정보 마스킹 처리.
- SDK/런타임: 공식 HTTP 엔드포인트를 기본으로, 언어별 HTTP 클라이언트 혹은 경량 SDK를 선택합니다.
- 파일 형식: DOCX, PPTX, PDF 등 지원 범위와 제한 사항을 문서로 확인하고 샘플로 사전 검증합니다.
2) 기본 요청 패턴 이해하기
DeepL Pro API는 텍스트 단위 번역과 문서 번역(비동기) 두 흐름이 있습니다. 파일 기반 워크플로우는 문서 번역 엔드포인트를 중심으로 구성하세요.
텍스트 번역 예시
curl -X POST 'https://api.deepl.com/v2/translate' \
-H 'Authorization: DeepL-Auth-Key YOUR_API_KEY' \
-d 'text=Hello world' \
-d 'target_lang=KO' \
-d 'preserve_formatting=1'
자주 쓰는 옵션: target_lang, source_lang, preserve_formatting, formality, glossary_id, tag_handling(html/xml), ignore_tags, non_splitting_tags 등.
문서 번역(비동기) 예시
# 1) 업로드
curl -X POST 'https://api.deepl.com/v2/document' \
-H 'Authorization: DeepL-Auth-Key YOUR_API_KEY' \
-F 'file=@/path/to/file.docx' \
-F 'target_lang=EN-US' \
-F 'glossary_id=YOUR_GLOSSARY_ID'
# 2) 상태 조회
où curl -G 'https://api.deepl.com/v2/document/{document_id}' \
-H 'Authorization: DeepL-Auth-Key YOUR_API_KEY' \
--data-urlencode 'document_key={document_key}'
# 3) 결과 다운로드
curl -L 'https://api.deepl.com/v2/document/{document_id}/result' \
-H 'Authorization: DeepL-Auth-Key YOUR_API_KEY' \
--data-urlencode 'document_key={document_key}' \
-o result.docx
문서 번역은 업로드 → 상태 폴링 → 결과 다운로드의 3단계로 처리됩니다. 큰 파일은 처리 시간이 길 수 있으니 대기/재시도 로직을 반드시 넣으세요.
3) 비동기 처리와 큐 설계
- 작업 큐: 업로드 후 document_id/document_key를 안전하게 저장하고, 상태 조회를 주기적으로 큐에서 수행합니다.
- 폴링 주기: 초기엔 짧게, 일정 시간 이후엔 간격을 늘리는 점진적 폴링으로 과도한 호출을 막습니다.
- 재시도 전략: 네트워크 일시 오류는 지수적 백오프로 재시도, 영구 오류는 즉시 중단·알림 처리.
- 중복 방지: 파일 해시(SHA-256 등)로 동일 문서 재요청을 피하고, 캐시된 번역 결과를 재사용합니다.
- 동시성: 계정 한도와 서버 리소스를 고려해 동시 업로드 수를 제한하고, 우선순위(긴급/일반) 큐를 분리합니다.
4) 용어집(Glossary) 제대로 운영하기
전사 용어 일관성은 문서 번역 품질을 좌우합니다. 팀 합의된 표기 기준을 용어집으로 고정하고, 버전 관리를 병행하세요.
용어집 생성/적용
# 용어집 생성(예: KO → EN-US)
curl -X POST 'https://api.deepl.com/v2/glossaries' \
-H 'Authorization: DeepL-Auth-Key YOUR_API_KEY' \
-d 'name=my-ko-en' \
-d 'source_lang=KO' \
-d 'target_lang=EN-US' \
--data-binary $'entries=딥러닝\tdeep learning\n문서\tdocument'
# 번역 시 적용(텍스트/문서 모두 가능)
-d 'glossary_id=YOUR_GLOSSARY_ID'
- 운영 팁: 제품명/브랜드/약어를 최우선 관리, 릴리스 노트 기반으로 주기적 업데이트.
- 충돌 해결: 중복 항목은 소스 우선순위를 정하고, 리뷰 워크플로우(작성→검토→배포)를 둡니다.
- 테스트: 대표 문서 샘플로 A/B 비교 후 용어집 변경을 배포합니다.
5) 형식 보존과 HTML 처리
문서 번역은 기본적으로 레이아웃을 보존합니다. 웹 콘텐츠나 리치 텍스트는 태그 처리 옵션을 적극 활용하세요.
# HTML 번역에서 코드/프리 태그 제외, 제목은 문장 분리 방지
-d 'tag_handling=html' \
-d 'ignore_tags=code,pre' \
-d 'non_splitting_tags=h1,h2,h3' \
-d 'preserve_formatting=1'
- 전처리: 반복 배너/푸터, 자동 생성 목차 등 의미 없는 텍스트는 제외해 비용과 잡음을 줄입니다.
- 후처리: 특수문자 이스케이프, 링크·앵커 확인, 표·도형 캡션의 번호 일관성 점검.
- PDF 주의: 스캔·이미지 기반 PDF는 OCR 품질에 따라 결과가 달라질 수 있으니 원본 편집 가능한 포맷을 권장합니다.
6) 품질·비용·속도 최적화 팁
- 캐시 전략: 동일 문장/문단 해시 기반 캐시로 재번역을 회피, 다국어 사이트에 특히 효과적입니다.
- 텍스트 정리: 코드 블록, 로그, 긴 숫자열은 제외하거나 별도 처리해 불필요한 과금을 줄입니다.
- 배치 처리: 유사 문서 묶음 배치와 야간 처리로 운영 비용과 사용자 체감 속도를 균형화합니다.
- 폼얼리티(formality): 대상 언어/콘텐츠 톤에 맞게 설정해 후편집 시간을 절감합니다.
- 샘플링 리뷰: 고가치 페이지는 사람이 마지막에 샘플링 검수하여 브랜드 톤과 용어 일관성을 확보합니다.
7) 오류 대응과 모니터링
- 에러 분류: 인증 실패, 파라미터 오류, 속도 제한, 사용량·요금 한도 초과, 파일 형식 문제로 구분해 대응합니다.
- 로그 설계: 요청 파라미터 요약, 응답 상태/메시지, 재시도 횟수, 처리 시간, 문서 ID를 구조화해 저장합니다.
- 알림: 치명 오류는 즉시 알림, 비정상 지연(평균 대비 초과)은 경보 임계치를 둡니다.
- 폴백: 장애 시 텍스트 엔드포인트로 긴급 전환하거나, 대기열 유지 후 자동 재개 전략을 마련합니다.
8) 보안·컴플라이언스 포인트
- 민감정보: 번역 대상에서 주민번호·계좌번호 등 PII는 마스킹/제거 후 처리합니다.
- 데이터 보관: 원문/번역문 저장 기간을 최소화하고, 암호화 저장·전송을 적용합니다.
- 접근 통제: API 키·용어집 관리 권한을 최소 권한 원칙으로 분리합니다.
9) 배포 전 최종 체크리스트
- 샘플 스모크 테스트: 대표 포맷(DOCX/PPTX/PDF/HTML) 각 1건 이상 성공 확인.
- 성능 점검: 최대 동시 처리량과 평균 대기시간 측정, 큐 임계치 설정.
- 롤백 계획: 새 설정/용어집 배포 시 문제 발생에 대비한 즉시 복구 경로 확보.
- 문서화: 운영 절차, 한도·과금 정책 링크, 자주 발생하는 오류와 해결책을 위키로 공유.
마무리: 빠른 시작 요약
- API 키 발급 및 안전 보관 → 샘플 문서로 업로드/다운로드 흐름 검증
- 큐·폴링·재시도 로직 구현 → 해시 캐시로 중복 번역 방지
- 팀 용어집 확정·버전 관리 → HTML 태그 처리/전처리 규칙 적용
- 모니터링·알림·폴백 준비 → 샘플링 리뷰로 품질 최종 보정
위 순서만 지켜도 DeepL Pro API 기반 문서 번역은 안정성과 효율을 모두 갖추기 쉽습니다. 작은 파일·짧은 텍스트에서 시작해 점진적으로 범위를 확장하세요.
