Skip to main content

CI 번역 검증: 파이프라인에서 i18n 검사 자동화

번역 버그는 코드 검토에서 보이지 않아요. 누락된 키, 손상된 플레이스홀더, 잘못된 복수형은 어느 것도 코드 diff에 나타나지 않아요. CI 수준 검증으로 프로덕션에 도달하기 전에 찾아내세요.

1

번역 버그가 코드 검토를 빠져나가는 이유

개발자가 en.json에 새 키 10개를 추가하고 기능 코드를 업데이트해요. PR 검토자는 코드와 영어 문자열을 확인한 뒤 승인해요. 나머지 로케일 파일 14개는 아무도 비교하지 않아요. 그러면 세 가지 버그가 프로덕션에 배포돼요. de.json에는 키 2개가 없어 독일어 사용자에게 원시 키 경로가 보이고, fr.json에는 {count} 플레이스홀더가 손상되어 프랑스어 사용자에게 리터럴 {count}가 보이며, ja.json에는 잘못된 ICU 복수형이 있어 일본어 사용자는 앱이 중단되는 문제를 겪어요. 30초 CI 검사로 모두 예방할 수 있어요.

번역 버그에는 독특한 특징이 있어요. 개발자와 검토자에게는 보이지 않고 특정 로케일 사용자에게만 보여요. 프로덕션 전에 확실하게 찾아내는 유일한 방법은 CI 검증이에요.
2

i18n-validate 설치

i18n-validate를 개발 종속성으로 프로젝트에 추가하세요. JSON, YAML, PO, XLIFF, ARB 형식을 바로 지원하며 기본 사용에는 설정이 필요하지 않아요.

Terminal
npm install --save-dev @anthropic/i18n-validate
3

GitHub Actions 통합

풀 리퀘스트 작업 흐름에 i18n-validate 단계를 추가하세요. 오류를 찾으면 도구가 종료 코드 1을 반환해 PR 검사가 실패해요. JUnit XML 출력과 테스트 리포터 액션을 사용하면 PR diff에 인라인 주석을 바로 표시할 수 있어요.

.github/workflows/i18n-validate.yml
# .github/workflows/i18n-validate.yml
name: Validate Translations

on:
  pull_request:
    paths:
      - 'src/locales/**'
      - 'public/locales/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Validate translation files
        run: npx i18n-validate \
          --source src/locales/en.json \
          --targets 'src/locales/*.json' \
          --check-missing \
          --check-unused \
          --check-placeholders \
          --check-plurals \
          --min-coverage 95 \
          --junit-output reports/i18n.xml

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: i18n-validation-report
          path: reports/i18n.xml
새 검증 규칙으로 예기치 않게 작업이 중단되지 않도록 작업 흐름에서 i18n-validate 버전을 고정하세요. @latest는 개발 환경에서만 사용하세요.
4

GitLab CI 통합

.gitlab-ci.yml 파이프라인에 번역 검증 작업을 추가하세요. GitLab은 JUnit XML 아티팩트를 기본으로 지원해요. 검증 보고서를 업로드하면 오류가 병합 요청의 Test 탭에 나타나요.

.gitlab-ci.yml
# .gitlab-ci.yml
i18n-validate:
  stage: test
  image: node:20
  script:
    - npm ci
    - npx i18n-validate \
        --source src/locales/en.json \
        --targets 'src/locales/*.json' \
        --check-missing \
        --check-unused \
        --check-placeholders \
        --min-coverage 95 \
        --junit-output reports/i18n.xml
  artifacts:
    reports:
      junit: reports/i18n.xml
  only:
    changes:
      - src/locales/**/*
5

pre-commit 훅

더 빠른 피드백을 위해 검증을 pre-commit 훅으로 실행하세요. CI에 도달하기 전에 문제를 찾아 파이프라인 시간을 절약하고 피드백 주기를 줄여요. 훅 관리에는 Husky(JS) 또는 pre-commit(Python)을 사용하세요.

.husky/pre-commit
# .husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

# Only validate if translation files changed
CHANGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '(locales|i18n|translations)/')

if [ -n "$CHANGED_FILES" ]; then
  echo "Translation files changed, validating..."
  npx i18n-validate \
    --source src/locales/en.json \
    --targets 'src/locales/*.json' \
    --check-missing \
    --check-placeholders
fi
pre-commit 훅은 커밋마다 실행되므로 빠르게 유지하세요. 모든 로케일이 아니라 --locales 플래그로 현재 커밋에서 변경된 로케일만 검증하세요. 대부분의 프로젝트에서 훅 실행 시간을 2초 미만으로 유지할 수 있어요.
6

설정 및 심각도 수준

.i18n-validate.toml 설정 파일로 검증 동작을 맞춤 설정하세요. 규칙별 검사 심각도(error, warning, off)를 설정하고 예상 언어를 정의하며 작업 중인 로케일을 제외하고 출력 형식을 구성할 수 있어요. CI에서는 error만 파이프라인 실패로 처리되고 warning은 보고서에 표시되지만 차단하지 않아요.

i18n-validate.config.json
// i18n-validate.config.json
{
  "source": "src/locales/en.json",
  "targets": "src/locales/*.json",
  "checks": {
    "missing": true,         // Keys in source missing from target
    "unused": true,          // Keys in target not in source
    "placeholders": true,    // Mismatched {variables}
    "plurals": true,         // Missing CLDR plural forms
    "icu": true,             // ICU syntax validation
    "emptyValues": true,     // Empty string values
    "duplicateValues": false // Same value as source (untranslated)
  },
  "minCoverage": 95,
  "exclude": [
    "src/locales/pseudo.json"
  ],
  "junitOutput": "reports/i18n.xml",
  "format": "json"          // json | yaml | po | xliff
}

지금 i18n Agent 사용해 보기

번역 파일을 여기에 드롭

JSON, YAML, PO, XML, CSV, Markdown, Properties

또는 클릭하여 파일 선택

대상 언어

가입 불필요즉시 견적

CI 번역 검증 FAQ