Translation Sync Engine — better-i18n 로컬라이제이션 파이프라인을 위한 신뢰할 수 있는 비동기 처리
소스 코드, 번역, CDN을 완벽하게 동기화 상태로 유지하는 신뢰할 수 있는 비동기 번역 파이프라인 — 충돌 감지, Activity Logging, 제로 데이터 손실을 갖추고 있습니다.
전용 Sync Engine이 필요한 이유
번역 워크플로우는 여러 시스템에 관여합니다 — Git 리포지토리, 번역 데이터베이스, 런타임 전달을 위한 CDN, 컨텍스트 분석을 위한 AI 서비스입니다. 이러한 시스템을 실시간으로 조율하는 것은 취약합니다. API 타임아웃이 한 번만 발생해도 번역이 일관성 없는 상태가 될 수 있습니다.
Better i18n은 Cloudflare Queues 위에 구축된 전용 Sync Engine으로 이 문제를 해결합니다. Key 가져오기부터 번역 게시까지 모든 작업은 재시도, 순서 보장, 완전한 관찰 가능성을 갖춘 비동기 Job으로 처리됩니다.
결과: 무언가 잘못되더라도 모든 시스템에서 번역이 일관되게 유지됩니다.
아키텍처 개요
Sync Engine은 구조화된 메시지를 처리하는 Cloudflare Queue 컨슈머입니다. 각 메시지는 트리거할 Sync, 업로드할 파일, 게시할 배치 등 개별 작업 단위를 나타냅니다.
메시지는 명확하게 정의된 라이프사이클을 통해 흐릅니다:
- Producer — 사용자의 작업(Push 이벤트, 수동 Sync, 게시)이 메시지를 큐에 넣습니다
- Queue — Cloudflare Queues가 내구성 있는 순서 배달을 제공합니다
- Consumer — Sync 워커가 메시지를 가져와 Job을 실행합니다
- Activity Log — 완전한 추적성을 위해 모든 단계가 Sync 활동으로 기록됩니다
이 분리 덕분에 API 응답이 빠르고(작업은 백그라운드에서 수행됨), 실패는 사용자 개입 없이 자동으로 재시도됩니다.
10가지 메시지 타입
Sync Engine은 각각 특정 작업 클래스를 담당하는 10가지 고유한 메시지 타입을 처리합니다:
| 메시지 타입 | 목적 |
|---|---|
| SYNC_START | 전체 또는 증분 GitHub Sync를 트리거합니다 — 파일 가져오기, Key 비교, 데이터베이스 업데이트 |
| REPO_PUSH_SYNC | GitHub Push Webhook 이벤트를 처리합니다 — 빠른 증분 Sync를 위해 변경된 파일만 처리 |
| CDN_SETUP | 프로젝트가 처음 구성될 때 초기 CDN 매니페스트와 빈 언어 파일을 생성합니다 |
| CDN_UPLOAD | 단일 JSON 번역 파일을 R2 스토리지에 업로드합니다 |
| CDN_MERGE | 변경되지 않은 Key를 덮어쓰지 않고 기존 CDN 파일에 새 번역 콘텐츠를 병합합니다 |
| CDN_CLEANUP | 프로젝트의 모든 R2 파일을 제거합니다 (프로젝트 삭제 또는 재설정 시 사용) |
| AI_CONTEXT_ANALYSIS | Firecrawl + Gemini로 웹사이트를 분석하여 번역 컨텍스트를 구축합니다 |
| REPO_ANALYSIS | GitHub 리포지토리를 스캔하여 프레임워크를 감지하고 용어를 추출하며 프로젝트 컨텍스트를 구축합니다 |
| PUBLISH_BATCH | 단일 원자적 작업으로 승인된 번역을 CDN과 GitHub 모두에 푸시합니다 |
| GLOSSARY_SYNC | 일관된 기계 번역을 위해 DeepL과 용어 글로서리를 동기화합니다 |
각 메시지 타입에는 자체 핸들러, 유효성 검사 및 오류 복구 로직이 있습니다. CDN 업로드 실패가 Sync 작업을 차단하지 않으며, 그 반대도 마찬가지입니다.
전체 라이프사이클 커버리지를 위한 12가지 Job 타입
Job은 여러 메시지를 생성할 수 있는 더 높은 수준의 워크플로우를 나타냅니다:
- initial_import — 리포지토리에서 처음으로 Key 추출
- incremental_sync — 마지막 실행 이후 변경된 파일만 동기화
- full_sync — 모든 번역 파일의 완전한 재동기화
- source_sync — 소스 언어 변경 사항만 동기화
- bulk_translate — 여러 언어에 대한 기계 번역 트리거
- publish / batch_publish — 승인된 번역을 프로덕션에 푸시
- cdn_upload / cdn_merge / cdn_setup / cdn_cleanup — CDN 라이프사이클 작업
- glossary_sync — DeepL 글로서리를 최신 상태로 유지
Job 타입은 세밀한 제어를 제공합니다. 필요한 워크플로우를 정확히 트리거할 수 있습니다 — 불필요한 처리도, 낭비되는 컴퓨팅도 없습니다.
완전한 관찰 가능성을 위한 45개 이상의 Activity Actions
모든 Sync Job은 진행되면서 구조화된 Activity Action을 기록합니다. 45개 이상의 고유한 액션 타입으로 무슨 일이 언제 왜 발생했는지에 대한 완전한 그림을 얻을 수 있습니다.
일반적인 Sync 흐름은 이 Activity 추적을 생성합니다:
SYNC_STARTED → FETCH_FILES → FILES_FETCHED → COMPARE_KEYS →
UPDATE_DATABASE → PR_GENERATION_STARTED → PR_CREATED → SYNC_COMPLETED
Activity Action은 디버깅만을 위한 것이 아닙니다 — 실시간 Sync 상태 UI를 구동하여 팀이 Sync가 라이프사이클에서 정확히 어디에 있는지 확인할 수 있게 합니다. 무언가 실패하면 마지막으로 기록된 액션이 정확히 무엇이 잘못되었는지 알려줍니다.
충돌 감지 및 해결
여러 소스가 동일한 번역 Key를 수정하면 충돌은 불가피합니다. Sync Engine은 전용 충돌 감지 및 해결 시스템으로 이를 처리합니다.
충돌 감지 방법
모든 Sync에서 Engine은 들어오는 변경 사항을 현재 데이터베이스 상태와 비교합니다. 마지막 Sync 이후 리포지토리와 데이터베이스 모두에서 Key가 수정된 경우 충돌로 표시됩니다.
충돌 해결 방법
충돌은 전체 컨텍스트와 함께 팀에 표시됩니다 — 소스 값, 데이터베이스 값, 각 변경의 타임스탬프입니다. 충돌을 개별적으로 또는 일괄적으로 해결할 수 있습니다:
- 소스 유지 — 리포지토리 버전 수락
- 데이터베이스 유지 — 기존 번역 보존
- 수동 병합 — 최종 값을 직접 편집
Engine은 번역을 자동으로 덮어쓰지 않습니다. 모든 충돌은 기록되고 추적되며 명시적인 해결이 필요합니다.
설계에 의한 신뢰성
Sync Engine은 모든 계층에서 신뢰성을 위해 구축되었습니다:
- 내구성 있는 메시지 배달 — Cloudflare Queues는 최소 한 번의 배달을 보장합니다. 메시지는 워커 재시작과 인프라 장애에서 살아남습니다.
- 자동 재시도 — 실패한 Job은 지수 백오프로 재시도됩니다. 일시적인 오류(API 타임아웃, 속도 제한)는 자동으로 해결됩니다.
- 멱등 작업 — 모든 메시지 핸들러는 안전하게 재실행되도록 설계되었습니다. 재시도는 중복 데이터를 생성하지 않습니다.
- 순서 있는 처리 — 프로젝트 내 메시지는 순서대로 처리되어 관련 작업 간의 경쟁 조건을 방지합니다.
- Activity Logging — 모든 단계가 기록되어 디버깅 및 컴플라이언스를 위한 완전한 감사 추적을 제공합니다.
시작하기
GitHub 리포지토리를 Better i18n에 연결하면 Sync Engine이 즉시 작동합니다. 구성할 것이 없습니다 — Sync, CDN 업데이트 및 충돌 감지가 모두 자동으로 처리됩니다.
더 많은 제어가 필요한 팀을 위해 Sync Engine은 특정 워크플로우 트리거, 진행 상황 모니터링, 프로그래밍 방식의 충돌 해결을 가능하게 하는 Job 수준 API를 노출합니다.