다국어 리소스 검증 자동화

서비스는 한국어, 중국어, 일본어, 영어 리소스를 각각의 JSON 파일로 관리하고 있었습니다. 새로운 기능을 추가하거나 기존 문구를 변경할 때 기준 언어에는 키를 추가했지만 다른 언어에는 동일한 키를 추가하지 않는 문제가 발생했습니다.

번역 키가 누락된 상태로 배포되면 사용자 화면에는 번역 문구 대신 product.detail.description과 같은 i18n 키가 그대로 표시됐습니다. 당시 운영 화면에서 63건이 발견됐으며, 사용자가 직접 화면에 진입하기 전까지 누락 여부를 알기 어려웠습니다.

언어별 JSON은 여러 단계로 중첩된 객체 구조를 사용했습니다. 파일 전체를 직접 비교하면 객체의 깊이와 키의 위치가 달라 누락된 항목을 빠르게 찾기 어려웠고, 언어와 키가 늘어날수록 수동 비교의 누락 가능성도 높아졌습니다.

각 언어의 파일을 열어 키를 검색하고 해당 언어로 화면을 실행하는 데 키 하나당 20~30초가 필요했습니다. 문제의 핵심은 번역 작업자의 실수 자체가 아니라 여러 언어가 동일한 키 구조를 유지하는지 검사하는 자동화된 기준이 없다는 점이었습니다.

한국어 리소스를 기준 데이터로 사용하고 다른 언어의 JSON이 동일한 키 경로를 갖는지 비교하는 TypeScript 검증 스크립트를 구현했습니다. 먼저 중첩된 JSON 객체를 product.detail.description처럼 점으로 연결된 키 경로로 평탄화했습니다.

평탄화한 키 집합을 언어별로 비교해 기준 언어에는 있지만 대상 언어에는 없는 키와 대상 언어에만 존재하는 불일치 키를 찾았습니다. 검증 결과에는 실패 여부뿐 아니라 누락이 발생한 언어와 전체 키 경로를 함께 출력해 개발자가 바로 수정 위치를 확인하도록 했습니다.

검증 스크립트를 구현한 뒤에도 개발자가 로컬에서 직접 실행해야 한다면 번역 누락을 완전히 방지할 수 없었습니다.

일정이 촉박하거나 번역과 관계없는 변경이라고 판단한 경우 검증 명령을 생략할 수 있었습니다. 스크립트가 존재하더라도 실행 여부가 개인의 작업 방식에 달려 있으면 누락된 리소스가 다시 배포될 가능성이 남았습니다.

로컬 검증은 개발자의 실수를 줄이는 보조 수단이지만 배포 조건으로 강제되지 않으면 팀 전체의 품질 기준이 되기 어려웠습니다.

기존 배포 과정에는 모든 언어의 리소스 키가 일치해야 한다는 조건이 없었습니다. 코드 빌드가 성공하면 번역 리소스가 누락돼도 배포가 계속 진행됐고, i18n 키 구조의 일치 여부가 빌드 성공 조건에 포함되지 않은 것이 문제의 반복 가능성을 남겼습니다.

TypeScript 검증 스크립트를 AWS CodePipeline의 pre_build 단계에 연결해 애플리케이션을 빌드하기 전에 모든 언어의 리소스 키를 비교하도록 변경했습니다.

누락 또는 불일치 키가 발견되면 스크립트가 실패 상태를 반환하고 CodePipeline이 이후 빌드와 배포를 중단하도록 구성했습니다. 오류 로그에는 문제가 발생한 언어와 전체 키 경로를 표시해 개발자가 CI 결과만 보고도 수정 위치를 확인할 수 있게 했습니다.