통합: better-i18n을 개발 스택에 연결하기
코드 동기화에는 GitHub, AI 어시스턴트에는 MCP, CI/CD에는 CLI, 커스텀 워크플로우에는 REST API를 활용하세요. 팀이 이미 사용하는 도구에 better-i18n을 통합하세요.
인테그레이션: better-i18n을 개발 스택에 연결하기
better-i18n은 API 우선으로 설계되었습니다. 모든 기능에 프로그래밍 방식으로 접근할 수 있으며, 플랫폼은 개발자가 매일 사용하는 도구와 직접 통합됩니다. 코드에는 GitHub, 생산성에는 AI 어시스턴트, 자동화에는 CI/CD, 런타임에는 프레임워크 SDK를 활용합니다.
GitHub
리포지토리와 better-i18n 간의 양방향 동기화:
- 인바운드 동기화 — Push 이벤트가 Webhook을 통해 번역 파일 자동 가져오기를 트리거합니다
- 아웃바운드 동기화 — 게시된 번역이 리포지토리에 풀 리퀘스트로 전달됩니다
- 파일 패턴 — 동기화할 경로를 설정합니다 (예:
locales/**/*.json) - 최소 권한 — 번역 파일에 대한 읽기/쓰기만, Push 이벤트용 Webhook만
GitHub 통합은 수동 개입 없이 클라우드 프로젝트와 리포지토리를 동기화 상태로 유지합니다. 번역 PR에 대한 전체 병합 제어권은 유지됩니다.
AI 어시스턴트 (MCP)
두 개의 MCP 서버가 AI 도구를 번역 워크스페이스에 직접 연결합니다:
| 패키지 | 도구 수 | 목적 |
|---|---|---|
@better-i18n/mcp | 11개 도구 | 번역 관리 — 키, 번역, 게시 |
@better-i18n/mcp-content | 17개 도구 | 콘텐츠 관리 — 모델, 항목, 로컬라이즈된 콘텐츠 |
지원 AI 도구
| 도구 | 연결 방법 |
|---|---|
| Claude (claude.ai) | Remote MCP URL: https://mcp.better-i18n.com/mcp |
| ChatGPT | Remote MCP URL: https://mcp.better-i18n.com/mcp |
| Gemini | Remote MCP URL: https://mcp.better-i18n.com/mcp |
| Cursor | 로컬: npx @better-i18n/mcp |
| Claude Code | 로컬: npx @better-i18n/mcp |
| Windsurf | 로컬: npx @better-i18n/mcp |
| Zed | 로컬: npx @better-i18n/mcp |
AI 어시스턴트는 키 생성, 콘텐츠 번역, 용어집 관리, 대기 중인 변경 사항 미리보기, 게시를 모두 자연어로 수행할 수 있습니다.
CLI
@better-i18n/cli는 개발 워크플로우에 통합됩니다:
Scan: 하드코딩된 문자열 감지
npx @better-i18n/cli scan --ci
React/Next.js 코드에서 번역되지 않은 텍스트를 찾습니다. useTranslations(), getTranslations(), JSX 텍스트, 속성을 지원합니다.
Sync: 로컬과 클라우드 비교
npx @better-i18n/cli sync --format json
코드에는 있지만 클라우드에 없는 키(누락)와 클라우드에 있지만 코드에서 사용되지 않는 키(미사용)를 표시합니다.
CI/CD 통합
# GitHub Actions
- run: npx @better-i18n/cli scan --ci # 하드코딩된 문자열이 있는 PR 차단
- run: npx @better-i18n/cli sync --format json # 번역 커버리지 감사
# Pre-commit 훅
npx husky init
echo "npx @better-i18n/cli scan --staged --ci" > .husky/pre-commit
REST API
모든 번역 관리 작업에 대한 전체 프로그래밍 방식 접근:
Base URL: https://dash.better-i18n.com/api
Auth: Authorization: Bearer your-api-key
| 엔드포인트 | 설명 |
|---|---|
listProjects | 조직의 모든 프로젝트 나열 |
getProject | 프로젝트 세부 정보, 언어, 네임스페이스 가져오기 |
listKeys | 검색, 네임스페이스, 상태 필터로 키 쿼리 |
createKeys | 소스 텍스트와 번역으로 키 생성 |
updateKeys | 기존 키의 번역 업데이트 |
deleteKeys | 사용하지 않는 키 소프트 삭제 |
addLanguage | 프로젝트에 대상 언어 추가 |
API 키는 대시보드에서 생성되고, 특정 프로젝트로 범위가 지정되며, 즉시 취소할 수 있습니다.
콘텐츠 SDK
로컬라이즈된 콘텐츠를 가져오기 위한 Supabase 스타일 쿼리 빌더:
import { createClient } from "@better-i18n/sdk";
const client = createClient({
project: "your-org/your-project",
apiKey: process.env.BETTER_I18N_CONTENT_API_KEY,
});
const { data, total } = await client
.from("blog-posts")
.eq("status", "published")
.language("fr")
.order("publishedAt", { ascending: false })
.limit(20);
의존성 없음, TypeScript로 완전히 타입화, 모든 JavaScript 런타임에서 작동합니다.
프레임워크 SDK
| 프레임워크 | 패키지 | 런타임 |
|---|---|---|
| Next.js (App Router & Pages) | @better-i18n/next | 서버 + 클라이언트 |
| TanStack Start | @better-i18n/use-intl | SSR + 클라이언트 |
| Vite + React | @better-i18n/use-intl | 클라이언트 |
| Expo (React Native) | @better-i18n/expo | 클라이언트 + 오프라인 |
모든 SDK는 동일한 CDN 엔드포인트와 네임스페이스 구조를 사용합니다. 웹 및 모바일 앱은 번역에 대한 단일 진실 공급원을 공유합니다.
CDN
번역은 Cloudflare의 엣지 네트워크에서 제공됩니다:
https://cdn.better-i18n.com/{org}/{project}/{locale}/{namespace}.json
- 전 세계 100ms 미만 전송 (300개 이상의 엣지 위치)
- 업데이트는 게시 후 수 초 내에 전파됩니다
- 번역 변경을 위한 앱 재배포 불필요
- 언어 검색을 위한 매니페스트 엔드포인트
사용자 정의 통합
REST API와 콘텐츠 SDK를 통해 모든 시스템과 사용자 정의 통합이 가능합니다:
- 내부 도구 — 관리자 패널에 번역 관리 구축
- 자동화된 워크플로우 — 이벤트 파이프라인에서 번역 트리거
- 사용자 정의 대시보드 — 번역 메트릭을 분석에 가져오기
- 콘텐츠 파이프라인 — 로컬라이즈된 콘텐츠를 CMS에 통합
대시보드에서 사용 가능한 모든 작업은 API를 통해서도 사용할 수 있습니다. HTTP 요청을 보낼 수 있다면 better-i18n과 통합할 수 있습니다.
시작하기
- GitHub — 프로젝트 설정에서 리포지토리를 연결합니다
- MCP — AI 도구의 설정에
npx @better-i18n/mcp를 추가합니다 - CLI —
npm install -D @better-i18n/cli - API — dash.better-i18n.com/settings/api-keys에서 API 키를 생성합니다
모든 통합은 무료 티어를 포함한 모든 플랜에서 이용 가능합니다.