better-i18n 번역 품질 보증: 대규모 자동화 검사

번역의 일관성 유지하기

번역 품질은 단순히 단어를 올바르게 번역하는 것만이 아닙니다. 모든 키가 처리되고, 미사용 키가 정리되며, 용어가 모든 언어에서 일관되게 유지되도록 하는 것입니다. better-i18n은 프로젝트 전반에서 번역 품질을 유지하기 위해 함께 작동하는 여러 도구를 제공합니다.

CLI Scan: 하드코딩된 문자열 탐지

첫 번째 방어선은 scan 명령입니다. AST 분석을 사용하여 코드베이스를 파싱하고 번역되어야 하지만 번역 함수로 래핑되지 않은 문자열을 찾습니다.

better-i18n scan --dir ./src

스캐너는 다음을 탐지합니다:

• 하드코딩된 JSX 텍스트 (<h1>Hello</h1>)
• 하드코딩된 JSX 속성 (<img alt="Logo" />)
• Toast 및 알림 문자열
• 로케일 의존적 삼항 표현식
• 사용자 대면 텍스트를 포함하는 문자열 변수

CSS 클래스, URL, HTML 엔티티 및 기술적 상수를 무시할 만큼 충분히 스마트합니다. 따라서 결과는 실제 번역 누락에 집중되며, 오탐지가 없습니다.

--ci를 사용하여 빌드 파이프라인에 통합하고 새로운 하드코딩된 문자열을 도입하는 PR을 차단합니다:

npx @better-i18n/cli scan --ci

CLI Sync: 누락된 키와 미사용 키 찾기

sync 명령은 코드베이스의 번역 키 사용 현황을 better-i18n 클라우드에 존재하는 것과 비교합니다:

better-i18n sync

다음을 보여주는 명확한 리포트를 생성합니다:

• Remote에 누락: 코드에서 사용하지만 아직 better-i18n에 업로드되지 않은 키
• 코드에서 미사용: 소스 코드에서 더 이상 참조되지 않는 better-i18n의 키

이는 리팩토링 후에 매우 유용합니다. 어떤 키가 고아가 되어 정리할 수 있는지, 그리고 어떤 새로운 키가 배포 전에 번역이 필요한지 즉시 확인할 수 있습니다.

--summary 플래그는 빠른 상태 확인을 제공합니다:

better-i18n sync --summary

커버리지 비율(로컬 대 리포지토리, 리포지토리 사용)을 표시하여 번역 완성도를 한눈에 파악할 수 있습니다.

Glossary: 용어 일관성

Glossary는 모든 번역에서 일관된 용어를 적용합니다. Glossary에서 브랜드 용어, 제품명 또는 도메인별 어휘를 정의하면 AI 번역이 자동으로 해당 정의를 따릅니다.

이를 통해 동일한 개념이 앱 전체에서 다르게 번역되는 일반적인 문제를 방지합니다. 한 곳에서는 "Workspace", 다른 곳에서는 "작업 공간", 세 번째 곳에서는 "프로젝트 공간"과 같은 상황이 발생하지 않습니다.

대시보드 커버리지 가시성

better-i18n 대시보드는 언어별 및 네임스페이스별 번역 커버리지를 표시합니다. 한눈에 확인할 수 있습니다:

• 어떤 언어가 완전히 번역되었는지
• 어떤 네임스페이스에 공백이 있는지
• 프로젝트의 각 부분에 몇 개의 키가 있는지

이를 통해 프로덕트 매니저와 엔지니어링 리드는 CLI 명령을 실행하지 않고도 로컬라이제이션 상태를 명확하게 파악할 수 있습니다.

품질 게이트를 위한 CI 통합

CI 파이프라인에서 scan과 sync를 결합하여 번역 문제가 프로덕션에 도달하지 못하도록 하는 품질 게이트를 만듭니다:

name: i18n Quality
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @better-i18n/cli scan --ci
      - run: |
          npx @better-i18n/cli sync --format json \
            | jq -e '.comparison.missingCount == 0' > /dev/null || exit 1

pre-commit 훅의 경우, 빠른 피드백을 위해 스테이징된 파일만 스캔합니다:

npx @better-i18n/cli scan --staged --ci

아직 제공하지 않는 것

품질 도구의 현재 범위에 대해 명확히 하기 위해:

• 인라인 QA 엔진 없음 -- 에디터 내에서 플레이스홀더, HTML 태그 또는 ICU MessageFormat의 실시간 검증이 없습니다. CLI는 코드 수준에서 누락된 번역을 탐지합니다.
• 커스텀 규칙 시스템 없음 -- 현재 커스텀 검증 규칙(길이 제한이나 금지된 문자 등)을 정의할 수 없습니다.
• 플레이스홀더 검증 없음 -- 시스템은 소스의 {name}이 번역에 나타나는지 확인하지 않습니다.
• 비주얼 컨텍스트 없음 -- 품질 검사는 렌더링된 UI 스크린샷이 아닌 키/값 데이터에서 작동합니다.

이는 향후 개발을 위해 검토 중인 영역입니다.

시작하기

CLI를 설치하고 첫 번째 품질 검사를 실행합니다:

npm install -g @better-i18n/cli
better-i18n scan --dir ./src
better-i18n sync --summary

대시보드에서 Glossary 용어를 설정하여 AI 번역의 일관성을 강제하고, CLI를 CI 파이프라인에 통합하여 자동화된 품질 게이트를 구축하십시오.

계정을 만드세요로 프로젝트 전반의 번역 품질 관리를 시작하십시오.