다국어 품질 관리

다국어 품질 관리의 필요성

FE개발 시 다국어(i18n)는 기능 완성 이후에도 지속적으로 변하는 영역이기에, 키 누락이나 오타가 빌드 단계에서 감지되지 않을 수 있음

• 다국어 키가 번역 파일에 존재하지 않는 경우
• 키가 중복되거나 다국어간 구조가 일치하지 않는 경우
• 사용하지 않는 키가 파일에 누적되는 경우

그리하여 정적 분석 단계에서 사전에 차단하기 위해 다국어 리소스 검사 도구인 @lingual/i18n-check 라이브러리 리서치를 수행

@lingual/i18n-check를 선택한 배경에는 react-i18next 기반 JSON 리소스를 활용한 정적 분석틀 마땅히 없기 때문., 비교대상이 없다.

@lingual/i18n-check 프로젝트 적용 예시

설치 및 사용법

// 설치
pnpm add -D -w @lingual/i18n-check
// 패키지 스크립트에 추가
"i18n:generate-json": "npx tsx scripts/generate-locale-json.ts",
"i18n:check": "pnpm run i18n:generate-json && npx @lingual/i18n-check -l packages/shared/i18n/src/locales -s ko -f i18next -u apps/host/src"

옵션	값	설명
-l	packages/shared/i18n/src/locales	locale 디렉토리 경로 - JSON 변환 파일들이 있는 위치
-s	ko	source locale - 기준이 되는 언어 (ko 기준으로 en 비교)
-f	i18next	format - i18next 라이브러리 형식으로 파싱 (nested key 지원: log.columnIpAddress)
-u	apps/host/src	unused 검사 대상 소스 경로 - 이 경로의 코드를 분석해서 사용되지 않는 키와 정의되지 않는 키를 찾음

//검사 실행 및 검사 옵션의 범위
pnpm run i18n:check

검사 타입	설명
invalidKeys	타입 불일치, 형식 오류 등 잘못된 번역
missingKeys	source locale(ko)에는 있지만 다른 locale(en)에 없는 키
unused	locale에 정의됐지만 소스 코드에서 사용 안 하는 키
undefined	소스 코드에서 사용했지만 locale에 정의되지 않은 키

// 검사 결과

적용시 한계

검사를 수행했을 때 missingKeys, invalidKeys는 없었고 UnusedKey가 많이 나왔는데 그 이유로는 다국어를 문자열 템플릿등으로 동적으로 할당해주고 있기 때문

아래와 같이 동적으로 다국어코드를 사용하는 케이스는 --ignore 옵션으로 제거가 가능하지만 @lingual/i18n-check은 config 파일 없이 cli옵션으로만 전달 가능하기 때문에 번잡해질 수 있다.

현재 프로젝트에선 이미 다국어 품질 관리를 하고 있는데 i18nValidate.js를 실행하여 라이브러리 없이 직접 다국어 품질 검사를 진행중이며 이를 라이브러리를 통해 대체 가능할지 확인해보았다.

기존에는 커스텀하게 예외규칙을 지정하는일이 많아서 완벽하게 대체는 불가해보이며 사용을 한다면
"코드↔번역" 간 검증을 하는 과정에서 사용할 수 있을것으로 보임

검증 항목	i18nValidate.js (커스텀 함수)	@lingual/i18n-check (라이브러리)
언어 간 누락 검증 (ko에는 있는데 ja에 없음)	✅ 지원 • 4개 언어 Cross-Check	✅ 지원 • 4개 언어 Cross-Check
코드-번역 연동 검증 (t('KEY') ↔ 번역 파일)	❌ 미지원	✅ 지원 • Undefined: 코드에만 존재 • Unused: 번역에만 존재
커스텀 예외 규칙 (중복키 검증 외 여러 룰)	✅ 지원 • en: 34개 예외 • cn: 4개 예외 • 특수 처리 등	❌ 미지원
커스텀 리포트	✅ 지원 • 0: 에러사유 • 1: 파일:라인	⚠️ 기본 제공 영문 JSON 리포트

번역이 안된 채 텍스트로만 존재하는 코드를 검출해주는 기능은 따로 없어서 정규표현식과 함께 AI Agent를 활용하여 검출하는것이 효율적으로 보임

결론

• @lingual/i18n-check는 적용된 다국어(i18n)가 제대로 관리되고 있는지 검사하는 정적 분석 도구
• 언어 간 누락검증과 코드↔번역 간 검증이 가능하여 오타 혹은 누락된 키값을 확인할 수 있음
• 커스텀 예외 규칙을 설정하는데는 한계가 있기에 필요에 따라 i18nValidate와 같이 커스텀 함수 구현 필요
• 개발 완료 후 코드↔ 번역 간 연동검증에 사용하면 좋을것으로 보임