목차
API 우선 현지화: 개발 워크플로에 번역을 통합하는 방법
핵심 요점
- API 우선 현지화는 코드베이스와 번역 관리 시스템 사이의 자동 동기화로 수동 파일 교환을 대체합니다
- CLI 도구와 CI/CD 통합을 통해 배포마다 번역을 동기화 상태로 유지하는 push/pull 워크플로가 가능합니다
- Webhook 기반 알림은 번역이 업데이트될 때 빌드를 트리거하여 지속적인 현지화를 가능하게 합니다
- API 우선 방식은 새로운 언어의 출시 시간을 몇 주에서 몇 시간으로 단축합니다
API 우선 현지화란 무엇입니까?
API 우선 현지화는 번역 관리 시스템(TMS)이 REST API, CLI 도구, Webhook을 통해 모든 번역 워크플로에 프로그래밍 방식의 접근을 제공하는 방식입니다. 번역 파일을 수동으로 내보내고 가져오는 대신, 개발자는 빌드 및 배포 파이프라인에 번역 동기화를 직접 통합합니다.
기존 방식 vs. API 우선 워크플로
기존 방식 (파일 기반)
- 개발자가 소스 문자열을 파일(JSON, XLIFF 등)로 내보냅니다
- 파일을 TMS에 업로드하거나 이메일로 번역가에게 전송합니다
- 번역된 파일이 며칠 또는 몇 주 후에 반환됩니다
- 개발자가 파일을 다운로드하여 올바른 디렉터리에 배치합니다
- 개발자가 커밋하고 배포합니다
문제점: 수동 단계, 버전 불일치, 병합 충돌, 느린 사이클 시간.
API 우선
- 개발자가 CLI로 새 문자열을 푸시합니다:
better-i18n push - TMS가 번역가에게 새 콘텐츠를 알립니다
- 번역가가 전체 컨텍스트를 갖춘 TMS 편집기에서 작업합니다
- 번역이 완료되면 Webhook이 CI/CD를 트리거합니다
- 빌드가 최신 번역을 가져옵니다:
better-i18n pull - 배포에 업데이트된 번역이 자동으로 포함됩니다
장점: 수동 파일 처리 없음, 지속적인 동기화, 빠른 사이클 시간.
API 우선 현지화의 핵심 구성 요소
REST API
TMS API는 다음 엔드포인트를 제공합니다:
POST /api/keys — 새 번역 키 생성 GET /api/translations — 로케일의 번역 가져오기 PUT /api/translations — 번역 업데이트 GET /api/projects — 프로젝트 및 상태 목록 조회 POST /api/upload — 소스 파일 업로드 GET /api/download — 번역된 파일 다운로드
CLI 도구
개발자 편의를 위해 API를 감싸는 명령줄 도구입니다:
# 새 소스 문자열을 TMS에 푸시 better-i18n push # 최신 번역 가져오기 better-i18n pull --locale=de,fr,ja # 번역 상태 확인 better-i18n status # 미번역 문자열 코드베이스 스캔 better-i18n scan
Webhook
번역이 변경될 때의 이벤트 기반 알림입니다:
{
"event": "translations.completed",
"project": "my-app",
"locale": "de",
"completed_keys": 142,
"total_keys": 142
}
Webhook을 사용하여 CI/CD 파이프라인, Slack 알림 또는 자동 배포를 트리거하십시오.
CI/CD 통합
번역 동기화를 빌드 파이프라인에 통합합니다:
# GitHub Actions 예시
- name: Pull translations
run: better-i18n pull --all
env:
BETTER_I18N_TOKEN: ${{ secrets.BETTER_I18N_TOKEN }}
- name: Build
run: npm run build
API 우선 현지화의 장점
| 장점 | 효과 |
|---|---|
| 자동화된 동기화 | 수동 파일 관리 불필요 |
| 버전 관리 | 코드와 함께 번역 추적 |
| 지속적인 배포 | 매 배포마다 새 번역 출시 |
| 개발자 경험 | 친숙한 CLI/API 워크플로 |
| 빠른 출시 시간 | 새 언어를 몇 주가 아닌 몇 시간 만에 |
| 오류 감소 | 파일 형식 문제나 잘못 배치된 파일 없음 |
구현 패턴
패턴 1: 빌드 타임 Pull
빌드 단계에서 번역을 가져옵니다. 번역은 빌드 시 앱에 번들됩니다.
적합한 대상: 정적 사이트, 사전 렌더링된 페이지, 모바일 앱.
패턴 2: 런타임 Fetch
런타임에 API에서 번역을 가져옵니다. 재배포 없이 즉각적인 업데이트가 가능합니다.
적합한 대상: SPA, 동적 웹 앱, 실시간 콘텐츠.
패턴 3: 하이브리드
초기 로드를 위해 빌드 타임에 번역을 가져오고, 핫픽스를 위해 런타임에 업데이트를 가져옵니다.
적합한 대상: 성능과 유연성이 모두 필요한 프로덕션 앱.
자주 묻는 질문
API 우선 현지화를 사용하려면 파일 형식을 변경해야 합니까? 아니요. 대부분의 API 우선 TMS 플랫폼은 표준 형식(JSON, XLIFF, YAML, .strings, .xml)을 지원하며 형식 변환을 자동으로 처리합니다.
이름이 변경되거나 삭제된 번역 키는 어떻게 처리합니까? CLI scan 명령이 사용되지 않는 키를 감지합니다. API 엔드포인트는 키의 일괄 작업을 허용합니다. 대부분의 TMS 플랫폼은 키 수명 주기를 추적하고 고아 번역에 플래그를 지정합니다.
빌드 중 API가 다운되면 어떻게 됩니까? 캐시된 번역을 폴백으로 사용하십시오. API에 접근할 수 없는 경우에도 빌드에 항상 기준선이 있도록 마지막으로 성공한 pull을 버전 관리에 저장해 두십시오.
여러 환경의 번역은 어떻게 관리합니까? 프로젝트 수준 또는 브랜치 수준의 네임스페이싱을 사용하십시오. 일부 TMS 플랫폼은 동일한 프로젝트에 대해 환경별 재정의(스테이징, 프로덕션)를 지원합니다.
API 우선 현지화가 소규모 프로젝트에 적합합니까? 예. CLI push/pull 워크플로는 수백 개의 문자열을 가진 프로젝트에서도 수동 파일 관리보다 간단합니다. API 통합 설정의 오버헤드는 절약되는 시간에 비해 최소합니다.
