목차
Translation Automation: CI/CD와 Webhooks로 로컬라이제이션을 간소화합니다
핵심 내용
- Translation Automation은 개발자와 번역가 사이의 수동 파일 전달을 없애고 로컬라이제이션 사이클 시간을 단축합니다
- CI/CD 통합을 통해 새로운 문자열이 자동으로 추출, 번역, 병합되는 지속적인 로컬라이제이션이 가능합니다
- Webhooks를 통해 번역이 완료될 때 TMS 플랫폼이 작업(빌드, 알림, 배포)을 트리거할 수 있습니다
- 자동화를 통해 번역되지 않은 콘텐츠나 오래된 번역이 출시될 위험을 줄입니다
- 잘 자동화된 워크플로우는 로컬라이제이션 턴어라운드를 수 주에서 수 시간으로 단축할 수 있습니다
Auto Translation이란 무엇입니까?
핵심적으로, auto translation은 콘텐츠가 최소한의 인간 개입으로 소스 언어에서 대상 언어로 이동할 수 있도록 번역 워크플로우에서 수동 단계를 제거하는 실천입니다. 이 용어는 광범위한 스펙트럼을 포함합니다 — Google Translate에 대한 단순한 API 호출부터, 코드베이스에서 새로운 문자열을 감지하고, 컨텍스트를 인식하는 AI로 번역하고, 인간 검토를 통해 라우팅하고, 승인된 번역을 풀 리퀘스트로 리포지토리에 다시 병합하는 완전히 오케스트레이션된 파이프라인까지.
Automatic translation이 중요한 이유는 현대 소프트웨어 팀이 지속적으로 배포하기 때문입니다. 번역 프로세스에 수동 파일 내보내기, 이메일 조정, 수동 가져오기가 필요하다면 모든 국제 릴리즈를 지연시키는 병목 지점이 됩니다. Auto Translation은 그 병목을 제거합니다.
Automatic translation에는 세 가지 성숙도 수준이 있습니다:
- 기본 auto translation: 개발자가 MT API(DeepL, Google Translate, Azure Translator)를 호출하여 파일을 번역한 다음 출력을 수동으로 통합합니다. 일회성 작업에는 빠르지만 확장되지 않습니다.
- 반자동 번역: TMS가 리포지토리 또는 CMS의 변경 사항을 감시하고, translation memory와 machine translation을 자동으로 적용한 다음 인간 검토자에게 알립니다. 파이프라인의 대부분은 개입 없이 실행되지만 인간이 게시 전에 승인합니다.
- 완전 자동화된 번역 파이프라인: 병합 시 문자열 변경이 감지되고, AI로 번역되고, quality gates(플레이스홀더 검사, 길이 검증, 완전성 임계값)로 검증되고, 모든 검사가 통과하면 자동으로 다시 병합되는 CI/CD 통합 워크플로우. 인간 검토는 필요로 하는 콘텐츠 유형(마케팅 카피, 법적 텍스트)을 위해 예약됩니다.
이 가이드의 나머지 부분은 레벨 2와 3에 초점을 맞춥니다 — automatic translation을 일회성 단축키가 아닌 개발 워크플로우의 지속 가능한 부분으로 만드는 CI/CD 및 webhook 기반 접근 방식입니다.
왜 번역을 자동화해야 합니까?
수동 로컬라이제이션 워크플로우에서 개발자는 번역 파일을 추출하고, 번역가에게 이메일로 보내거나 TMS에 업로드하고, 번역을 기다리고, 완성된 파일을 다운로드하고, 코드베이스에 다시 병합합니다. 각 전달은 지연과 오류의 기회를 도입합니다.
Translation Automation은 소스 코드 리포지토리를 번역 관리 시스템에 직접 연결함으로써 이러한 전달을 제거합니다. 개발자가 변경 사항을 커밋하면 새로운 또는 수정된 문자열이 자동으로 감지되어 번역을 위해 전송됩니다. 번역가가 작업을 완료하면 번역이 자동으로 동기화됩니다.
자동화된 로컬라이제이션 파이프라인
일반적인 자동화 파이프라인은 이 흐름을 따릅니다:
개발자가 코드를 커밋
↓
CI/CD가 변경된 번역 파일을 감지
↓
TMS CLI가 새로운/변경된 문자열을 TMS에 푸시
↓
TMS가 translation memory 적용(즉시 매치)
↓
매치되지 않은 문자열 → MT 사전 번역 또는 인간 할당
↓
번역가가 TMS에서 번역 완료
↓
Webhook 트리거: "translations completed"
↓
CI/CD가 완성된 번역을 리포지토리로 가져옴
↓
새 번역과 함께 PR 생성
↓
검토, 병합, 배포
CI/CD 통합 패턴
GitHub Actions 예시
대부분의 TMS 플랫폼은 CI/CD 파이프라인에서 사용할 수 있는 CLI 도구를 제공합니다:
# .github/workflows/sync-translations.yml
name: Sync Translations
on:
push:
branches: [main]
paths:
- 'src/locales/en/**'
jobs:
push-sources:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Push source strings to TMS
run: |
npx @better-i18n/cli push \
--project your-org/your-project \
--source src/locales/en
env:
BETTER_I18N_TOKEN: ${{ secrets.BETTER_I18N_TOKEN }}
일정에 따라 번역 가져오기
# .github/workflows/pull-translations.yml
name: Pull Translations
on:
schedule:
- cron: '0 */6 * * *' # 6시간마다
workflow_dispatch: # 수동 트리거
jobs:
pull-translations:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Pull completed translations
run: |
npx @better-i18n/cli pull \
--project your-org/your-project \
--target src/locales
env:
BETTER_I18N_TOKEN: ${{ secrets.BETTER_I18N_TOKEN }}
- name: Create PR if translations changed
uses: peter-evans/create-pull-request@v6
with:
title: 'chore(i18n): update translations'
commit-message: 'chore(i18n): pull latest translations from TMS'
branch: i18n/update-translations
GitLab CI/CD
# .gitlab-ci.yml
push-sources:
stage: sync
only:
changes:
- src/locales/en/**
script:
- npx @better-i18n/cli push --project $PROJECT_ID --source src/locales/en
Webhook 기반 워크플로우
Webhooks를 통해 TMS는 이벤트 발생 시 시스템에 알릴 수 있습니다 — 번역 완료, 검토 승인 또는 새로운 문자열 감지.
일반적인 Webhook 이벤트
| 이벤트 | 트리거 | 일반적인 작업 |
|---|---|---|
translation.completed | 언어의 모든 문자열이 번역됨 | 번역 가져오기, PR 생성 |
translation.reviewed | 번역이 검토 통과 | 스테이징에 배포 |
source.updated | 새로운 소스 문자열 감지됨 | 번역가에게 알림 |
project.exported | 번역 내보내기 준비 완료 | 다운로드 및 병합 |
Webhook 핸들러 예시
// Express.js webhook 핸들러
app.post('/webhooks/translations', (req, res) => {
const { event, language, project } = req.body;
if (event === 'translation.completed') {
// API를 통해 GitHub Actions 워크플로우 트리거
triggerWorkflow('pull-translations', {
language,
project,
});
}
res.status(200).json({ received: true });
});
파일 형식 고려 사항
다른 파일 형식은 자동화 작동 방식에 영향을 미칩니다:
| 형식 | 강점 | 일반적으로 사용되는 곳 |
|---|---|---|
| JSON (플랫/중첩) | 파싱이 쉽고, 널리 지원됨 | React, Vue, Angular |
| XLIFF | 업계 표준, 메타데이터 보존 | 엔터프라이즈 도구 |
| PO/POT | 성숙한 도구, 번역가 친화적 | Django, Rails, PHP |
| RESX | .NET 네이티브 형식 | C#, .NET 프로젝트 |
| ARB | Flutter/Dart 표준 | Flutter 앱 |
| Strings/Stringsdict | iOS 네이티브 형식 | iOS/macOS 앱 |
| XML | Android 네이티브 형식 | Android 앱 |
자동화 파이프라인은 코드베이스에서 사용하는 특정 형식을 처리해야 합니다. 대부분의 TMS CLI 도구는 모든 일반적인 형식을 지원합니다.
문자열 추출 자동화
별도의 번역 파일을 사용하지 않는 프로젝트의 경우, 자동화된 문자열 추출이 소스 코드에서 번역 가능한 문자열을 식별합니다:
정적 분석
도구가 번역 함수 호출에 대한 소스 코드를 스캔합니다:
// 이 패턴들은 추출 도구에 의해 감지됩니다:
t('home.title')
useTranslations('common')
formatMessage({ id: 'greeting' })
추출 구성
{
"extract": {
"patterns": ["src/**/*.{tsx,ts}"],
"functions": ["t", "useTranslations", "formatMessage"],
"output": "src/locales/en/messages.json"
}
}
pre-commit 훅 또는 CI 단계로 추출 명령을 실행하면 새로운 번역 가능한 문자열이 항상 캡처됩니다.
자동화 파이프라인의 Quality Gates
자동화에는 깨진 번역이 프로덕션에 도달하는 것을 방지하기 위한 품질 검사가 포함되어야 합니다:
- 플레이스홀더 검증: 소스 문자열의 모든 플레이스홀더(
{name},{count})가 번역에 존재하는지 확인 - 길이 검증: 소스 문자열 길이를 크게 초과하는 번역에 플래그 지정(UI 오버플로우 발생 가능)
- 완전성 검사: 배포 전에 모든 필수 언어가 최소 번역 비율을 충족하는지 확인
- 형식 검증: 번역 파일이 유효한 JSON/XLIFF/PO인지 확인(구문 오류 없음)
# CI의 Quality gate
- name: Validate translations
run: |
npx @better-i18n/cli validate \
--source src/locales/en \
--target src/locales \
--min-coverage 95
일반적인 함정
- 과도한 동기화: 모든 커밋에서 번역을 가져오면 노이즈가 많은 PR이 생성됩니다. 대신 예약된 또는 webhook 트리거 가져오기를 사용하세요.
- 컨텍스트 누락: 자동화된 추출은 문자열을 캡처하지만 스크린샷이나 설명은 캡처하지 않습니다. 댓글이나 TMS 기능을 통해 컨텍스트를 제공하세요.
- 브랜치 충돌: 번역 PR이 기능 브랜치와 충돌할 수 있습니다. 충돌을 최소화하기 위해 번역 업데이트를 자주 병합하세요.
- 시크릿 관리: TMS API 토큰은 리포지토리에 커밋하지 않고 CI/CD 시크릿에 안전하게 저장해야 합니다.
- Rate Limiting: TMS 플랫폼에 대한 API 호출은 rate limiting될 수 있습니다. 자동화 스크립트에서 백오프 및 재시도 로직을 구현하세요.
FAQ
번역을 얼마나 자주 동기화해야 합니까?
main(또는 기본 브랜치)에 병합할 때마다 소스 문자열을 푸시하세요. 번역은 일정(4-6시간마다)에 따라 또는 번역이 완료될 때 webhook을 통해 가져오세요. 기능 브랜치에 모든 커밋에서 동기화하는 것을 피하세요 — 불필요한 노이즈가 생성됩니다.
번역 PR을 자동 병합해야 합니까?
quality gates(플레이스홀더 검증, 형식 검사)가 있는 잘 확립된 워크플로우의 경우, 번역 PR 자동 병합은 안전할 수 있습니다. 새로운 설정의 경우, 품질 검사에 자신감이 생길 때까지 수동 검토를 요구하세요. 많은 팀이 중요하지 않은 언어에 대해 자동 병합하고 주요 시장에 대해서는 검토를 요구합니다.
번역이 빌드를 중단시키면 어떻게 합니까?
병합 전에 번역 파일을 검증하는 CI 검사를 추가하세요. 번역 파일에 유효하지 않은 구문, 누락된 플레이스홀더 또는 기타 문제가 있으면 PR이 CI에서 실패하고 병합되지 않아야 합니다. 이렇게 하면 깨진 번역이 프로덕션에 도달하는 것을 방지합니다.
Auto Translation이 프로덕션에 충분히 좋습니까?
Auto Translation — 즉, 인간 검토 없이 완전히 자동화된 machine translation — 은 내부 도구, 개발자 문서, 속도가 완성도보다 중요한 저위험 콘텐츠에 적합합니다. 사용자 대면 제품 UI, 마케팅 카피, 법적 콘텐츠의 경우 auto translation은 인간 검토를 포함하는 파이프라인에서 첫 번째 초안으로 제공되어야 합니다. CI/CD 컨텍스트에서 automatic translation의 목표는 인간을 제거하는 것이 아니라 인간을 느리게 만드는 수동 조정을 제거하는 것입니다.
