팀 단위로 문서 번역을 굴리는 순간, 품질·속도·비용은 서로 얽힌 하나의 문제로 바뀝니다. 이 글은 DeepL Pro API를 기반으로 문서 번역 자동화를 구축·운영할 때 꼭 알아야 할 설정과 실전 코드 패턴을 모아, 품질과 비용을 동시에 끌어올리는 방법을 정리했습니다. 과장 없는 체크리스트와 워크플로 제안만 담았습니다.
왜 DeepL Pro API로 문서 번역을 자동화할까
- 대량 문서의 일관성: 용어집(Glossary)로 브랜드·제품 용어를 강제해 번역 편차를 줄입니다.
- 형식 보존: DOCX·PPTX·XLSX·HTML 등 문서 레이아웃을 가급적 유지해 후처리 시간을 절약합니다.
- 운영 효율: 큐·워크커 구조로 야간 배치/온디맨드 처리를 분리하고, 실패 작업만 재시도합니다.
아키텍처 한눈에 보기: 큐·워크커·스토리지
- 인입 계층: 업로더(웹/CLI)가 원문 문서를 스토리지에 저장하고 작업 메타데이터를 큐에 투입
- 워크커: 큐를 소비하며 DeepL Pro API에 업로드→상태 조회→다운로드까지 자동화
- 스토리지: 원문/번역본 버전 관리, 해시 기반 캐시(동일 문서 재번역 방지)
- 관측: 로그·메트릭(성공률, 평균 지연, 문자 수, 비용 추정), 알림
필수 설정 체크리스트
1) 언어·문체
- target_lang: 팀 표준을 명확히(예: 한국어는 KO). 소스어가 혼재되면 source_lang을 고정하지 말고 자동 감지에 맡기는 편이 안전합니다.
- formality: 대상 언어·콘텐츠 톤을 맞추는 핵심. 제품 공지/문서화는 formal, 마케팅·블로그는 default 또는 more/less formal을 테스트합니다.
- preserve_formatting: 줄바꿈·간격 보존이 중요한 원문(예: 코드 주석, 표 캡션)에서 켭니다.
2) 태그·형식 보존
- HTML 원문이면 tag_handling=html(텍스트 번역 엔드포인트 기준)을 사용하고,
translate="no"속성이나<code>·<pre>·제품명 래퍼에 대해 ignore_tags로 보호합니다. - DOCX/PPTX/XLSX 등은 문서 번역 엔드포인트를 사용하면 서식을 최대한 유지합니다. 번역 불가 구간은 스타일/북마크로 표시해 사전 보호하는 게 좋습니다.
3) 용어집(Glossary)
- 브랜드·기능명·UI 문구를 기준으로 우선순위 용어 100~300개부터 시작해, 리뷰 피드백을 주 단위로 반영합니다.
- 용어집은 언어쌍별로 운영합니다(예: EN→KO, JA→KO). 다국어를 한 파일에 섞지 마세요.
- 누가·언제·왜 바꿨는지 변경 이력을 남기고, 배포 전 스테이징 워크커에 먼저 적용해 회귀를 막습니다.
문서 번역 엔드포인트: 업로드→상태→다운로드
- 업로드: 문서 파일과 target_lang, 선택적으로 source_lang/formality/glossary_id를 전송합니다.
- 상태 조회: 반환된 document_id·document_key로 폴링합니다. 실패 시 메시지를 로깅하고 재시도 규칙을 적용합니다.
- 다운로드: 변환 완료 시 번역본을 저장소에 버전으로 보관하고, 원문 해시와 매핑합니다.
팁: 대형 문서는 페이지/슬라이드 단위로 나눌 수 있으면 가급적 분할 업로드 후 병합하세요. 실패 구간만 재번역할 수 있어 총 소요 시간이 줄어듭니다.
품질을 끌어올리는 코드 패턴 12가지
- 사전 정리: 잘못된 인코딩, 이중 공백, 깨진 HTML을 정규화하고 올바른 문단 경계를 잡습니다.
- 불번역 보호: 제품명·버전·코드·변수는
<span translate="no">또는 별도 태그로 감싸고 ignore_tags로 제외합니다. - 문장 분할 제어: 목록/표 캡션은 문장 분할을 최소화하면 맥락이 보존됩니다.
- 컨텍스트 힌트: 섹션 헤더(예: “보안 주의”)를 유지하면 전문 용어 선택이 안정화됩니다.
- UI 문자열: “Save”, “Cancel”처럼 짧은 문자열은 용어집 우선. 문맥 없는 단일 단어는 과번역 위험이 큽니다.
- 숫자·단위: 통화·치수는 지역화 규칙에 맞게 후처리(쉼표/마침표, 공백, 단위 순서)를 적용합니다.
- 하이퍼링크: 앵커 텍스트만 번역하고 URL 파라미터는 보호합니다.
- 이미지 대체텍스트: alt 텍스트를 별도로 추출해 번역하고, 접근성 검수 리스트에 포함합니다.
- 표/코드 블록: 표 헤더는 신중히 번역, 코드 블록은 전면 보호. 주석은 번역하되 코드 조각은 보존합니다.
- 후검수 루프: 리뷰어가 발견한 용어·문체 이슈를 용어집과 스타일 가이드에 즉시 반영, 다음 배치부터 자동 수렴.
- 부분 업데이트: 원문 변경 해시를 비교해 변경된 구간만 재번역(diff 기반)하여 비용과 시간 절감.
- A/B 번역: 중요 페이지는 formality/용어집 버전을 바꿔 두 번 번역 후, 리뷰어가 더 나은 쪽을 채택합니다.
비용·속도 최적화 전략
- 캐싱: 원문 해시(key)→번역본 값을 저장해 동일 문서/문단 재번역을 방지합니다.
- 배치 크기: 소형 문서는 묶고, 대형 문서는 분할합니다. 실패 복구·큐 대기시간을 함께 고려합니다.
- 불필요 텍스트 제외: 법적 고지·공통 푸터처럼 반복 블록은 한 번만 번역해 삽입합니다.
- 사전 품질 확보: 용어집 정합성이 오르면 사람 검수 시간이 확 줄고, 재번역 비용도 함께 줄어듭니다.
에러·장애 대응: 안전한 리트라이
- 429(요청 과다): 지수 백오프와 지터를 적용하고, 동시성 상한을 동적으로 낮춥니다.
- 413(페이로드 큼): 문서 분할 업로드로 전환합니다.
- 4xx(매개변수 오류): 필수 값 누락·잘못된 언어 코드·유효하지 않은 glossary_id를 검증 단계에서 차단합니다.
- 456(쿼터 초과): 알림 후 대기·자동 중지. 월별/일별 상한을 모니터링하고, 프로젝트별 예산을 분리합니다.
- 재시도 정책: 업로드/다운로드는 멱등성을 고려해 동일 document_id 기반으로만 재시도합니다.
보안과 개인정보
- 민감정보 최소화: PII는 마스킹 후 전송하고, 내부 ID·토큰·서명값은 불번역 구간으로 보호합니다.
- 전송 보안: API 키는 서버 측에서만 보관·사용하고, 요청은 HTTPS로만 수행합니다.
- 데이터 보존: DeepL Pro는 제출 텍스트를 학습에 사용하지 않는다고 밝힙니다. 세부 보존 정책은 약관·DPA를 확인하고 내부 규정과 정합성을 맞추세요.
워드프레스 통합 팁
- 편집 워크플로: 게시글 저장 시 원문 스냅샷→큐 투입→번역본 수신 후 초안으로 생성→에디터 검수→공개 순서를 자동화합니다.
- 다국어 플러그인: 언어별 슬러그·메타를 분리 저장하고, 번역본 퍼머링크 충돌을 피하세요.
- HTML 보호: 코드 샘플·단축코드(shortcode)·내장 위젯은
translate="no"로 감싸거나 전처리 단계에서 플레이스홀더로 교체 후 복원합니다. - 크론/웹훅: 대량 작업은 야간 크론으로, 긴급 문서는 수동 트리거로 처리해 에디터 체감을 개선합니다.
빠른 시작 가이드
- 용어집 초안 100개 작성(EN↔KO), 리뷰 기준 합의
- 파일 업로드→상태 폴링→다운로드 워크커 1대 시범 운영
- HTML 보호 규칙(translate=”no”, ignore_tags) 적용
- 캐시·재시도·알림 붙이기(429/456 대비)
- 2주 단위로 용어집·formality 튜닝, 검수 시간·반려율 지표 추적
마무리: 품질·비용·속도를 잇는 가장 짧은 루트
DeepL Pro API 자동화의 본질은 ‘사전 보호(형식·불번역) → 일관성(용어집) → 안전한 재시도(운영)’의 세 박자입니다. 위 체크리스트대로 작은 단위부터 적용하면, 문서 번역 품질은 올라가고 사람 검수·재작업 비용은 안정적으로 내려갑니다. 팀에 맞는 용어집·톤을 정교화하면서 파이프라인을 꾸준히 다듬어 보세요.
