i18n Doctor: 단일 명령어로 완벽한 번역 상태 보고서 확인하기
Run better-i18n doctor를 실행하여 코드 품질, 번역 적용 범위, 자리 표시자 정확도, 고아 키, CDN 동기화 등 다섯 가지 차원에서 전체 코드베이스를 분석하고 실행 가능한 진단 정보와 함께 0~100점의 단일 건강 점수를 확인하세요.
$ better-i18n doctor
better-i18n · 국제화 진단 보고서
████████████████░░░░ 82 / 100 A
PASSED (threshold: 70)
Coverage 95 (3 issues)
Quality 88 (2 issues)
Code 72 (8 issues)
Structure 100 (clean)
Performance 91 (1 issue)분석
단일 패스 내의 다섯 가지 분석 계층
Doctor는 코드 스캐닝, 커버리지 분석, 품질 검증, 성능 감사, CDN 동기화 점검을 — 통합 점수와 함께 — 동시에 수행합니다.
코드 — 하드코딩된 문자열 탐지
AST 기반 스캔은 t()로 감싸지 않은 모든 사용자 노출 문자열을 찾아냅니다. JSX 텍스트, 속성, 삼항 로케일 로직, 토스트 메시지 및 문자열 변수를 포착합니다.
커버리지 — 누락된 번역
소스 로케일에 존재하는 키를 각 대상 로케일과 비교합니다. 대상 로케일에서 누락된 키는 정확한 네임스페이스와 경로와 함께 보고됩니다.
품질 — 자리 표시자 불일치
모든 로케일에서 보간 자리 표시자가 일관되게 사용되는지 확인합니다. 이름 지정된 {}, 이중 중괄호 {{}}, printf%s, 템플릿 ${}, 위치 지정자 {0} 형식을 지원합니다.
성능 — 고아 키 감지
번역 파일에 존재하지만 코드에서 참조되지 않는 키를 감지합니다. 고아 키는 페이로드 크기를 증가시키고 유지보수 부채를 발생시킵니다.
싱크 — CDN 비교
코드에서 추출한 키를 CDN에 게시된 키와 비교합니다. 원격에서 누락된 키 및 사용되지 않은 원격 키 문제를 프로덕션 환경에 영향을 미치기 전에 노출합니다.
점수 산정
번역 건강을 위한 단일 점수
의사는 진단 결과를 바탕으로 0에서 100 사이의 점수를 산출합니다. 오류는 각각 3.0점씩 감점되며, 각 규칙의 경고 기여도는 20점으로 제한됩니다. 이는 수천 개의 경고를 포함하는 단일 규칙이 전체 점수를 0으로 만들지 않도록 방지합니다.
기본 합격 기준은 70점(B등급)입니다. 이 기준 미만의 빌드를 실패로 처리하려면 --ci 옵션을 사용하거나, 점수 적용 전에 기준선을 설정하려면 --report로 시작하십시오.
점수 공식
score = 100 - (errors × 3.0) - Σ min(rule_warnings × 0.15, 20)등급 기준점
- A+
- ≥ 90
- A
- ≥ 80
- B
- ≥ 70
- C
- ≥ 50
- F
- < 50
지속적 통합
CI/CD 통합 — 출시 전에 잘못된 번역 차단하기
CI 파이프라인에 Doctor를 추가하여 매번 푸시 시 번역 회귀 현상을 포착하세요. GitHub Actions의 자동 OIDC 인증으로 비밀 관리가 필요 없습니다.
GitHub Actions와 OIDC
GitHub Actions OIDC를 사용하여 API 키 없이 자동 인증하세요. id-token: write 권한만 추가하고 doctor --ci --report를 실행하면 됩니다.
역치 게팅
합격 점수 기준(기본값: 70)을 설정하고 점수가 이 기준 미만으로 떨어지면 빌드를 실패 처리합니다. --report 옵션으로 추적을 시작한 후 --ci 옵션으로 적용합니다.
기계가 읽을 수 있는 JSON
구조화된 출력을 위해 --format json 옵션을 사용하면 jq 파이프라인, 사용자 정의 대시보드 또는 배포 파이프라인의 다운스트림 자동화로 연결할 수 있습니다.
대시보드 보고
--report 옵션을 사용하여 결과를 Better I18N 대시보드에 업로드하면 이력 추적, 추세 분석 및 팀 전체가 i18n 상태를 확인할 수 있습니다.
# GitHub Actions example
- run: npx @better-i18n/cli doctor --ci --report명령어
어떤 명령어를 언제 사용해야 하는가
Doctor는 포괄적인 옵션입니다. 특정 검사가 필요하거나 커밋 전 훅에서 더 빠른 피드백을 원할 때는 집중된 명령어를 사용하세요.
의사5단계 분석 레이어로 구성된 완벽한 건강 점수 — 프로젝트의 국제화 상태를 파악하는 유일한 신뢰할 수 있는 정보원입니다.
스캔집중된 하드코딩된 문자열 탐지. 커밋 전 훅을 위한 --staged 지원.
확인누락되거나 사용되지 않은 번역 키를 위한 대화형 검사기(가이드 프롬프트 포함)
동기화로컬과 원격 간 전체 비교로 누락된 키와 사용되지 않은 키를 동시에 표시합니다.
기능
실제 국제화 워크플로우를 위해 설계됨
건강 점수 0–100
단일 점수와 범주별 세부 분석, CI 통과/불합격 기준. 시간 경과에 따른 번역 품질 추이를 추적하세요.
어휘적 범위 추적
useTranslations 및 getTranslations 모두에 대한 스마트 네임스페이스 감지. 모든 t() 호출은 올바른 네임스페이스로 매핑됩니다.
서버 구성 요소 지원
Next.js App Router의 비동기 서버 함수에 대한 완전한 지원. 서버 측 getTranslations 호출이 감지 및 감사됩니다.
구성 가능한 규칙
i18n.config.ts 파일에서 규칙을 비활성화하거나 등급을 낮추세요. 프로젝트 요구사항에 맞게 규칙을 "error", "warning" 또는 "off"로 설정하세요.
스마트 필터링
CSS 클래스 이름, URL, 임포트 경로 및 개발자 상수는 자동으로 무시합니다. 실행 가능한 결과만 표시됩니다.
상세 감사 로그
--verbose 옵션으로 심층적인 투명성 제공. 디버깅을 위한 범위 요약, 타이밍 정보 및 네임스페이스 해결 추적 기록.
관련 주제
번역 품질을 확인한 후 발송하세요
Run better-i18n doctor를 한 번 실행하여 기준점을 설정하세요. CI에 추가하여 번역 누락을 다시는 배포하지 않도록 하세요.