딥엘(DeepL) Pro API, 이렇게 쓰면 실무가 편해집니다
팀 문서가 빠르게 늘어나고, 제품·브랜딩 용어는 일관되게 유지해야 하며, 마크다운·HTML·워드 파일의 서식도 그대로 살리고 싶다면 DeepL Pro API가 답이 됩니다. 이 글은 DeepL Pro API를 바로 업무에 적용할 수 있도록 연동 절차, 문서 번역 자동화, 용어집(Glossary) 운영, 형식 보존 설정, 오류/요금 관리까지 실무 중심으로 정리했습니다.
- 핵심 포인트: 간단한 텍스트 번역은 /translate, 대용량 파일은 /document, 용어 일관성은 /glossaries를 조합합니다.
- 서식 보존: tag_handling, preserve_formatting, ignore_tags 등 옵션을 정확히 써야 형식이 깨지지 않습니다.
- 운영: 사용량(/usage) 조회, 재시도/폴링 전략, 키 보안과 로그로 운영 비용과 장애를 줄입니다.
연동 전 체크리스트
플랜·엔드포인트 구분
- Pro: https://api.deepl.com/v2/
- Free: https://api-free.deepl.com/v2/
환경변수에 키를 보관하고, 코드에는 하드코딩하지 않습니다. 권장 인증은 헤더 Authorization: DeepL-Auth-Key {YOUR_KEY}입니다(대체로 auth_key 파라미터도 지원).
언어 코드와 지원 기능
타깃 언어는 EN-GB, EN-US, DE, FR, JA, KO 등 코드로 지정합니다. formality, 용어집 등은 언어 쌍에 따라 동작 범위가 다를 수 있어 적용 전 공식 문서에서 지원 여부를 확인하세요.
보안·운영
- 키 보안: .env, 시크릿 매니저 사용. 저장·전송 중 평문 노출 금지.
- 시간 제한·재시도: 429/5xx 대비 지수 백오프 적용.
- 로깅: 요청 파라미터 중 민감 정보 마스킹, 오류 코드·응답 시간 수집.
텍스트 번역 API 빠른 시작
간단한 문장은 /translate로 처리합니다. 여러 문장은 text를 배열처럼 반복 전달하면 됩니다.
cURL 예제
curl https://api.deepl.com/v2/translate \n -H "Authorization: DeepL-Auth-Key $DEEPL_KEY" \n -d "text=안녕하세요" \n -d "target_lang=EN-US" \n -d "preserve_formatting=1"Python 예제
import os, requests\nurl = "https://api.deepl.com/v2/translate"\nheaders = {"Authorization": f"DeepL-Auth-Key {os.getenv('DEEPL_KEY')}"}\ndata = {\n "text": ["<strong>중요:</strong> 릴리즈 노트를 확인하세요."],\n "target_lang": "EN-US",\n "tag_handling": "html",\n "ignore_tags": "strong",\n "preserve_formatting": 1\n}\nr = requests.post(url, data=data, headers=headers, timeout=30)\nr.raise_for_status()\nprint(r.json()["translations"][0]["text"])실무 팁
- HTML 번역: tag_handling=html로 태그 인식, 코드·변수는 ignore_tags=code,pre 등으로 보호.
- 문장 분할: split_sentences=0/1/nonewlines 조정(소제목·UI 문자열은 0이 유리할 때가 있음).
- 격식: formality=more/less(지원 언어에서만 동작).
- 용어집 적용: glossary_id 파라미터로 일관성 유지.
문서 번역 자동화: 업로드→상태 폴링→다운로드
대용량 파일은 /document를 사용합니다. 워드(docx), 파워포인트(pptx), PDF, HTML, TXT 등 주요 형식을 지원합니다.
1) 업로드
curl -X POST "https://api.deepl.com/v2/document" \n -H "Authorization: DeepL-Auth-Key $DEEPL_KEY" \n -F "file=@proposal_ko.docx" \n -F "target_lang=EN-GB" \n -F "glossary_id=$GLOSSARY_ID" \n -F "preserve_formatting=1"응답에서 document_id, document_key를 받습니다.
2) 상태 확인(폴링)
curl -G "https://api.deepl.com/v2/document/$DOC_ID" \n -H "Authorization: DeepL-Auth-Key $DEEPL_KEY" \n --data-urlencode "document_key=$DOC_KEY"status가 done이면 다운로드 가능합니다. 대기 시간은 3~10초 간격으로 점진적 백오프를 권장합니다.
3) 결과 다운로드
curl -L "https://api.deepl.com/v2/document/$DOC_ID/result" \n -H "Authorization: DeepL-Auth-Key $DEEPL_KEY" \n --data-urlencode "document_key=$DOC_KEY" \n -o proposal_en.docx실무 팁
- 여러 파일 병렬 처리: 업로드 큐와 상태 폴링 워커를 분리해 처리량을 안정화합니다.
- PDF는 서식 품질이 원문 구조·OCR 품질에 크게 좌우됩니다. 가능하면 원본 편집 파일(docx/pptx/html)로 번역하세요.
- 결과 검수: 표·도형·각주 등은 샘플로 품질 점검 후 대량 처리에 들어갑니다.
용어집(Glossary)로 브랜드·제품명 일관성 유지
생성
curl https://api.deepl.com/v2/glossaries \n -H "Authorization: DeepL-Auth-Key $DEEPL_KEY" \n -d "name=ko-en-product" \n -d "source_lang=KO" \n -d "target_lang=EN-US" \n -d "entries_format=tsv" \n --data-urlencode "entries=제품\tproduct\n고객\tcustomer"반환되는 glossary_id를 /translate 또는 /document 업로드 시 glossary_id로 지정하면 됩니다. 언어 쌍별 지원 범위가 다를 수 있으니, 운영 전 해당 쌍의 용어집 지원 여부를 먼저 확인하세요.
운영 팁
- 버전 관리: 용어집을 Git/스프레드시트로 관리하고 변경 이력을 남깁니다.
- 테스트: 신규 항목 추가 시 샘플 문장으로 오번역 여부를 빠르게 체크합니다.
- 범주화: 제품/법무/마케팅 등 용도별 용어집을 분리해 충돌을 최소화합니다.
형식 보존과 HTML 번역, 이렇게 설정하세요
- preserve_formatting=1: 줄바꿈·강조 등 레이아웃 보존.
- tag_handling=html: HTML 인식. 코드·데이터는 ignore_tags=code,pre,script 등으로 보호.
- tag_handling=xml: 세밀 제어가 필요하면 xml로 전환해 non_splitting_tags, ignore_tags를 병행.
- 숫자·변수 보호: {VAR}, %s, {{handlebars}} 등 플레이스홀더는 ignore_tags나 고정 패턴으로 감싸 번역 제외.
HTML 예제
curl https://api.deepl.com/v2/translate \n -H "Authorization: DeepL-Auth-Key $DEEPL_KEY" \n -d "text=<h3>릴리즈 2.0</h3><p>코드: <code>init_app()</code></p>" \n -d "target_lang=EN-US" \n -d "tag_handling=html" \n -d "ignore_tags=code" \n -d "preserve_formatting=1"난이도 높은 케이스별 팁
- PDF 스캔본: OCR 품질 이슈가 있을 수 있습니다. 원본 문서로 재번역하거나, OCR 전처리 후 적용을 권장합니다.
- 코드·콘솔 로그: <pre>·<code>로 감싸고 ignore_tags로 제외.
- UI 문자열: split_sentences=0, formality 고정, 용어집을 함께 사용해 일관성 강화.
- 마크다운: HTML로 임시 변환 후 번역, 다시 마크다운으로 되돌리는 파이프라인을 고려합니다.
오류 처리와 요금·사용량 관리
대표 상태 코드
- 400 잘못된 파라미터: 언어 코드·옵션 재확인.
- 403 인증 실패: 키·엔드포인트 확인.
- 404 문서 미존재: document_id/document_key 확인.
- 429 과도한 요청: 재시도 백오프, 동시성 제한.
- 456 한도 초과: 요금제 한도 도달. 작업 중단·알림 발송.
- 5xx 서버 오류: 지수 백오프 재시도.
사용량 조회(/usage)
curl https://api.deepl.com/v2/usage \n -H "Authorization: DeepL-Auth-Key $DEEPL_KEY"스케줄러로 사용량 임계치 도달 시 알림을 보내면 예산 초과를 예방할 수 있습니다. 문서 번역 자동화에서는 업로드 전 남은 한도를 확인하고, 초과 예상 시 큐에 보류 상태로 전환하세요.
배포 체크리스트
- 환경변수: DeepL 키, 엔드포인트, 타임아웃, 재시도 횟수.
- 관찰성: 요청 수·지연·오류율·번역 길이 로깅.
- 품질 보증: 샘플 세트 회귀 테스트(용어집 반영 여부, HTML 태그 보존).
- 폴백: 번역 실패 시 재시도 후 수동 검수 대기열로 이동.
예시 워크플로: 콘텐츠 팀 문서 번역 자동화
- 업로더: 사내 스토리지/WordPress 미디어에 원문 업로드 → 큐에 작업 생성.
- 변환기: 마크다운/HTML 정리, 코드·변수 태그 보호.
- 번역기: /document 또는 /translate 호출(용어집·형식 보존 옵션 포함).
- 폴링: 상태 완료 시 결과 다운로드 → 원문 메타데이터 유지한 채 저장.
- 검수: 표본 문서 자동 비교(diff) + 에디터 크리티컬 용어 스팟체크.
이 흐름에 사용량 모니터링과 알림을 추가하면, 문서 번역 자동화가 안정적으로 돌아갑니다.
마무리
DeepL Pro API의 강점은 정확도뿐 아니라 실무에 맞춘 자동화 친화성입니다. 텍스트와 문서를 역할에 따라 분리하고, 용어집으로 브랜드 언어를 고정하며, 형식 보존 옵션을 정확히 조합하면 번역 품질과 작업 속도를 모두 잡을 수 있습니다. 위 설정을 템플릿화해 팀 표준으로 굳히면, 신규 프로젝트에도 빠르게 재사용할 수 있습니다.
