왜 문서 번역 워크플로우를 표준화해야 할까
DeepL Pro API를 도입하면 초기에 속도와 품질이 크게 개선됩니다. 하지만 팀 규모가 커지고 파일 포맷이 늘어나면 번역 품질 편차, 비용 예측 실패, 장애 대응 미흡 같은 문제가 곧바로 드러납니다. 표준화된 워크플로우를 구축하면 다음을 안정적으로 달성할 수 있습니다.
- 품질 일관성: 용어집과 스타일 규칙을 체계적으로 반영
- 형식 보존: 문서 포맷별 특성에 맞춘 안전한 처리
- 비용·속도 통제: 캐시·비동기 번역·재시도 정책으로 낭비 최소화
- 운영 가시성: 상태 추적·로그·알림으로 장애를 조기에 감지
아키텍처 개요: 요청부터 배포까지
1) 인증·라우팅
DeepL Pro API 키는 환경 변수나 시크릿 매니저에 저장하고, 사내 서비스는 번역 요청을 중앙 게이트웨이로 라우팅해 공통 정책(레이트 리밋, 로깅, 캐시)을 적용합니다. 유료 엔드포인트(예: api.deepl.com/v2)를 사용하고, 테스트·스테이징·프로덕션 키를 분리해 사고 범위를 제한합니다.
2) 동기 vs 비동기 번역
- 텍스트 번역(/translate): 소량 문자열·HTML 조각에 적합. 빠른 응답이 필요한 UI 문자열에 사용.
- 문서 번역(/document): DOCX, PPTX, PDF 등 대용량 문서에 권장. 업로드→상태 조회→다운로드의 비동기 플로우로 처리합니다.
같은 요청을 여러 번 보내지 않도록 작업 ID 기반의 멱등 처리와 캐시를 두면 비용과 대기 시간을 줄일 수 있습니다.
3) 스토리지·상태 추적
원본/결과 파일은 객체 스토리지에 저장하고, DeepL 문서 ID·키, 타임스탬프, 매개변수(formality, glossary_id 등)를 메타데이터로 기록합니다. 상태는 폴링 또는 웹훅(중간 프록시 활용)으로 갱신하고, SLA 초과 시 알람을 보냅니다.
포맷별 처리 베스트 프랙티스
DOCX: 스타일과 레이아웃 보존
- 문단/표/캡션 등 스타일을 최대한 원본대로 유지하려면 문서 내부의 불필요한 수동 줄바꿈, 하드 스페이스, 깨진 리스트를 정리한 후 업로드합니다.
- 고유명사·제품명은 용어집(쌍방향 매핑)으로 고정하고, 제목/캡션/각주 등은 QA 체크 대상 목록에 포함합니다.
- 그림 안 텍스트는 번역 대상이 아니므로, 필요 시 사전 OCR 처리 후 병합하는 파이프라인을 둡니다.
PPTX: 개체 단위 제약 고려
- 텍스트 상자, 표, 도형별로 줄바꿈 규칙이 달라질 수 있습니다. 자동 줄바꿈이 흐트러지는 경우 슬라이드 마스터를 정리해 과도한 스타일 중첩을 줄이세요.
- 차트·스마트아트의 임베디드 텍스트는 포맷에 따라 번역되지 않을 수 있습니다. 사전 추출→번역→재삽입 스텝을 별도로 둡니다.
HTML: 태그 보호와 세그먼트 제어
- 텍스트 번역 엔드포인트에서는 tag_handling=html, ignore_tags 매개변수로 번역에서 제외할 태그(예: code, pre, script)를 지정해 마크업 파손을 방지합니다.
- split_sentences, preserve_formatting를 상황에 맞게 조정해 세그먼트 분할을 제어합니다. UI 조각은 세그먼트 고정을 우선 고려하세요.
- 속성 값(i18n-key 등)처럼 번역 금지 대상은 사전에 별도 필드로 분리하여 요청합니다.
PDF: 스캔 vs 디지털 PDF 구분
- 텍스트 레이어가 없는 스캔 PDF는 정확도가 크게 떨어질 수 있습니다. 신뢰 가능한 OCR로 텍스트를 추출해 DOCX/HTML로 변환 후 번역하는 경로를 권장합니다.
- 문서 보안(암호/편집 금지)은 해제 후 처리하고, 표/도식은 추출 정확도를 샘플링 검사로 확인합니다.
용어집 관리: 버전·언어쌍·검증
언어쌍별 운용 원칙
- DeepL 용어집은 언어쌍 단위로 동작합니다. 주요 언어쌍별로 별도 용어집을 만들고, 이름 규칙(예: glossary_product_ko-en_v3)을 통일하세요.
- 대소문자/복수형 변형 등은 용어집 본문과 스타일 가이드에서 함께 정의해 중복 규칙을 줄입니다.
버전관리와 롤백
- CSV 소스와 API 생성 스크립트를 저장소에서 버전관리하고, 스테이징 환경에서 샘플 문서 회귀 테스트를 통과한 버전만 프로덕션에 배포합니다.
- 배포 시 기존 glossary_id를 보관해 즉시 롤백할 수 있도록 매핑 테이블을 유지합니다.
QA 루프와 회귀 테스트
- 대표 문서 20~30개 내외의 고정 검증 세트를 두고, 릴리즈마다 용어 고정률, 불필요한 재번역 비율, 형식 오류 건수를 비교합니다.
- 지표는 과장하지 말고 추세만 모니터링해, 특정 릴리즈에서 급격한 변화를 빠르게 감지합니다.
에러 처리와 비용 통제
재시도·백오프·타임아웃
- 429(레이트 리밋), 5xx 응답에는 지수 백오프로 최대 재시도 횟수를 제한합니다. 문서 상태 폴링은 2~5초 간격으로 점진 백오프를 적용합니다.
- 업로드·다운로드 타임아웃과 최대 파일 크기를 사전에 정의해 큐 정체를 방지합니다.
문자 수·캐시·중복 방지
- DeepL 과금은 일반적으로 번역 문자 수 기준입니다. 요청 전에 대략의 문자 수를 추정(원본 텍스트 길이)해 예산 알림을 설정합니다.
- 동일 해시(원본+파라미터) 요청은 캐시를 우선 조회하고, 진행 중 작업은 작업 ID로 결합해 중복 업로드를 막습니다.
사전 검증과 폴백
- 대상 언어, 파일 확장자, 페이지 수 등 기본 검증을 통과하지 못하면 요청을 거부하고 사용자에게 수정 가이드를 제공합니다.
- 장애 시에는 중요 문서만 우선 처리하는 우선순위 큐와, 간단한 텍스트만 /translate로 임시 우회하는 폴백 경로를 둡니다.
보안·개인정보 고려사항
- API 키는 코드 저장소에 절대 저장하지 말고, 시크릿 매니저·환경 변수로 주입합니다.
- 민감 정보는 가명화/마스킹 후 전송하고, 원본·결과 파일의 보존 기간을 최소화합니다.
- 전송·저장 로그에서 본문을 남기지 말고, 식별자·통계 정보만 기록합니다.
최소 구현 예시(cURL)
엔드포인트·매개변수는 변경될 수 있으니, 최신 공식 문서를 함께 확인하세요.
# 1) 문서 업로드
curl -X POST "https://api.deepl.com/v2/document" \
-H "Authorization: DeepL-Auth-Key $DEEPL_KEY" \
-F "file=@report.docx" \
-F "target_lang=KO" \
-F "formality=prefer_less" \
-F "glossary_id=$GLOSSARY_ID"
# 응답 예시: {"document_id":"...","document_key":"..."}
# 2) 상태 조회
curl -G "https://api.deepl.com/v2/document/$DOC_ID" \
-H "Authorization: DeepL-Auth-Key $DEEPL_KEY" \
--data-urlencode "document_key=$DOC_KEY"
# 3) 결과 다운로드
curl -G "https://api.deepl.com/v2/document/$DOC_ID/result" \
-H "Authorization: DeepL-Auth-Key $DEEPL_KEY" \
--data-urlencode "document_key=$DOC_KEY" -o translated.docx운영 체크리스트
- 요청 정책: 레이트 리밋, 재시도, 멱등 키, 최대 동시 작업 수
- 포맷 규칙: DOCX/PPTX 템플릿 정리, HTML 태그 보호, PDF 사전 OCR
- 용어집: 언어쌍 분리, 버전 태깅, 스테이징 회귀 테스트, 롤백 플랜
- 비용: 문자 수 추정, 캐시 적중률 모니터링, 중복 요청 차단
- 품질: 샘플 세트 자동 비교, 형식(표/리스트/캡션) 무결성 점검
- 보안: 키 관리, 로그 가명화, 보존 기간, 접근 제어
- 관측성: 작업 대기/실패율 대시보드, 알림, 장애 대응 플레이북
마무리: 작게 시작해 빠르게 학습하기
문서 포맷은 제각각이고, 팀별 용어·스타일도 다릅니다. DeepL Pro API 도입 효과를 극대화하려면, 포맷별 처리 원칙과 용어집 관리를 표준화하고, 비동기 번역·캐시·재시도 정책으로 비용과 안정성을 동시에 잡아야 합니다. 작은 파일군부터 표준을 적용해 성공사례를 만들고, 회귀 테스트와 모니터링을 통해 범위를 점진적으로 확장하세요. 이렇게 구축한 워크플로우는 문서 번역 자동화를 일회성 작업이 아닌, 신뢰할 수 있는 제품 기능으로 바꿔줍니다.
