DeepL Pro API 연동 완전 가이드: 문서 번역 자동화, 용어집, 형식 보존 실전 팁

개요: DeepL Pro API로 문서 번역 자동화하기

DeepL Pro API는 대량 텍스트와 문서를 안정적으로 번역하고, 워크플로우에 자연스럽게 통합할 수 있는 상용 API입니다. 본 글은 초기 세팅부터 텍스트·문서 번역 API 사용법, 형식 보존과 용어집(Glossary) 적용, 비용·품질 관리, WordPress 연동 아이디어까지 실무 중심으로 정리했습니다.

사전 준비와 보안 체크리스트

엔드포인트: Pro는 https://api.deepl.com/v2/, Free는 https://api-free.deepl.com/v2/
인증: HTTP 헤더 Authorization: DeepL-Auth-Key <API_KEY>
보안: API 키는 서버 환경변수로 관리하고, 로그에 노출되지 않도록 마스킹합니다. 프런트엔드 직접 호출은 피하고, 서버에서 프록시 처리합니다.
데이터 보호: 개인정보·기밀이 포함될 수 있는 원문은 전송 전에 최소화·가명처리하고 보관 기간·암호화를 명확히 합니다.

텍스트 번역: 기본 호출과 핵심 파라미터

필수·자주 쓰는 파라미터

text: 번역할 문자열(배열 지원)
target_lang / source_lang: 예) KO, EN, JA 등
preserve_formatting: 줄바꿈·기본 서식 유지(0/1)
formality: 어투 조절(언어별 지원, 예: more/less)
tag_handling: html 또는 xml로 태그 인식
ignore_tags, non_splitting_tags: 번역 제외·문장 분할 제어
glossary_id: 용어집 적용

cURL 예시

curl -X POST 'https://api.deepl.com/v2/translate' \ 
  -H 'Authorization: DeepL-Auth-Key YOUR_API_KEY' \ 
  -d 'text=<p>안녕하세요</p>' \ 
  -d 'target_lang=EN' \ 
  -d 'tag_handling=html' \ 
  -d 'preserve_formatting=1' \ 
  -d 'formality=more'

Python 예시

import os, requests
API_KEY = os.getenv('DEEPL_KEY')
url = 'https://api.deepl.com/v2/translate'
headers = {'Authorization': f'DeepL-Auth-Key {API_KEY}'}
payload = {
  'text': ['첫 줄<br/>둘째 줄', '제품: UltraView 3000'],
  'target_lang': 'JA',
  'tag_handling': 'html',
  'split_sentences': '1',
  'preserve_formatting': '1'
}
r = requests.post(url, headers=headers, data=payload, timeout=30)
r.raise_for_status()
print(r.json())

팁: HTML을 번역할 때 코드 조각이나 UI 키는 <code>, <pre> 등으로 감싸고 ignore_tags=code,pre로 제외하면 안전합니다.

문서 번역 API: 업로드-상태-다운로드 3단계

1) 업로드

curl -X POST 'https://api.deepl.com/v2/document' \
  -H 'Authorization: DeepL-Auth-Key YOUR_API_KEY' \
  -F 'file=@report.docx' \
  -F 'target_lang=EN' \
  -F 'formality=more'

응답에는 document_id와 document_key가 포함됩니다. 이 두 값은 이후 상태 조회·결과 다운로드에 필수이므로 안전하게 저장하세요.

2) 상태 조회

curl -G 'https://api.deepl.com/v2/document/{document_id}' \
  -H 'Authorization: DeepL-Auth-Key YOUR_API_KEY' \
  --data-urlencode 'document_key=YOUR_DOCUMENT_KEY'

상태는 대기, 처리 중, 완료, 오류 등으로 반환됩니다. 폴링 간격은 점진적으로 늘리는 백오프를 권장합니다.

3) 결과 다운로드

curl -G 'https://api.deepl.com/v2/document/{document_id}/result' \
  -H 'Authorization: DeepL-Auth-Key YOUR_API_KEY' \
  --data-urlencode 'document_key=YOUR_DOCUMENT_KEY' \
  --output report_en.docx

실무 팁

파일명 규칙: 원본명.언어코드.확장자로 일관성 유지
대용량 처리: 문서를 작은 단위로 나누고 큐(예: SQS, Redis)로 병렬 처리
재시도 정책: 타임아웃·일시 오류는 지수 백오프, 영구 오류는 운영자 알림
형식 보존: 지원 포맷은 서식을 최대한 유지합니다. 이미지 내 텍스트는 별도 OCR 파이프라인이 필요할 수 있습니다.

