CDN Delivery: better-i18n의 엣지 캐시 전 세계 번역 서비스
Cloudflare R2와 300개 이상의 엣지 위치를 통해 번역을 제공합니다. Merge, 미리보기, 일괄 업로드, 중복 제거 — 앱을 redeploy하지 않고도 전 세계에 배포합니다.
CDN 배포: better-i18n의 엣지 캐시 전 세계 번역 서비스
better-i18n에서 게시하는 모든 번역은 Cloudflare의 글로벌 엣지 네트워크에 배포됩니다. 애플리케이션은 가장 가까운 엣지 노드에서 번역을 가져옵니다 — 오리진 서버 왕복 없이, 번역 업데이트를 위한 앱 재배포도 필요하지 않습니다.
CDN URL 구조
번역은 조직, 프로젝트, 로케일, 네임스페이스를 기반으로 예측 가능한 URL 패턴을 따릅니다:
https://cdn.better-i18n.com/{org}/{project}/{locale}/{namespace}.json
예시:
# 영어 common 네임스페이스
https://cdn.better-i18n.com/acme/web-app/en/common.json
# 터키어 auth 네임스페이스
https://cdn.better-i18n.com/acme/web-app/tr/auth.json
# 프랑스어 navigation 네임스페이스
https://cdn.better-i18n.com/acme/web-app/fr/nav.json
각 네임스페이스-로케일 조합은 별도의 JSON 파일이므로, 앱은 필요한 번역만 로드합니다. 이 URL 구조는 안정적이고 캐시 가능합니다 — CDN 엣지 노드, 브라우저 캐시, 서비스 워커 모두 이를 활용할 수 있습니다.
프로젝트 Manifest
CDN은 프로젝트의 언어 설정이 담긴 manifest 파일도 제공합니다:
https://cdn.better-i18n.com/{org}/{project}/manifest.json
프로젝트의 모든 로케일이 포함된 languages 배열을 반환합니다. Expo SDK는 이를 사용하여 런타임에 사용 가능한 언어를 자동으로 검색합니다.
CDN 작업
better-i18n은 CLI, REST API, MCP 도구를 통해 완전한 CDN 관리 작업 세트를 제공합니다.
설정 및 해제
| 작업 | 설명 |
|---|---|
cdn.setup | 프로젝트의 CDN 배포를 초기화합니다. R2 버킷 구조를 생성하고 엣지 라우팅을 구성합니다. |
cdn.uninstall | CDN 배포를 제거합니다. R2 스토리지와 엣지 구성을 정리합니다. |
업로드 작업
단일 업로드 (cdn.upload)
단일 네임스페이스-로케일 파일을 CDN에 업로드합니다:
# 영어 common 번역 업로드
better-i18n cdn upload --locale en --namespace common
파일을 R2에 기록하고 해당 경로의 엣지 캐시를 무효화합니다. 변경 사항은 몇 초 내에 300개 이상의 모든 엣지 노드에 전파됩니다.
일괄 업로드 (cdn.uploadBatch)
단일 작업으로 여러 네임스페이스-로케일 조합을 업로드합니다:
# 영어와 터키어의 모든 네임스페이스 업로드
better-i18n cdn upload-batch --locales en,tr --namespaces common,auth,dashboard
일괄 업로드는 여러 파일을 게시할 때 개별 업로드보다 훨씬 빠릅니다. R2 쓰기와 캐시 무효화를 일괄 처리하여 총 전파 시간을 줄입니다.
병합 작업
병합을 사용하면 전체 파일을 교체하지 않고 기존 CDN 파일 내의 특정 키를 업데이트할 수 있습니다. 이는 점진적 번역 업데이트에 매우 중요합니다.
병합 (cdn.merge)
# 영어 common 네임스페이스에 업데이트된 키 병합
better-i18n cdn merge --locale en --namespace common --keys "welcome,nav.home"
병합은 R2에서 기존 파일을 읽고, 키 수준 변경 사항을 적용한 후 결과를 다시 씁니다. 병합에 포함되지 않은 키는 변경되지 않습니다. 이는 여러 팀원이나 자동화 파이프라인이 동시에 게시할 때 실수로 덮어쓰는 것을 방지합니다.
병합 미리보기 (cdn.mergePreview)
병합 작업을 실행하기 전에 결과를 미리 확인합니다:
# 적용하지 않고 병합 결과 미리보기
better-i18n cdn merge-preview --locale en --namespace common --keys "welcome"
추가, 업데이트, 변경되지 않은 키를 보여주는 diff를 반환합니다. CI 파이프라인이나 검토 워크플로우에서 변경 사항이 적용되기 전에 확인하는 데 사용합니다.
파일 관리
| 작업 | 설명 |
|---|---|
cdn.listFiles | 프로젝트에 현재 배포된 모든 CDN 파일을 나열합니다. 각 파일의 로케일, 네임스페이스, 크기, 마지막 수정 타임스탬프를 반환합니다. |
cdn.deleteFile | CDN에서 특정 네임스페이스-로케일 파일을 제거합니다. 네임스페이스를 deprecated하거나 로케일을 제거할 때 사용합니다. |
중복 감지 및 정리
번역 프로젝트는 시간이 지남에 따라 중복이 누적됩니다 — 특히 네임스페이스가 재구성되거나 키가 네임스페이스 간에 이동될 때 그렇습니다.
중복 감지 (cdn.detectDuplicates)
프로젝트의 모든 CDN 파일을 스캔하고 네임스페이스 간 중복 번역 값을 식별합니다:
better-i18n cdn detect-duplicates
다른 네임스페이스에서 동일한 값을 공유하는 키를 보여주는 보고서를 반환합니다. 이를 통해 번역을 공유 네임스페이스로 통합하고 총 CDN 페이로드 크기를 줄일 수 있습니다.
중복 정리 (cdn.cleanupDuplicates)
통합 설정에 따라 감지된 중복을 자동으로 해결합니다:
# common 네임스페이스로 중복 이동
better-i18n cdn cleanup-duplicates --target-namespace common
이것은 파괴적인 작업입니다 — 변경될 내용을 검토하려면 항상 먼저 cdn.detectDuplicates를 실행하고, cdn.mergePreview를 사용하여 대상 네임스페이스 결과를 확인하세요.
업데이트 작동 방식
- 번역 편집 — 대시보드, REST API, 또는 MCP 도구를 통해 편집합니다
- 게시 —
publishTranslations를 사용합니다 —cdn_upload동기화 작업이 트리거됩니다 - CDN 업데이트 — 몇 초 내에 Cloudflare가 모든 엣지 노드에 변경 사항을 전파합니다
- 앱이 변경 사항 반영 — 다음 번역 가져오기 시 — 재배포 불필요
세밀한 제어를 위해 전체 업로드 대신 cdn.merge를 사용하여 변경된 키만 업데이트하세요. CI 파이프라인에서 cdn.mergePreview와 결합하여 CDN 배포를 검토 단계로 제어합니다.
프레임워크 통합
웹: Next.js, TanStack Start, Vite
웹 SDK(@better-i18n/next, @better-i18n/use-intl)는 i18n.config.ts를 기반으로 CDN 가져오기를 자동으로 처리합니다:
// i18n.config.ts
export const project = "acme/web-app";
export const defaultLocale = "en";
SDK는 프로젝트 식별자에서 CDN URL을 확인하고 런타임에 올바른 네임스페이스-로케일 파일을 가져옵니다.
모바일: Expo / React Native
@better-i18n/expo는 CDN 배포 위에 오프라인 우선 캐싱을 추가합니다:
import { initBetterI18n, storageAdapter } from '@better-i18n/expo';
import { MMKV } from 'react-native-mmkv';
const mmkv = new MMKV({ id: 'translations' });
await initBetterI18n({
project: 'acme/mobile-app',
i18n,
defaultLocale: 'en',
storage: storageAdapter(mmkv),
});
네트워크 우선 전략:
- CDN에서 가져오기 (최신 번역 수신)
- 영구 캐시로 폴백 (MMKV 또는 AsyncStorage)
- 번들된 정적 데이터로 폴백 (선택 사항)
사용자가 네트워크 연결 상태에서 앱을 열면 번역이 로컬에 캐시됩니다. 그 이후부터는 앱이 완전히 오프라인으로 작동합니다.
모든 HTTP 클라이언트
CDN은 일반 HTTPS 엔드포인트입니다 — SDK가 필요하지 않습니다:
curl https://cdn.better-i18n.com/acme/web-app/en/common.json
{
"welcome": "Welcome to our app",
"nav.home": "Home",
"nav.settings": "Settings"
}
Swift, Kotlin, Go, Python, Ruby 등 HTTP 요청을 보낼 수 있는 모든 언어와 플랫폼에서 사용할 수 있습니다.
인프라
- Cloudflare Workers — 전 세계 300개 이상의 위치에서 엣지 컴퓨팅
- Cloudflare R2 — 번역 파일에 대한 제로 이그레스 비용의 오브젝트 스토리지
- 자동 전파 — 변경 사항이 몇 초 내에 모든 엣지 노드에 도달
- DDoS 보호 — Cloudflare 네트워크에 내장
- TLS 1.3 — 모든 CDN 요청이 암호화됨
- 제로 이그레스 비용 — R2는 트래픽 볼륨에 관계없이 대역폭 비용을 없앱니다
네임스페이스 구성
번역을 네임스페이스로 구성하여 로드되는 항목을 제어합니다:
acme/web-app/
├── en/
│ ├── common.json → 공유 UI 문자열
│ ├── auth.json → 로그인, 회원가입, 비밀번호 재설정
│ ├── dashboard.json → 대시보드 전용 문자열
│ └── marketing.json → 랜딩 페이지 카피
├── tr/
│ ├── common.json
│ ├── auth.json
│ └── ...
└── manifest.json → 프로젝트 언어 구성
앱은 현재 페이지나 기능에 필요한 네임스페이스만 로드합니다. 로그인 페이지는 auth.json을 로드하고, 대시보드는 dashboard.json을 로드합니다. 이를 통해 번들 크기를 작게 유지하고 페이지 로드를 빠르게 합니다.
cdn.detectDuplicates를 주기적으로 사용하여 여러 네임스페이스에서 동일한 값으로 나타나는 키를 식별한 다음, cdn.cleanupDuplicates를 사용하여 common.json으로 통합하세요.
게시 제어
CDN은 게시된 번역만 제공합니다. 게시 파이프라인을 사용하여 적용되는 내용을 제어합니다:
getPendingChanges— CDN에 배포될 내용 미리보기publishTranslations— 변경 사항 배포 (전체 또는 특정 번역)cdn.mergePreview— 적용 전 키 수준 병합 결과 미리보기cdn.merge— 전체 파일 교체 없이 점진적 키 업데이트 적용getSyncs/getSync— 배포 상태 추적
이를 통해 단계별 워크플로우를 제공합니다: 보류 중인 변경 사항 미리보기, 병합 결과 확인, 게시, 배포 모니터링 — 애플리케이션 코드를 건드리지 않고도 가능합니다.
시작하기
- 프로젝트 생성 — dash.better-i18n.com에서 생성합니다
- CDN 초기화 —
cdn.setup으로 R2 스토리지와 엣지 라우팅을 구성합니다 - 번역 추가 — 대시보드, REST API, 또는 MCP 도구를 통해 추가합니다
- 게시 — CDN에 배포합니다
- 통합 —
@better-i18n/next,@better-i18n/use-intl,@better-i18n/expo, 또는 직접 HTTP를 사용합니다
번역은 무료 플랜을 포함한 모든 플랜에서 CDN을 통해 제공됩니다.