688명 × 8개국어, 멤버 바이오 다국어 배선을 완성한 아침

오전 6시부터 정오까지의 작업 회고다. 이 시간대는 크게 두 갈래로 나뉘었다. 하나는 실제 사용자가 체감하는 버그 수정이고, 다른 하나는 그 버그를 파면서 드러난 데이터 규모를 정리하고 기록으로 남기는 작업이었다. 둘 다 결국 같은 맥락에서 출발했다. 멤버 페이지에서 비영어 언어를 선택해도 영어 바이오가 그대로 노출되는 문제였다.

문제의 발단 - 영어누수라 부르는 현상

처음에 이 버그를 인지한 건 멤버 바이오 다국어 데이터를 넣으면서였다. 데이터는 이미 DB에 들어가 있었다. 8개국어 분량이 다 있었다. 그런데 프론트에서 /ko/member/xxx 같은 경로로 들어가도 바이오 텍스트가 영어로 나왔다. 처음엔 데이터 누락인가 싶어 DB를 직접 확인했는데, 데이터는 멀쩡히 있었다.

문제는 getMemberBio 함수에 있었다. 이 함수는 db.ts에 정의되어 있고, 호출부는 MemberPage.astro였다. 함수 시그니처 자체는 로케일 파라미터를 받도록 되어 있었지만, 실제 쿼리 로직 안에서 로케일 값을 WHERE 조건에 제대로 바인딩하지 않거나, fallback 처리 과정에서 항상 en을 먼저 찍어버리는 구조였다. 즉 어떤 로케일로 요청해도 영어 행을 먼저 꺼내온 다음 거기서 멈추는 흐름이었다.

MemberPage.astro 쪽에서도 문제가 있었다. Astro의 Astro.currentLocale 이나 라우트 파라미터에서 추출한 로케일 값을 getMemberBio에 넘기는 코드가 빠져 있거나, 넘기더라도 함수 내부에서 무시되는 구조였다. 이 두 지점을 동시에 고쳐야 했다.

[Before]
getMemberBio(memberId) -> 항상 locale='en' 고정

[After]
getMemberBio(memberId, locale) -> DB 쿼리에 locale 바인딩
MemberPage.astro -> currentLocale을 getMemberBio에 전달

수정 자체는 크지 않았지만, 이걸 검증하려면 8개국어 데이터가 실제로 DB에 다 있어야 했다. 그래서 이 fix 커밋이 나오기 전에 데이터 현황을 먼저 파악해야 했다.

4816행짜리 다국어 바이오 데이터의 실체

멤버 바이오 다국어 지원이 "2번 완료"라고 커밋 메시지에 적은 건 마일스톤 기준으로 2단계가 끝났다는 의미다. 이 시간대에 완료된 규모를 정리하면 이렇다.

항목	수치
멤버 수	688명
지원 언어	8개국어
총 바이오 행 수	4,816행
문서화 대상	HANDOFF.md

688명이라는 숫자는 작지 않다. 한 멤버당 8개 언어 행이 있으면 단순 곱셈으로 5,504행이 되어야 하는데 4,816행인 건 일부 멤버에 대해 특정 언어 바이오가 아직 미입력인 경우가 있거나, 예외 처리 방식의 차이 때문일 수 있다. 정확한 이유는 커밋 메시지 외로 추가 정보가 없으므로 여기서 더 추측하지 않겠다.

이 규모의 데이터를 다루면서 가장 조심해야 했던 건 managed DB 연결이었다. 직접 운영하는 DB가 아니라 managed 서비스이기 때문에, 연결 풀 설정이나 트랜잭션 방식에서 일반 self-hosted DB와 다르게 동작하는 지점이 있다. 대량 삽입을 쪼개서 넣을 때 커넥션 타임아웃이 어떻게 잡히는지, 재시도 로직이 어디서 터지는지 등을 확인하면서 진행했다. 이 내용을 HANDOFF.md에 기록한 이유는 나중에 이 작업을 이어받는 사람이 같은 삽질을 반복하지 않게 하기 위해서다.

HANDOFF.md에 기록한 이유

팀 규모가 작거나 솔로로 운영하더라도, "나중의 나"를 위해 주요 작업 맥락을 문서로 남기는 습관은 중요하다. 이번에 HANDOFF.md에 담은 내용은 크게 세 가지였다.

멤버 바이오 다국어 배선 현황 (어느 페이지에서 어떤 함수를 통해 바이오를 가져오는지)
managed DB 연결 시 주의해야 할 사항 (커넥션 방식, 대량 작업 시 고려사항)
현재 완료 단계와 남은 작업에 대한 맥락

이 중에서 managed DB 연결 주의 기록이 제일 값지다. 이런 내용은 몇 달 지나면 직접 겪은 사람도 기억이 흐려진다. DB 연결 관련 이슈는 재현하기가 까다로운 경우가 많기 때문에, "이런 문제가 있었고 이렇게 처리했다"는 기록이 없으면 다음에 동일한 상황에서 처음부터 디버깅을 다시 해야 한다.

페이지 배선 기록도 마찬가지다. getMemberBio가 어디서 호출되는지, 어떤 파라미터를 받는지, 어떤 응답 구조를 돌려주는지를 코드 외부에서도 한눈에 볼 수 있도록 정리해두면, 나중에 다른 언어를 추가하거나 바이오 외 다른 다국어 필드를 추가할 때 같은 패턴을 참고할 수 있다.

이 아침 작업의 흐름을 되짚으면

6시에 시작할 때 목표는 단순했다. 멤버 바이오 다국어 데이터 2단계 마무리, 그리고 그 결과를 페이지에서 제대로 보여주는 것. 그런데 막상 시작하니 데이터는 있는데 화면에 영어만 나오는 상황이 발견됐고, 그걸 추적하다 보니 db.ts와 MemberPage.astro 양쪽에 걸친 배선 문제가 드러났다.

버그를 잡고 나서야 데이터 검증이 의미 있어졌다. 4,816행이 제대로 로케일별로 쿼리되는지 몇 개 언어를 직접 찍어보면서 확인했다. 그리고 이 과정에서 managed DB 연결 관련으로 주의해야 할 포인트들이 또 생겼고, 그걸 바로 HANDOFF.md에 옮겼다.

결과적으로 이 시간대는 버그 수정 하나, 데이터 규모 확인 및 마일스톤 완료, 그리고 문서화가 유기적으로 연결된 세트였다. 순서대로 계획한 게 아니라, 하나를 하다 보니 다음이 자연스럽게 이어졌다. 총괄 포지션에서 이런 작업을 할 때 흔히 겪는 패턴이기도 하다. 기술 부채를 발견하면 그냥 지나치지 않고 문서로 남기거나 바로 고치는 것. 나중에 큰 레버리지를 만들어주는 건 대부분 이런 작은 습관들이다.

오전 세션 마무리 시점에서 멤버 페이지 바이오는 8개국어 모두 정상 출력되는 상태고, 그 과정의 주의사항은 문서에 남겨놨다. 다음 세션에서 이 흐름을 이어받는 누구든 HANDOFF.md 한 장이면 컨텍스트를 복원할 수 있다.

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

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