형식 보존과 태그 핸들링 전략

HTML/XML: tag_handling=html|xml, ignore_tags로 코드·숫자·고유키 제외
레이아웃 민감 문서: 표 제목·캡션·각주 등 구조적 요소를 규칙화하면 파손을 줄일 수 있습니다.
플레이스홀더: {name}, %%DATE%% 등은 고정 토큰으로 두고 번역 제외

용어집(Glossary)로 브랜드·도메인 용어 고정

용어집은 특정 용어를 원하는 번역으로 고정해 일관성을 높입니다. 언어쌍 지원 범위는 제한될 수 있으므로 사전에 확인하세요.

용어집 생성

curl -X POST 'https://api.deepl.com/v2/glossaries' \
  -H 'Authorization: DeepL-Auth-Key YOUR_API_KEY' \
  -d 'name=BrandTerms_KO_EN' \
  -d 'source_lang=KO' \
  -d 'target_lang=EN' \
  -d 'entries=제품\tProduct\n고객센터\tSupport' \
  -d 'entries_format=tsv'

용어집 적용

텍스트 번역: glossary_id=... 파라미터 추가
문서 번역: 업로드 단계에 glossary_id 포함

운영 팁

버전 관리: 변경 이력·검수자·적용 범위를 메타데이터로 기록
충돌 해소: 우선순위 규칙 수립(예: 제품군 > 일반 용어)
주기적 리뷰: 고빈도 오류·신규 제품명 반영

비용·한도 관리: 낭비 줄이는 6가지

사용량 모니터링: GET /usage로 문자 수·문서 처리량 확인, 임계치 알림
중복 방지: 해시 기반 캐시(문장 단위)로 재번역 최소화
배치 윈도우: 트래픽 집중 시간 회피, 큐·스케줄러로 평준화
사전 정제: 불필요한 공백·스크립트·광고 블록 제거
문장 단위 분할: 과도한 길이의 텍스트는 안정성·비용 측면에서 분할 처리
샘플 검사: 대량 투입 전 대표 샘플로 품질·서식 유효성 점검

번역 품질 관리: 사람이 개입하는 최소 루프

가이드라인: 톤·용어·형식(제목 대소문, 숫자·단위 표기) 명문화
샘플링 리뷰: 고빈도 페이지·신규 포맷·신규 언어 우선 검수
회귀 체크: 용어집 변경·엔진 업데이트 시 전·후 비교
피드백 루프: 리뷰 결과를 용어집·전처리 규칙으로 환류

WordPress 연동 설계 예시

흐름: 편집기 저장 → 백엔드 큐 등록 → DeepL 번역 → 결과 저장 → 번역본 게시
실행: WP-CLI/크론으로 배치 처리, 번역본은 새 포스트로 생성하고 _original_post_id 메타로 연결
미디어: 문서 번역 결과 파일은 미디어 라이브러리에 첨부, 파일명 규칙 유지
다국어 플러그인: Polylang/WPML 등과 호환되도록 언어 코드·포스트 관계를 맞춥니다.
보안: REST 엔드포인트는 인증·권한·레이트리밋 적용, API 키는 서버 측에만 보관

운영 안정성: 예외 처리와 로그

타임아웃·재시도: 네트워크 예외는 지수 백오프, 최대 재시도 횟수 제한
에러 분류: 클라이언트(요청 파라미터) vs 서버(일시 오류)로 구분해 대응
추적성: document_id, 소스 경로, 배치 ID를 구조화 로그로 남겨 재처리 용이
알림: 실패 임계치·대기열 초과 시 슬랙·메일로 즉시 통보

마무리

DeepL Pro API는 텍스트·문서 번역 자동화에 필요한 구성 요소를 고르게 제공합니다. 전처리(형식·태그), 용어집, 사용량 관리, 검수 루프를 체계화하면 고품질·일관 번역을 운영 환경에 안정적으로 안착시킬 수 있습니다.

Meta Description

DeepL Pro API 연동부터 문서 번역 자동화까지. 인증·형식 보존·용어집 적용·사용량 관리·오류 대응과 WordPress 연동 팁, cURL·Python 예제로 빠르게 시작하세요.