GitHub 연동: 리포지토리와 번역을 동기화하세요

better-i18n은 GitHub 리포지토리에 직접 연결됩니다. Push 이벤트는 HMAC-SHA256으로 검증된 Webhook을 통해 자동 동기화를 트리거하고, 번역 업데이트는 Pull Request로 제공되며, Doctor CI 워크플로우는 모든 Commit에서 번역 품질을 보호합니다.

작동 방식

인바운드: 코드에서 클라우드로

GitHub에 코드를 Push하면 better-i18n이 Webhook 이벤트를 수신하고 번역 파일을 동기화합니다:

GitHub에 Push — 팀이 코드 변경 사항을 Commit합니다
Webhook 발생 — GitHub이 HMAC-SHA256 서명으로 검증된 push 이벤트를 전송합니다
파일 Sync — 설정된 패턴과 일치하는 번역 파일이 클라우드 프로젝트에 동기화됩니다
대시보드 업데이트 — 새 키가 표시되고 변경된 번역이 반영됩니다

아웃바운드: 클라우드에서 코드로

번역가가 대시보드(또는 API/MCP)에서 번역을 업데이트하면 리포지토리에 다시 게시합니다:

번역 업데이트 — 대시보드, REST API 또는 MCP 도구를 통해
Publish — publishTranslations를 호출하거나 대시보드의 Publish 버튼을 사용합니다
Pull Request 생성 — better-i18n이 전용 Branch에 업데이트된 번역 파일이 포함된 PR을 생성합니다
팀이 리뷰하고 Merge — 표준 코드 리뷰 워크플로우가 적용됩니다

Webhook 이벤트와 보안

better-i18n은 모든 수신 이벤트에 HMAC-SHA256 서명 검증을 사용하는 GitHub App Webhook을 사용합니다. 인증되지 않은 페이로드는 처리되지 않습니다.

지원되는 Webhook 이벤트

이벤트	동작
push	리포지토리에서 클라우드로 번역 파일 동기화를 트리거합니다
installation.deleted	연동을 자동으로 제거하고 정리합니다
installation.suspend	Sync를 일시 중지 — 일시 중지된 동안 Webhook이 처리되지 않습니다
installation.unsuspend	Sync를 재개 — Webhook이 다시 처리됩니다

모든 Webhook 페이로드는 처리 전에 GitHub의 HMAC-SHA256 서명에 대해 검증됩니다. 잘못된 서명은 즉시 거부됩니다.

PR 기반 번역 워크플로우

번역 업데이트는 기존 코드 리뷰 프로세스를 따릅니다:

번역가 또는 AI 에이전트가 better-i18n 대시보드에서 번역을 업데이트합니다
준비가 되면 번역을 리포지토리에 게시합니다
better-i18n이 변경된 번역 파일만 포함하는 Pull Request를 생성합니다
팀이 diff를 리뷰 — 어떤 키가 변경되었는지, 어떤 언어가 업데이트되었는지 정확히 확인할 수 있습니다
만족스러우면 Merge — 번역은 다른 코드 변경과 동일한 워크플로우를 통해 코드베이스에 반영됩니다

이 접근 방식의 의미:

직접 Push 없음 — 모든 번역 변경 사항은 PR 리뷰를 통해 진행됩니다
완전한 감사 추적 — 모든 번역 변경 사항이 git 기록에 추적됩니다
CI 검증 — 기존 CI 파이프라인도 번역 PR에 대해 실행됩니다
롤백 지원 — 번역 PR을 다른 Commit처럼 되돌릴 수 있습니다

멀티 리포지토리 지원

여러 리포지토리를 단일 better-i18n 프로젝트에 연결하거나 동일한 리포지토리를 여러 프로젝트에 연결할 수 있습니다. 일반적인 설정:

모노리포 — 번역 프로젝트를 공유하는 여러 앱이 있는 하나의 리포지토리
마이크로 프론트엔드 — 공유 번역 세트에 기여하는 여러 리포지토리
플랫폼 + 모바일 — 동일한 번역 소스에서 동기화하는 웹 및 모바일 리포지토리

리포지토리 관리

대시보드 또는 tRPC API를 사용하여 연결된 리포지토리를 관리합니다:

작업	tRPC 메서드
리포지토리 연결	`github.addRepository`
수동 동기화 트리거	`github.syncRepository`
리포지토리 연결 해제	`github.removeRepository`
리포지토리 파일 탐색	`github.getSourceFiles`
사용 가능한 Branch 목록	`github.listBranches`
리포지토리 트리 보기	`github.getTree`

Doctor CI 워크플로우

Doctor 워크플로우는 better-i18n이 리포지토리를 위해 생성할 수 있는 GitHub Actions 워크플로우입니다. 모든 Push와 Pull Request에서 번역 상태 확인을 실행합니다.

Doctor가 확인하는 항목

누락된 번역 — 소스 언어에 있지만 대상 언어에 없는 키
사용하지 않는 키 — 번역 파일에 정의되어 있지만 코드에서 참조되지 않는 키
형식 일관성 — 모든 언어에 걸친 ICU 메시지 구문 검증
커버리지 보고서 — 언어별 번역 완료 비율

Doctor 설정

tRPC API를 사용하여 워크플로우 파일을 생성합니다:

github.createDoctorWorkflow

