Kord/Docs/WorkDone/2026-03-27_i18n_Check_Tool_Implementation.md

2026-03-27: i18n 테스트 코드 검사 도구 구현 (i18n Check Tool Implementation)

테스트 코드 내에서 i18n 번역 키를 참조하지 않고 실제 번역된 문자열을 하드코딩하여 검증하는 부분을 자동으로 탐지하는 도구를 구현했습니다.

배경 및 목적

• i18n 시스템 도입 후, 테스트 코드에서 번역된 결과값을 직접 비교(expect().toBe('문자열'))하는 사례가 발견되었습니다.
• 번역 파일(ko.ts, en.ts)의 내용이 변경될 때 테스트 코드가 함께 깨지는 것을 방지하고, i18n 참조(t() 함수 사용)를 강제하기 위함입니다.

주요 구현 사항

1. 검사 스크립트 작성 (scripts/check-i18n-tests.ts)

• 로직: src/i18n/locales/의 번역 데이터를 로드하여 값 -> 키 맵을 생성한 뒤, tests/ 디렉토리 내의 모든 .ts 파일을 스캔하여 일치하는 하드코딩된 문자열을 찾습니다.
• 예외 처리:
  • i18n 키 자체(점. 포함 문자열)는 무시합니다.
  • t() 함수의 인자로 사용되는 경우(키 참조)는 무시합니다.
  • // i18n-ignore 주석이 있는 라인은 검사에서 제외합니다.

2. 실행 명령어 추가 (package.json)

• npm run check-i18n (또는 yarn check-i18n) 명령어를 통해 언제든지 검사를 실행할 수 있습니다.

작업 결과

• 현재 프로젝트 내에서 10개의 위반 사례를 성공적으로 탐지했습니다.
• i18n.test.ts 등 의도적으로 하드코딩이 필요한 부분에는 // i18n-ignore를 적용하여 예외 처리를 완료했습니다.

향후 계획

• CI/CD 파이프라인에 해당 검사 단계를 추가하여 코드 품질을 유지할 예정입니다.