이 글에서 얻을 수 있는 것
DeepL Pro API로 워드프레스와 내부 업무 도구를 연결해 문서 번역을 자동화하는 실전 흐름을 정리합니다. 비동기 문서 번역 플로우, 용어집(Glossary) 운영, 형식 보존 팁, 에러/비용 관리 체크리스트까지 한 번에 점검하세요.
전체 흐름 한눈에 보기
- 인증: DeepL Pro API 키 발급 후 서버 사이드에서만 사용
- 방식 선택: 텍스트 번역(동기) vs 문서 번역(비동기)
- 용어집 설계: 브랜드·제품명 고정, 번역 금지어 지정
- 형식 보존: 문서 포맷 선택(DOCX 권장), HTML/XML 태그 보호
- 운영: 큐 기반 처리, 재시도, 사용량 모니터링
빠른 시작: 엔드포인트 핵심
1) 텍스트 번역(동기)
간단 문단, HTML 조각 등에 적합합니다. 주요 파라미터는 target_lang, source_lang(선택), glossary_id(선택), formality(가능 언어 한정), tag_handling(HTML/XML)입니다.
POST https://api.deepl.com/v2/translate
Authorization: DeepL-Auth-Key <API_KEY>
text=Hello&target_lang=KO&glossary_id=<YOUR_GLOSSARY_ID>&tag_handling=html포맷을 최대한 유지하려면 줄바꿈·리스트 등 마크업을 함께 전달하고, HTML/XML은 tag_handling로 보호하세요.
2) 문서 번역(비동기)
대용량 문서와 형식 보존이 필요한 경우 권장합니다. 업로드→상태 조회→결과 다운로드의 3단계를 따릅니다.
# 업로드
POST https://api.deepl.com/v2/document
(form-data) file=@/path/file.docx
target_lang=KO
source_lang=EN # 선택
glossary_id=<ID> # 선택
# 상태 조회
POST https://api.deepl.com/v2/document/{document_id}
(form-data) document_key=<document_key>
# 결과 다운로드
POST https://api.deepl.com/v2/document/{document_id}/result
(form-data) document_key=<document_key>응답의 document_id와 document_key를 안전하게 저장해 폴링하거나 큐에서 후속 작업을 트리거하세요.
용어집(Glossary) 제대로 쓰기
설계 원칙
- 범위 분리: 언어쌍·도메인별로 용어집을 분리해 충돌 방지
- 기본 단위: TSV로 정리(원문 탭 번역문), 대소문자·복수형 변형을 명시
- 버전 관리: 변경 이력과 검토자 기록을 남겨 회귀 이슈 방지
생성·적용 팁
# 생성 예시
POST /v2/glossaries
name=marketing-en-ko
source_lang=EN
target_lang=KO
entries=BrandX 브랜드엑스\nDo not translate 변역하지 않음- 문서 번역 시 glossary_id를 함께 전달하면 적용됩니다.
- 한 번에 여러 용어집을 적용할 수 없으므로, 필요 항목을 병합한 운영용 용어집을 별도로 두는 전략이 유용합니다.
형식 보존과 콘텐츠 보호
문서 포맷 선택
- DOCX/PPTX/XLSX: 구조 보존에 유리. 복잡한 표·도형은 사전 정리 권장
- PDF: 레이아웃 복원 한계가 있을 수 있어, 가능하면 원본 편집 포맷(DOCX 등)으로 변환 후 처리
- 이미지 내 텍스트는 번역 대상이 아닙니다. OCR가 필요하면 사전 처리하세요.
HTML/XML 태그 핸들링
- tag_handling=html 또는 xml로 지정해 태그 구조를 보호
- 변수·코드 조각은 플레이스홀더로 감싸 번역 제외(예: <span class=”notranslate”>{PRICE}</span>)
- 줄바꿈·리스트·표 마크업은 최대한 구조적으로 유지해 품질 개선
워드프레스 연동 가이드
자동화 시나리오
- 게시물 발행 시: 본문(HTML)과 첨부 문서를 큐에 넣고 비동기 번역 후 다국어 포스트 생성
- 미디어 라이브러리: DOCX/PPTX 업로드 시 자동 번역본을 같은 폴더/미디어 메타로 저장
- 정기 배치: WP-Cron 또는 외부 스케줄러로 미번역 항목 처리·상태 동기화
구현 체크리스트
- 서버 사이드에서만 API 호출: API 키는 환경 변수·Secrets에 저장
- 큐/상태 관리: document_id/document_key를 포스트 메타로 저장, 상태 폴링 후 완료 시 첨부 등록
- 용어집 선택 로직: 카테고리·태그·언어쌍에 따라 glossary_id 매핑
- 실패 복구: 429/5xx 시 지수 백오프 재시도, 영구 실패는 관리자 알림
- 사용량 대시보드: 일일 번역 문자 수와 오류율을 관리자 화면에 집계
품질을 끌어올리는 사전 정리
- 문서 정돈: 잘못된 줄바꿈, 불필요한 중복 공백, 깨진 목록·표를 먼저 정리
- 일관된 스타일: 제목·본문·캡션을 스타일로 구분해 엔진이 문맥을 파악하기 쉽게
- 고유명사 보호: 브랜드명·코드·변수를 태그/플레이스홀더로 표시
- 리뷰 프로세스: 우선순위 높은 섹션만 인하우스 리뷰해 리드타임 단축
비용·성능 최적화
- 번역 범위 축소: 부록·로그·코드 블록 등 불필요 영역은 제외
- 문서 분할: 매우 큰 문서는 장/절 단위로 분할해 실패 범위를 좁히고 재시도 비용 절약
- 대기·동시성 제어: 워커 수를 조정해 429(요청 과다)를 피하고 평균 지연 최소화
- 사용량 모니터링: /v2/usage로 일/월 단위 사용량을 집계해 예산 초과를 예방
자주 만나는 오류와 대응
대표 상태 코드
- 400: 파라미터 오류(언어 코드·glossary_id·파일 포맷 확인)
- 413: 파일이 너무 큼(분할·용량 제한 확인)
- 429: 요청 과다(큐·백오프 적용)
- 456: 쿼터 초과(요금제·사용량 점검, 스로틀링 강화)
- 5xx: 일시 장애(지수 백오프 후 재시도, 최대 횟수 제한)
안전한 재시도
- 문서 업로드는 중복을 피하기 위해 파일 해시로 중복 제출을 차단
- 상태 조회/다운로드는 동일 document_id/document_key로 멱등 처리
- 재시도 로그에 원인·회수·최종 상태를 남겨 원인 분석
언어 옵션 활용 팁
- formality: 지원 언어에서만 적용되므로, 미지원 언어는 기본값 처리
- split_sentences: 제목·슬로건은 nonewlines가 어울리는 경우가 있음
- preserve_formatting(텍스트 번역): 원문 개행·강조를 최대한 유지하고 싶을 때 고려
보안과 컴플라이언스
- API 키는 클라이언트에 노출 금지, 서버 프록시를 통해 호출
- 로그 마스킹: 개인·기밀 데이터는 저장/전송 전 마스킹
- 데이터 수명: 임시 파일·큐 메시지의 보존 기간을 짧게 유지
운영 체크리스트(요약)
- 용어집: 언어쌍/도메인별 분리, 변경 이력 관리
- 큐·재시도: 429/5xx 백오프, 영구 실패 알림
- 형식 보존: 가능하면 DOCX, HTML/XML은 태그 보호
- 사용량: /v2/usage 집계, 예산 경보
- 워드프레스: 발행 훅→큐→상태 폴링→다국어 포스트/첨부 등록
마무리
DeepL Pro API는 비동기 문서 번역, 용어집 적용, 형식 보존을 한 번에 다루며, 워드프레스와 결합하면 콘텐츠 현지화 자동화의 기반이 됩니다. 위 체크리스트대로 설계·운영하면 품질과 비용 사이의 균형을 잡으면서도, 팀의 번역 리드타임을 안정적으로 단축할 수 있습니다.
