다국어 프로젝트의 함정: Next.js i18n 레이아웃 버그 해결기

안녕하세요! 오늘은 hafuture 서비스 개발 과정에서 겪은 흥미로운(그리고 조금은 당혹스러웠던) 기술적 트러블슈팅 사례를 공유하고자 합니다. 주제는 바로 **'다국어 환경에서의 레이아웃 컴포넌트 동기화'**입니다.

문제의 발견: "내용은 한국어인데 메뉴는 왜 영어지?"

hafuture는 글로벌 사용자를 대상으로 텍스트 처리, PDF 편집, 각종 계산기 등 다양한 유틸리티 도구를 제공하는 플랫폼입니다. 따라서 한국어, 영어, 일본어를 완벽하게 지원하는 것이 무엇보다 중요했습니다.

저희는 next-intl 라이브러리를 사용해 다국어를 구현했는데, 어느 날 블로그 페이지를 테스트하던 중 이상한 점을 발견했습니다. /ko/blog 경로로 접속했을 때 블로그 포스트의 본문과 제목은 한국어로 잘 나오는데, 상단의 헤더(Header) 메뉴와 하단의 **푸터(Footer)**는 여전히 영어로 표시되고 있었습니다.

심지어 지구본 모양의 언어 전환기를 통해 언어를 바꿔도 URL만 바뀔 뿐, 공통 레이아웃 요소들은 요지부동이었습니다. 마치 레이아웃만 다른 시간대에 살고 있는 듯한 느낌이었죠.

원인 분석: 클라이언트 사이드 프로바이더의 부재

원인은 크게 두 가지였습니다.

NextIntlClientProvider의 로케일 누락: layout.tsx에서 모든 메시지를 불러와 제공하고 있었지만, NextIntlClientProvider에 현재 어떤 언어(locale)를 사용해야 하는지 명시적으로 알려주지 않았습니다. 이로 인해 브라우저에서 동작하는 클라이언트 컴포넌트들(Header, Footer 등)은 기본 설정인 영어로 고정되어 버린 것이었습니다.
메시지 로딩의 불확실성: 서버 컴포넌트에서 getMessages()를 호출할 때 인자를 생략하면, 현재 요청의 컨텍스트를 정확히 파악하지 못해 기본 언어의 메시지를 반환할 위험이 있었습니다.

해결 과정: 명시적인 로케일 주입

문제를 해결하기 위해 다음과 같은 단계로 코드를 수정했습니다.

1. Root Layout 수정

가장 먼저 RootLayout에서 현재 URL의 locale 정보를 NextIntlClientProvider에 직접 전달하도록 변경했습니다. 이렇게 하면 하위의 모든 클라이언트 컴포넌트가 동일한 언어 컨텍스트를 공유하게 됩니다.

// src/app/[locale]/layout.tsx
<NextIntlClientProvider locale={locale} messages={messages}>
  <Header />
  {children}
  <Footer />
</NextIntlClientProvider>

컴포넌트의 타입(Server/Client)에 따른 i18n 전략: 서버 컴포넌트는 요청 컨텍스트를, 클라이언트 컴포넌트는 프로바이더를 통한 컨텍스트 공유가 필수적입니다.
명시적인 게 암묵적인 것보다 낫다: 자동으로 처리되길 기대하기보다, 로케일 정보를 명시적으로 전달하는 것이 디버깅과 유지보수 측면에서 훨씬 유리합니다.

글로벌 서비스를 꿈꾸는 개발자분들에게 이 글이 작은 도움이 되길 바랍니다. 다국어 지원은 단순히 텍스트를 바꾸는 것을 넘어, 사용자의 환경을 존중하는 첫걸음이니까요!

감사합니다.

다국어 프로젝트의 함정: Next.js i18n 레이아웃 버그 해결기

문제의 발견: "내용은 한국어인데 메뉴는 왜 영어지?"

원인 분석: 클라이언트 사이드 프로바이더의 부재

해결 과정: 명시적인 로케일 주입

1. Root Layout 수정

2. 블로그 페이지의 메타데이터 및 번역 로직 강화

3. 언어 전환기 로직 단순화

결과 및 교훈