이를 통해 모든 Push와 Pull Request에서 실행되는 .github/workflows/i18n-doctor.yml 파일이 리포지토리에 생성됩니다.

Doctor 출력 예시

i18n Doctor Report
==================

Coverage:
  en: 100% (source)
  tr: 94.2% (missing 23 keys)
  de: 87.1% (missing 51 keys)

Unused keys: 12
Format errors: 0

Result: WARNING — 2 languages below 95% threshold

Doctor는 GitHub의 체크 시스템과 통합됩니다 — 누락된 번역이나 형식 오류를 도입하는 PR은 경고 상태를 표시합니다.

GitHub 권한

better-i18n은 최소한의 GitHub 권한을 요청합니다:

권한	용도
Repository Contents	번역 파일만 읽기/쓰기 (설정된 패턴)
Pull Requests	번역 업데이트를 위한 PR 생성
Webhooks	Sync를 위한 Push 이벤트 수신

설정된 패턴(예: locales/**/*.json)과 일치하는 파일에만 액세스합니다. better-i18n은 소스 코드, 설정 파일 또는 번역 파일 경로 외부의 어떤 것도 읽지 않습니다.

파일 형식

better-i18n은 locale 및 namespace로 구성된 JSON 번역 파일을 사용합니다:

your-repo/
├── locales/
│   ├── en/
│   │   ├── common.json
│   │   ├── auth.json
│   │   └── dashboard.json
│   ├── tr/
│   │   ├── common.json
│   │   ├── auth.json
│   │   └── dashboard.json
│   └── de/
│       └── ...

better-i18n이 동기화하는 파일 패턴은 프로젝트 설정에서 구성합니다.

CLI: 코드베이스에서 키 감지

@better-i18n/cli는 로컬 개발과 클라우드 프로젝트를 연결합니다.

하드코딩된 문자열 스캔

npx @better-i18n/cli scan

React/Next.js 코드베이스에서 번역되지 않은 텍스트를 감지합니다:

components/sign-up.tsx (11)
  24:13  missing  "Create an account"  i18n/jsx-text
  32:22  missing  "Name"               i18n/jsx-text

✖ 87 problems (87 missing translations)

지원:

useTranslations('namespace') — 클라이언트 컴포넌트
getTranslations('namespace') — 서버 컴포넌트 (Next.js App Router)
JSX 텍스트, 속성 및 locale 기반 삼항 연산자

로컬 vs. 클라우드 비교

npx @better-i18n/cli sync

코드에는 있지만 클라우드에 없는 항목과 클라우드에는 있지만 코드에서 사용되지 않는 항목을 표시합니다:

Coverage:
  Local → Remote: 59%
  Remote Used: 63%

⊕ Missing in Remote (473 keys)
  pages (300)
    affordableEnglishLearning (meta.title, meta.description, ...+12)

⊖ Unused in Code (386 keys)
  features (25)
    practiceSpeaking (title, subtitle, icon)

CI/CD 통합

GitHub Actions 워크플로우에 추가합니다:

name: i18n Check
on: [push, pull_request]

jobs:
  i18n:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npx @better-i18n/cli scan --ci
      - run: npx @better-i18n/cli sync --format json

번역되지 않은 문자열을 도입하는 PR을 차단합니다. 모든 Push에서 번역 커버리지를 감사합니다.

Pre-Commit 훅

# Husky 사용
npx husky init
echo "npx @better-i18n/cli scan --staged --ci" > .husky/pre-commit

// lint-staged 사용
{
  "lint-staged": {
    "*.{tsx,jsx}": ["better-i18n scan --ci"]
  }
}

Sync 추적

모든 Sync 작업은 전체 상태 및 로그와 함께 작업으로 추적됩니다:

// MCP tool: getSyncs
{
  "project": "your-org/your-project",
  "status": "completed",
  "type": "source_sync"
}

Sync 유형:

initial_import — 리포지토리 연결 시 첫 번째 동기화
source_sync — GitHub Push 이벤트에 의해 트리거됨
cdn_upload — CDN 배포
batch_publish — GitHub에 번역 게시

설정

i18n.config.ts

CLI는 i18n.config.ts에서 프로젝트 설정을 읽습니다:

export const project = "your-org/your-project";
export const defaultLocale = "en";

export const i18nWorkspaceConfig = {
  project,
  defaultLocale,
  lint: {
    include: ["src/**/*.tsx", "app/**/*.tsx"],
    exclude: ["**/*.test.tsx", "**/*.stories.tsx"],
  },
};

시작하기

GitHub App 설치 — dash.better-i18n.com에서 GitHub 계정을 연결합니다
리포지토리 추가 — github.addRepository를 통해 동기화할 리포지토리를 선택합니다
파일 패턴 설정 — 번역 파일이 있는 위치를 better-i18n에 알려줍니다
Doctor CI 활성화 — github.createDoctorWorkflow로 i18n 상태 확인 워크플로우를 생성합니다
CLI 설치 — npm install -D @better-i18n/cli
동기화 시작 — 코드를 Push하고 GitHub와 클라우드 사이에서 번역이 흐르는 것을 확인합니다

GitHub 연동은 모든 플랜에서 이용 가능합니다.

GitHub 연동: 리포지토리와 번역을 동기화하세요 – better-i18n