better-i18n Publish Pipeline: CDN & GitHub Deployment

better-i18n은 편집과 Deployment를 분리합니다. 번역을 자유롭게 생성하고 업데이트할 수 있습니다 — 명시적으로 Publish하기 전까지는 아무것도 라이브에 반영되지 않습니다. Publish하면 변경 사항이 추적된 Sync Job으로 CDN 엔드포인트 및/또는 GitHub 리포지토리에 배포됩니다.

이 페이지에서는 Publish Pipeline의 작동 방식, 모니터링할 수 있는 항목, 그리고 게시를 워크플로에 통합하는 방법을 설명합니다.

Publish 작동 방식

1. 대기 중인 변경 사항 미리보기

Publish하기 전에 배포될 내용을 정확히 검토합니다:

// MCP tool: getPendingChanges
{
  "project": "your-org/your-project"
}

반환값:

hasPendingChanges — 대기열에 있는 항목 여부
summary — 번역 수, 삭제된 Key, 총 변경 사항
byLanguage — 언어 코드별 분류
deletedKeys — 영구적으로 제거될 Key
publishDestination — "github", "cdn", 또는 "none"

2. Publish

대기 중인 모든 변경 사항 또는 특정 번역을 배포합니다:

// MCP tool: publishTranslations
{
  "project": "your-org/your-project"
}

// 또는 특정 번역을 Publish
{
  "project": "your-org/your-project",
  "translations": [
    { "keyId": "uuid-1", "languageCode": "tr" },
    { "keyId": "uuid-2", "languageCode": "de" }
  ]
}

Publish는 비동기입니다 — 즉시 Sync Job ID를 반환합니다.

3. Deployment 추적

Sync Job 진행 상황을 모니터링합니다:

// MCP tool: getSync
{
  "project": "your-org/your-project",
  "syncId": "sync-job-uuid"
}

상태(pending, in_progress, completed, failed), 타임스탬프, 로그, 영향받은 Key를 반환합니다.

Publish 대상

CDN Deployment

번역이 Cloudflare의 엣지 네트워크에 배포됩니다:

https://cdn.better-i18n.com/{org}/{project}/{locale}/{namespace}.json

애플리케이션이 이 엔드포인트에서 번역을 가져옵니다. Publish 성공 후 몇 초 내에 업데이트가 라이브에 반영됩니다 — 앱을 다시 배포할 필요가 없습니다.

GitHub Deployment

GitHub 리포지토리를 연결한 경우, Publish는 Pull Request를 생성하거나 설정된 브랜치에 직접 푸시합니다. 번역 파일은 설정한 패턴(예: locales/**/*.json)에 따라 업데이트됩니다.

Merge는 여러분이 제어합니다 — better-i18n이 PR을 생성하고, 팀이 검토하여 Merge합니다
설정된 파일 패턴만 변경됩니다
모든 번역 변경의 전체 Commit 기록

Sync Job 유형

유형	설명
`initial_import`	리포지토리 연결 시 첫 번째 Sync
`source_sync`	GitHub Push 이벤트로 트리거된 Sync
`cdn_upload`	번역을 CDN에 배포
`batch_publish`	여러 번역을 한 번에 Publish

최근 Sync 작업 목록 조회:

// MCP tool: getSyncs
{
  "project": "your-org/your-project",
  "limit": 10,
  "status": "completed"
}

GitHub Webhook 통합

better-i18n은 자동 Sync를 트리거하기 위해 Webhook를 통해 GitHub Push 이벤트를 수신합니다:

코드를 Push합니다 — 업데이트된 번역 파일과 함께
GitHub가 Webhook를 전송합니다 — better-i18n으로
better-i18n이 변경 사항을 Sync합니다 — 프로젝트에 반영
번역이 업데이트됩니다 — 대시보드에서

이를 통해 수동 개입 없이 클라우드 프로젝트를 리포지토리와 동기화된 상태로 유지합니다.

REST API Publishing

동일한 Publish 워크플로를 dash.better-i18n.com/api의 REST API를 통해서도 사용할 수 있습니다:

# 대기 중인 변경 사항 목록 조회
curl -H "Authorization: Bearer $API_KEY" \
  https://dash.better-i18n.com/api/projects/your-org/your-project/pending-changes

# 대기 중인 모든 변경 사항 Publish
curl -X POST -H "Authorization: Bearer $API_KEY" \
  https://dash.better-i18n.com/api/projects/your-org/your-project/publish

CI/CD 파이프라인에 Publish를 통합합니다 — 릴리스 프로세스의 일부로 번역을 배포합니다.

MCP Workflow

MCP Server를 사용하면 AI 어시스턴트가 전체 Publish 사이클을 관리합니다:

"랜딩 프로젝트에서 대기 중인 항목을 확인한 다음 모든 터키어 번역을 Publish하세요."

AI가 getPendingChanges를 호출하고 요약을 보여준 후 확인을 받아 publishTranslations를 호출합니다. getSyncs로 완료를 추적합니다.

모범 사례

항상 먼저 미리보기 — 매 Publish 전에 getPendingChanges 호출합니다
점진적으로 Publish — 한 번에 모두가 아닌 특정 언어나 Key를 배포합니다
완료 추적 — getSync를 사용하여 Job이 성공적으로 완료되었는지 확인합니다
CI로 자동화 — REST API를 통해 릴리스 파이프라인에 Publish 단계를 추가합니다
GitHub PR 활용 — 팀이 Merge 전에 번역 변경 사항을 검토할 수 있도록 합니다

Publish Pipeline은 번역이 사용자에게 언제, 어떻게 전달될지에 대한 완전한 제어권을 제공합니다. 명시적인 조치 없이는 아무것도 배포되지 않습니다.

better-i18n Publish Pipeline: CDN & GitHub Deployment