i18n Doctor: 단일 명령어로 완벽한 번역 상태 보고서 확인하기
Run better-i18n doctor를 실행하여 코드 품질, 번역 적용 범위, 자리 표시자 정확도, 고아 키, CDN 동기화 등 다섯 가지 차원에서 전체 코드베이스를 분석하고 실행 가능한 진단 정보와 함께 0~100점의 단일 건강 점수를 확인하세요.
단일 패스 내의 다섯 가지 분석 계층
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)등급 기준점
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 상태를 확인할 수 있습니다.
어떤 명령어를 언제 사용해야 하는가
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에 추가하여 번역 누락을 다시는 배포하지 않도록 하세요.