Retention 위젯 5곳의 한국어 텍스트 누수 버그 수정

이번에 다국어 환경에서 한국어 텍스트가 노출되는 버그를 발견하고 수정했다. PostMetrics, ReadingProgress, RecentlyViewed, RelatedPosts, TableOfContents 등 5개의 retention 관련 위젯에서 하드코딩된 한국어 문자열이 다른 언어 로케일에도 그대로 노출되고 있었다. 비록 작은 변경처럼 보이지만, 사용자 경험과 신뢰도에 직결되는 부분이고, 8개 모든 언어에 영향을 주는 광범위한 이슈였다.

왜 이런 일이 발생했나?

i18n(국제화) 처리는 개발자들이 가장 자주 놓치는 함정 중 하나다. 특히 한국 팀이 개발할 때 로컬 환경에서는 당연히 한국어로 작업하다 보니, 일부 텍스트를 i18n 함수로 감싸지 않고 하드코딩하게 된다. UI 완성도가 높아 보이는 단계에서는 한국어로만 테스트하므로 이 문제가 드러나지 않다가, 실제 배포나 다른 언어 테스트 시점에 발각되는 식이다.

이번 경우도 비슷했을 것으로 추측된다. Retention 관련 위젯들이 동시에 개발·수정되는 과정에서 여러 컴포넌트가 일관되지 않은 방식으로 i18n 처리되었거나, 새로 추가된 텍스트들이 번역 체크리스트를 빠져나갔을 가능성이 높다. 한두 개 파일이 아니라 6개 파일에서 동시에 발생했다는 것은, 이 변경들이 같은 시간대에 병렬로 진행되다가 리뷰를 통과한 것으로 보인다.

수정 범위와 영향

이들은 모두 사용자의 "재방문" 및 "더 오래 머물게 하기" 관련 기능들이다. 즉, engagement와 retention을 직접 담당하는 부분이다. 이런 곳에서 언어가 맞지 않으면 사용자는 곧바로 서비스에 불신을 느끼게 된다. "내가 스페인어로 설정했는데 왜 한국어가 튀어나와?" 하는 경험은 비록 2-3개 단어일지라도 사용 중단으로 이어질 수 있다.

i18n 처리의 일반적 패턴

보통 이런 수정은 다음과 같은 형태다:

// ❌ 하드코딩 (문제)
<div class="metrics">
  <span>읽음 진행도</span>
  <span>{readProgress}%</span>
</div>

// ✅ i18n 처리 (올바름)
<div class="metrics">
  <span>{t('components.readingProgress.label')}</span>
  <span>{readProgress}%</span>
</div>

각 로케일별 번역 파일(en.json, es.json, ko.json 등)에 매핑된 키를 사용하면, 사용자의 언어 설정에 따라 자동으로 올바른 텍스트가 로드된다.

회고: 팀 차원의 예방책

이런 실수가 반복되지 않으려면, 개발 단계에서 체계적인 접근이 필요하다.

코드 리뷰 체크리스트
- 새로운 텍스트/라벨 추가 시 반드시 i18n 키로 처리했는지 확인
- 하드코딩된 한글을 감지할 수 있도록 정규식 패턴 활용

테스트 환경의 다국어 기본 설정
- 기본 로케일을 한국어 이외의 언어로 설정해서 개발
- 또는 CI/CD에서 자동으로 모든 로케일로 스냅샷 테스트 실행

자동화
- ESLint 플러그인이나 커스텀 린터로 하드코딩된 한글 문자열 감지
- 빌드 시점에 번역 파일의 키-값 쌍이 모든 로케일에서 일치하는지 검증

이번 수정으로 버그 자체는 닫혔지만, 진짜 배워야 할 점은 왜 6개 파일이 동시에 같은 실수를 했는가 하는 것이다. 다음 sprint부터는 이 체크리스트를 코드 리뷰 가이드에 공식화하고, 가능하다면 린터 규칙도 추가해 개발 단계에서 먼저 막을 계획이다.

🛒 이 글과 어울리는 추천 상품

• 기계식키보드 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 스탠딩데스크 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.