목차
CDN Translation Delivery: Edge Cache로 구현하는 i18n 성능 가이드
번역 배포는 눈에 잘 보이지 않는 성능 문제입니다. 앱의 페이지 로딩이 1초 이하이고, 이미지가 최적화되어 있으며, 번들이 코드 분할되어 있더라도 — 번역이 늦게 도착하면 사용자는 레이아웃 이동, 로딩 스피너, 혹은 더 심각하게는 화면에서 깜빡이는 미번역 키를 보게 됩니다.
이 가이드에서는 better-i18n이 Cloudflare R2와 Edge Caching을 사용하여 번역 배포 문제를 어떻게 해결하는지 설명하고, 엔지니어링 팀이 사용할 수 있는 모든 CDN 작업을 안내합니다.
번역 배포가 i18n 성능에 중요한 이유
전통적인 i18n 설정은 번역을 애플리케이션에 번들링합니다. 오탈자를 수정하거나 새 언어를 추가할 때마다 전체 재빌드와 재배포가 필요합니다. 모바일 앱의 경우 앱 스토어 심사를 기다려야 합니다. 웹 앱의 경우 엔지니어링 외 변경을 차단하는 배포 파이프라인을 의미합니다.
CDN 번역 배포는 번역 콘텐츠를 애플리케이션 코드에서 분리합니다. 번역은 Edge에 존재하며 사용자와 가장 가까운 Cloudflare 노드에서 제공됩니다. 앱은 런타임에 HTTP로 번역을 가져옵니다.
성능 특성:
- 50ms 미만 전달 — 가장 가까운 Edge 노드에서 (전 세계 300개 이상 위치)
- 오리진 왕복 제로 — 캐시된 번역의 경우
- 증분 업데이트 — 애플리케이션 재배포 없이
- 병렬 로딩 — 현재 페이지에 필요한 네임스페이스만
이것을 가능하게 하는 URL 구조
better-i18n의 모든 번역 파일은 결정론적 URL 패턴을 따릅니다:
https://cdn.better-i18n.com/{org}/{project}/{locale}/{namespace}.json
이 구조는 의도적으로 단순하고 예측 가능합니다. 이것이 의미하는 바:
- 브라우저 캐시가 기본적으로 동작합니다 — 각 로케일-네임스페이스 쌍은 고유하고 안정적인 URL을 가집니다
- Service Worker가 알려진 경로를 미리 캐시할 수 있습니다 — 디스커버리 요청 없이
- CDN Edge 노드가 경로별로 독립적으로 캐시합니다 —
fr/auth.json의 캐시 미스가en/common.json에 영향을 주지 않습니다 - 모든 HTTP 클라이언트가 사용할 수 있습니다 — SDK 없음, 인증 없음, 특별한 헤더 없음
실제 예시:
# English common translations https://cdn.better-i18n.com/acme/web-app/en/common.json # Turkish authentication strings https://cdn.better-i18n.com/acme/web-app/tr/auth.json # Japanese dashboard translations https://cdn.better-i18n.com/acme/web-app/ja/dashboard.json
각 프로젝트에는 /{org}/{project}/manifest.json에 모든 사용 가능한 로케일을 나열하는 매니페스트가 있습니다. 모바일 SDK는 이를 사용하여 로케일 목록을 하드코딩하지 않고 런타임에 언어를 자동 검색합니다.
Upload 대 Merge: CDN 업데이트를 위한 두 가지 모델
better-i18n은 CDN의 번역을 업데이트하는 두 가지 접근 방식을 제공합니다.
전체 Upload (cdn.upload 및 cdn.uploadBatch)
Upload는 R2의 전체 네임스페이스-로케일 파일을 교체합니다:
# Single file better-i18n cdn upload --locale en --namespace common # Multiple files in one operation better-i18n cdn upload-batch --locales en,tr,fr --namespaces common,auth
배치 Upload가 적합한 경우:
- 처음으로 새 언어를 게시할 때
- 대규모 재구성 후 CDN 파일을 재구축할 때
- TMS에서 전체 번역 내보내기를 배포할 때
배치 작업은 내부적으로 최적화되어 있습니다 — R2 쓰기와 캐시 무효화가 일괄 처리되어 순차적 개별 Upload보다 전체 전파 시간이 줄어듭니다.
증분 Merge (cdn.merge)
Merge는 R2에서 기존 파일을 읽고, 키 수준의 변경 사항을 적용하고, 결과를 다시 씁니다:
better-i18n cdn merge --locale en --namespace common --keys "welcome,nav.home"
Merge에 포함되지 않은 키는 변경되지 않습니다. 증분 업데이트에 더 안전한 옵션입니다. 왜냐하면:
- 실수로 덮어쓰기 없음 — 파일의 다른 키들이 보존됩니다
- 동시성 안전 — 여러 팀원이나 CI 파이프라인이 충돌 없이 다른 키를 Merge할 수 있습니다
- 더 작은 변경 범위 — 지정된 키만 변경됩니다
Merge 미리보기 (cdn.mergePreview)
Merge를 실행하기 전에 결과를 미리 봅니다:
better-i18n cdn merge-preview --locale en --namespace common --keys "welcome"
이것은 어떤 키가 추가, 업데이트 또는 변경 없이 남을지 보여주는 diff를 반환합니다. 데이터베이스 마이그레이션을 적용하기 전에 검토하는 것처럼, CI 파이프라인에서 Merge 미리보기를 사용하여 CDN 배포를 검토 단계 뒤에 두세요.
중복 감지: CDN 페이로드를 가볍게 유지하기
번역 프로젝트가 성장함에 따라 중복이 쌓입니다. "저장" 버튼 문자열이 common.json, settings.json, profile.json 세 곳 모두에 동일한 값으로 존재할 수 있습니다. 각 중복은 CDN 전체 페이로드를 증가시키고 유지 관리 부담을 만듭니다 — 하나를 업데이트하고 다른 것들을 잊어버립니다.
중복 감지 (cdn.detectDuplicates)
better-i18n cdn detect-duplicates
프로젝트의 모든 CDN 파일을 스캔하고 네임스페이스 간에 동일한 번역 값을 공유하는 키의 보고서를 생성합니다. 보고서에는 다음이 표시됩니다:
- 어떤 키가 중복되는지
- 어떤 네임스페이스에 포함되어 있는지
- 공유 값
정리 (cdn.cleanupDuplicates)
better-i18n cdn cleanup-duplicates --target-namespace common
중복을 대상 네임스페이스(일반적으로 common)로 통합하고 소스 네임스페이스에서 제거합니다. 작업은 내부적으로 Merge를 사용하므로 동시 접근에 안전합니다.
모범 사례: 대규모 번역 가져오기나 네임스페이스 재구성 후 cdn.detectDuplicates를 실행합니다. CDN 페이로드를 최소한으로 유지하기 위해 정기적인 정리를 예약하세요.
CDN 수명 주기 관리
Setup (cdn.setup)
프로젝트의 CDN 배포 초기화:
better-i18n cdn setup
R2 버킷 구조를 생성하고, Cloudflare Worker Edge 라우팅을 구성하고, 캐시 규칙을 설정합니다. 프로젝트에 CDN 배포를 처음 활성화할 때 한 번 실행합니다.
파일 관리
CDN 상태를 감사하기 위해 배포된 모든 파일 나열:
better-i18n cdn list-files
각 파일의 로케일, 네임스페이스, 크기, 마지막 수정 타임스탬프를 반환합니다. 배포를 확인하고 오래된 파일을 식별하는 데 유용합니다.
네임스페이스를 더 이상 사용하지 않거나 로케일을 제거할 때 개별 파일 삭제:
better-i18n cdn delete-file --locale en --namespace legacy-feature
Teardown (cdn.uninstall)
CDN 배포 완전 제거:
better-i18n cdn uninstall
R2 스토리지, Edge 구성, 캐시 규칙을 정리합니다. 프로젝트를 마이그레이션하거나 애플리케이션을 폐기할 때 사용합니다.
실제 성능
프로덕션에서의 CDN 번역 배포 모습:
| 지표 | 값 |
|---|---|
| Edge 위치 | 300개 이상 (Cloudflare 네트워크) |
| 캐시 히트 지연 | 50ms 미만 (일반적) |
| 캐시 미스 지연 | 200ms 미만 (R2 오리진 페치) |
| 전파 시간 | 게시 후 10초 미만 |
| Egress 비용 | 0원 (Cloudflare R2) |
제로 Egress 비용 측면은 강조할 가치가 있습니다. 전통적인 CDN 설정은 GB당 대역폭을 청구합니다. R2를 사용하면 번역 배포 비용은 트래픽 볼륨에 관계없이 고정됩니다. 월 천만 번의 번역 페치를 제공하는 프로젝트는 천 번인 프로젝트와 같은 비용을 지불합니다.
번역을 위한 네임스페이스 기반 코드 분할
네임스페이스 모델은 번역을 위한 코드 분할 역할을 합니다. 모든 번역을 미리 로드하는 대신:
❌ /en/all-translations.json (450 KB)
앱은 현재 라우트에 필요한 것만 로드합니다:
✅ /en/common.json (12 KB) + /en/auth.json (4 KB) = 16 KB
이를 통해 대규모 번역 세트가 있는 앱의 초기 페이지 로드가 90% 이상 감소합니다. Edge Caching과 결합하면 이후 페이지 탐색은 새 네임스페이스만 가져옵니다 — dashboard.json은 사용자가 대시보드로 이동할 때 로드되며, 그 전에는 로드되지 않습니다.
통합 접근 방식
SDK 통합 (권장)
공식 SDK는 CDN 페치, 캐싱, 폴백을 자동으로 처리합니다:
@better-i18n/next— ISR/SSG 지원이 있는 서버 사이드 페칭@better-i18n/use-intl— TanStack Router 및 Vite 앱을 위한 클라이언트 사이드 페칭@better-i18n/expo— MMKV/AsyncStorage 캐싱을 사용한 오프라인 우선
각 SDK는 i18n.config.ts 프로젝트 식별자에서 CDN URL을 해석합니다. 수동 URL 구성이 필요 없습니다.
직접 HTTP (모든 플랫폼)
CDN은 일반 HTTPS 엔드포인트입니다. 인증 없음, 특별한 헤더 없음:
curl https://cdn.better-i18n.com/acme/web-app/en/common.json
이를 통해 better-i18n 번역을 모든 플랫폼에서 사용할 수 있습니다: iOS (Swift), Android (Kotlin), 백엔드 서비스 (Go, Python, Ruby), 게임 엔진, IoT 장치 — HTTP GET 요청을 할 수 있는 모든 것.
Publish-to-CDN 파이프라인
번역을 편집하여 전 세계에 제공하기까지의 전체 워크플로우:
- 편집 — 대시보드, REST API 또는 MCP 도구
- 보류 중인 변경 사항 미리보기 —
getPendingChanges로 배포될 내용 확인 - Merge 결과 미리보기 —
cdn.mergePreview로 키 수준 diff 표시 (선택 사항) - 게시 —
publishTranslations이cdn_upload동기화 작업을 트리거합니다 - 모니터링 —
getSyncs/getSync으로 배포 상태 추적 - 확인 —
cdn.listFiles로 업데이트된 파일이 라이브인지 확인
이를 통해 엔지니어링 팀은 코드 배포와 동일한 엄격함을 번역 배포에도 적용할 수 있습니다: 미리보기, 게시, 모니터링, 확인.
시작하기
- dash.better-i18n.com에서 프로젝트 생성
- R2 스토리지와 Edge 라우팅을 초기화하기 위해
cdn.setup실행 - 번역을 추가하고 CDN에 게시합니다
- 프레임워크 SDK 또는 직접 HTTP로 통합
cdn.listFiles및cdn.detectDuplicates로 모니터링
CDN 배포는 무료 플랜을 포함한 모든 플랜에서 사용할 수 있습니다. 번역은 첫날부터 Edge에서 캐시됩니다.
