콘텐츠 요청 폼이 잘못된 언어로 나오던 버그 수정

k-pop 관련 콘텐츠 서비스를 운영하다 보니 다국어 지원이 필수다. 여러 지역 사용자들이 각각의 모국어나 영어로 접근하는데, 콘텐츠 요청 위젯이 특정 마켓(영어권)에서 올바른 언어로 렌더링되지 않는 버그를 발견했다. 사용자들이 제출한 피드백을 통해 문제를 특정할 수 있었고, 컴포넌트 레벨과 API 응답 레벨의 언어 설정이 동기화되지 않았던 게 원인이었다.

다국어 서비스에서 마주하는 미묘한 조정 문제

다국어 서비스는 "언어 지원"이라는 단순한 명제가 아니다. 언제 어디서 누가 어떤 언어를 선택하느냐에 따라 전혀 다른 UX가 된다. 우리 서비스는 사용자가 접속하는 지역(브라우저 로케일, 지리적 위치), 사용자의 언어 선택(세팅), 그리고 마켓 설정(특정 지역에서 제공되는 기본 언어)이 모두 달라질 수 있는 구조다.

콘텐츠 요청 위젯은 Astro 컴포넌트로 구현되어 있고, 사용자가 원하는 언어로 UI를 표시해야 한다. 동시에 API 엔드포인트(content-request.ts)에서도 요청을 받을 때 올바른 언어 컨텍스트를 유지해야 했다. 이 두 곳이 서로 다른 로직으로 언어를 결정하고 있었는데, 여기서 불일치가 발생했다.

문제의 근본: 마켓과 사용자 언어 선택의 혼재

이런 버그가 왜 테스트를 통과했을까? 개발 환경에서는 보통 한 가지 언어 설정으로만 확인하기 쉽다. 하지만 영어권 마켓에서 한국어 사용자가 접근하거나, 혹은 그 반대의 경우처럼 마켓 기본값과 사용자 선택이 다를 때만 드러나는 버그다. QA 단계에서도 "영어 마켓에서 영어로" 접근하는 시나리오에만 집중하면 놓치기 쉬운 부분이다.

수정 작업은 두 가지 원칙으로 정리했다:

• 컴포넌트 레벨: 마켓 기본값을 초기값으로 하되, 사용자가 선택한 언어를 명시적으로 전달받아 우선 처리
• API 레벨: 요청 헤더나 페이로드에서 명확하게 언어 정보를 읽고, 이를 데이터베이스에 저장할 때도 함께 기록

이렇게 하면 나중에 요청 데이터를 분석할 때도 "사용자가 어떤 언어로 입력했는지" 명확하게 추적할 수 있다.

배운 점: 현지화는 하나의 계층이 아니라 여러 계층의 합

비슷한 버그를 줄이기 위해 팀과 함께 다음을 정리했다:

1. 언어 설정의 명확한 출처 정의: 마켓 기본값? 사용자 선택? 브라우저 로케일? 각 레이어에서 언어를 결정하는 순서를 명시화하기
2. 크로스 마켓 테스트 케이스: QA에서 "마켓 A에서 언어 B로 접근"하는 조합들을 체크리스트화
3. API와 UI의 언어 일관성 테스트: 위젯에서 선택한 언어와 API 응답의 언어가 매칭되는지 자동화된 테스트로 검증

특히 마지막 항목은 회귀 버그를 방지하는 데 효과가 좋았다. 더 복잡해지는 마켓 구조(앞으로 더 많은 지역 확장 예정)에서 이런 기본기가 얼마나 중요한지 느껴진다.

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

• 노트북 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →

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