왜 DeepL Pro API로 문서 번역 파이프라인을 꾸려야 할까
국내외 팀과 협업하거나 제품·문서를 다국어로 배포하려면 번역의 정확도만큼 일관성과 형식 유지가 중요합니다. DeepL Pro API는 텍스트와 문서를 프로그래매틱하게 번역하고, 용어집으로 브랜드·전문용어를 고정하며, 가능한 범위에서 원본 서식을 유지해 워크플로에 자연스럽게 녹일 수 있게 합니다. 아래에서는 연동 준비부터 코드 예시, 문서 번역 운영 팁까지 한 번에 정리합니다.
연동 준비 사항
- API 인증키: 계정 콘솔에서 발급한 키를 안전하게 보관하고, 서버 측 환경변수로 주입합니다.
- 요청 지역/엔드포인트: 서비스 약관과 문서를 확인해 권장 엔드포인트를 사용합니다.
- 요청 제한·비용 관리: 요금제·요청 한도를 확인하고 배치·재시도 정책을 설계합니다.
- 보안: 키를 클라이언트에 노출하지 말고, 로그에 원문·개인정보가 남지 않도록 마스킹합니다.
기본: 텍스트 번역 요청
간단한 문구·UI 문자열은 텍스트 번역 엔드포인트로 처리합니다. 태그 포함 콘텐츠는 HTML 핸들링 옵션을 사용해 태그를 보호하세요.
cURL 예시
curl -X POST https://api.deepl.com/v2/translate \n -H "Authorization: DeepL-Auth-Key $DEEPL_API_KEY" \n -d "text=안녕하세요" \n -d "target_lang=EN" \n -d "formality=more" \n -d "tag_handling=html" \n -d "ignore_tags=code,pre"Node.js 예시
import fetch from 'node-fetch';\nconst params = new URLSearchParams({\n text: '가격은 <strong>변경될 수 있습니다</strong>.
',\n target_lang: 'JA',\n tag_handling: 'html',\n ignore_tags: 'strong'\n});\nconst res = await fetch('https://api.deepl.com/v2/translate', {\n method: 'POST',\n headers: { Authorization: `DeepL-Auth-Key ${process.env.DEEPL_API_KEY}` },\n body: params\n});\nconst data = await res.json();팁: UI 문자열은 키-값 JSON을 분해해 키 순서를 고정한 뒤 번역하고, 결과를 다시 조립하면 변경 추적이 쉬워집니다.
문서 번역 워크플로(비동기)
DOCX·PPTX·XLSX·HTML·TXT 등 문서는 문서 번역 API를 사용합니다. 업로드 → 상태 폴링 → 다운로드의 세 단계입니다.
1) 문서 업로드
# cURL\ncurl -X POST https://api.deepl.com/v2/document \n -H "Authorization: DeepL-Auth-Key $DEEPL_API_KEY" \n -F "file=@/path/to/file.docx" \n -F "target_lang=EN" \n -F "formality=prefer_more" \n -F "glossary_id=$GLOSSARY_ID"응답에는 document_id와 document_key가 포함됩니다. 둘 다 안전하게 저장하세요.
2) 상태 확인(폴링)
curl -G https://api.deepl.com/v2/document/$DOCUMENT_ID \n -H "Authorization: DeepL-Auth-Key $DEEPL_API_KEY" \n --data-urlencode "document_key=$DOCUMENT_KEY"상태는 translating → done 순으로 진행됩니다. 429·5xx 응답에는 지수 백오프와 최대 재시도 횟수를 적용합니다.
3) 번역 결과 다운로드
curl -X POST https://api.deepl.com/v2/document/$DOCUMENT_ID/result \n -H "Authorization: DeepL-Auth-Key $DEEPL_API_KEY" \n -d "document_key=$DOCUMENT_KEY" \n --output translated.docx팁: 파일명 규칙을 정해 원본과 짝을 쉽게 찾도록 하고, 처리 로그에 document_id를 기록해 재다운로드·감사를 지원하세요.
용어집(글로서리) 운영 전략
- 범위 설계: 제품명·브랜드 톤·도메인 핵심어부터 시작해 릴리즈마다 증분 업데이트합니다.
- 형식: API를 통해 항목을 추가하거나, 포맷에 맞는 파일을 준비해 일괄 등록합니다.
- 우선순위: 용어집 매핑이 일반 번역보다 우선 적용되므로 오기·대소문자 오류를 최소화하세요.
- 버전 관리: 용어집 이름에 날짜·프로젝트 태그를 포함하고, 구버전을 아카이브해 회귀 이슈에 대비합니다.
- 테스트: 샘플 문장을 정해 용어집 반영 전·후 출력 차이를 스냅샷으로 비교합니다.
형식 유지와 레이아웃 깨짐 최소화
- 문서 작성 규율: 수동 줄바꿈·스페이스로 정렬하지 말고 스타일·목록·표 기능을 사용합니다.
- 이미지 안 텍스트: 가능하면 캡션·대체텍스트로 분리해 번역 대상에 포함되도록 합니다.
- 표·머리글/바닥글: 주요 텍스트가 본문에 있도록 구조를 단순화하면 보존률이 높습니다.
- HTML 번역:
tag_handling=html과ignore_tags로 코드를 보호하고, 번역 전 미니파이 대신 의미 단위로 정리합니다. - 사전 검증: 샘플 1~2페이지를 먼저 번역해 깨짐 여부를 확인한 뒤 일괄 처리합니다.
품질·성능 최적화 체크리스트
품질
- 문장 분절: 너무 긴 문장은 가독성이 떨어집니다. 소제목·리스트로 구조화하세요.
- 컨텍스트 유지: 단락 단위로 처리하면 대명사·지시어 해석이 안정적입니다.
- 후처리 QA: 금칙어·브랜드 톤 규칙을 정해 자동 검사하고, 중요 문서는 휴먼 리뷰를 거칩니다.
성능/비용
- 배치 처리: 작은 텍스트는 묶어 요청 수를 줄이고, 대용량 문서는 병렬 업로드 수를 제한합니다.
- 캐시: 동일 원문 해시를 키로 번역 결과를 재사용하면 불필요한 호출을 줄일 수 있습니다.
- 지수 백오프: 429·503 응답 시 대기시간을 점진적으로 늘려 안정성을 확보합니다.
에러 처리와 운영 관제
- 에러 분류: 클라이언트(4xx)와 서버(5xx)를 구분해 재시도 여부를 결정합니다.
- 타임아웃: 업로드·다운로드 모두 네트워크 타임아웃을 설정하고, 중단 시 안전하게 재시도합니다.
- 추적성:
document_id·document_key·원본 파일 해시·버전 정보를 함께 로깅합니다. - 알림: 실패 건수·대기열 길이·평균 처리시간에 임계치를 두고 알림을 발송합니다.
보안·개인정보 보호
- 키 보호: 서버 사이드에서만 사용하고, 저장 시 암호화·권한 분리를 적용합니다.
- 데이터 최소화: 불필요한 개인·민감정보는 전송 전에 마스킹하거나 제거합니다.
- 로그 정책: 원문 전체를 남기지 말고 식별자 중심으로 기록합니다.
- 내부 규정: 벤더의 데이터 처리 정책·계약을 검토하고 사내 보안 기준을 준수합니다.
샘플 파이프라인 설계
- 수집: 업로더/CI가 파일을 스토리지에 저장하며 작업 큐에 메시지를 적재
- 처리: 워커가 문서 업로드 → 상태 폴링 → 결과 저장
- 후처리: 용어집 규칙 검증, 표지/요약 자동 생성, 리뷰 태스크 발행
- 배포: 언어별 폴더/브랜치로 내보내며, CMS에 메타데이터(원본-번역 매핑) 등록
바로 적용할 실전 팁 7가지
- 파일명 규칙: product_v1.2_ko.docx → product_v1.2_en.docx
- 샘플 먼저: 대표 페이지 2~3장으로 형식 깨짐·용어집 반영률 검증
- 긴급·일반 큐 분리: 서비스 공지 등은 우선 처리
- 리뷰 스냅샷: 전/후 비교 PDF를 자동 생성해 승인 속도 향상
- HTML 보호: 코드 블록·변수 플레이스홀더는
ignore_tags로 제외 - 버전 태깅: 번역 결과에 소스 커밋/릴리즈 태그 저장
- 회귀 테스트: 자주 번역되는 섹션으로 정기 품질 점검
위 원칙만 지켜도 DeepL Pro API 기반 문서 번역은 안정적이고 예측 가능한 파이프라인으로 운영할 수 있습니다. 작은 범위에서 시작해 용어집·검수 규칙을 다듬고, 문서 형식 규율을 조직에 확산시키는 것이 핵심입니다.
