Next.js | next-translate 기반 다국어(i18n) 설정 탐구하기

dayannne·2025년 9월 8일

🌍 next-translate 기반 다국어 설정 탐구하기

인턴 중인 회사에서 글로벌 플랫폼을 운영함에 따라 다국어 설정 라이브러리로 next-translate를 사용하고 있었다.

next-translate를 기반으로 i18n 세팅을 프로젝트에 어떻게 구성하는지, 특히 i18n.ts 설정 / I18nProvider 적용 / useTranslation 네임스페이스 사용에 대해 탐구한 것을 바탕으로 정리해보려 한다.

Next.js 다국어(i18n) 라이브러리

많이 사용하는 라이브러리로는 react-i18next next-i18next next-translation 가 있는 것 같다.

1️⃣ react-i18next

기반: i18next의 React 버전
사용 대상: 일반 React 프로젝트 or CSR 중심 프로젝트
특징:
가장 널리 쓰이는 i18n 라이브러리 중 하나
훅(useTranslation) 기반으로 컴포넌트에 쉽게 다국어 적용 가능
Lazy loading, namespace, fallback language 등 다양한 기능 지원
서버사이드 렌더링(SSR) 지원은 있지만 Next.js와 완벽한 통합은 아님

2️⃣ next-i18next

기반: react-i18next + Next.js
사용 대상: Next.js 프로젝트에서 SSR과 SSG를 모두 지원하고 싶을 때
특징:
Next.js에 최적화된 i18n 솔루션
서버 사이드에서 번역 리소스를 로딩하며 SEO에 유리
파일 기반 번역(json), 언어 별 namespace 구조 제공
app/ 디렉토리 (Next.js 13+) 지원도 진행 중이지만 제한적일 수 있음

3️⃣ next-translation

기반: Next.js 전용 경량화된 i18n 솔루션
사용 대상: 최신 Next.js (app/ 디렉토리 기반)와 함께 사용하는 경우
특징:
작은 번들 사이즈, 빠른 빌드 속도
직관적인 API와 폴더 구조
클라이언트와 서버 모두에서 동작
app/ 디렉토리 기반의 App Router 완전 지원
번역 파일은 페이지 또는 컴포넌트 단위로 나눠 관리 가능

🔧 구조 개요

/locales
	/ko
		common.json
		signup.json
	/en
		common.json
		signup.json
/i18n
	i18n.ts
	i18n.js
/pages
	_app.tsx
/components
	SignUpForm.tsx

🗂 번역 파일 예시

// locales/ko/signup.json
{
  "title": "회원가입",
  "step1": {
    "heading": "1단계"
  }
}

// locales/en/signup.json
{
  "title": "Sign Up",
  "step1": {
    "heading": "Step 1"
  }
}

📁 i18n.ts / i18n.js 설정

기본 세팅은 i18n.js 또는 i18n.ts에 정의한다.

이 파일은 next.config.js와 연결되며, next-translate가 참조하게 된다.

// i18n.ts (or i18n.js)
module.exports = {
  locales: ['ko', 'en'],
  defaultLocale: 'ko',
  pages: {
    '*': ['common'],
    '/signup': ['signup']
  }
}

locales: 지원 언어 목록
defaultLocale: 초기 언어
pages: 경로별로 사용할 네임스페이스(json 파일 이름)를 정의

pages 안에 어떤 페이지에서 어떤 json 파일을 불러올지 배열 형식으로 작성해 준다.
예를 들어 /signup 페이지에선 signup.json과 common.json 두 네임스페이스가 사용 된다.

위와 같이 세팅 후, 번역을 사용할 코드에서는 useTranslation 키워드를 사용하면 된다.

만약 여기서 지정해주지 않은 채로 뷰단에서 useTranslation('signup')을 사용할 시 적용되지 않기 때문에 주의해야 한다..!

🔁 useTranslation

next-translate는 훅 기반의 API를 제공하고 있다.
컴포넌트에서 다음처럼 사용할 수 있다.

import useTranslation from 'next-translate/useTranslation';

const SignUpForm = () => {
  const { t } = useTranslation('signup');

  return <h1>{t('title')}</h1>;
};

useTranslation('signup'): signup 네임스페이스 로드
t('title') : signup.json 내 "title" key 참조

📌 t의 타입이 명확하지 않을 때 아래와 같이 타입 선언도 가능하다 :


const { t }: { t: (key: string) => string } = useTranslation('signup');

🧪 I18nProvider

일반적으로 next-translate는 자체적으로 컨텍스트를 주입하므로, 대부분의 경우 I18nProvider를 따로 쓸 필요는 없다.

그러나 테스트 환경이나, Next.js의 렌더링 흐름 외부에서 번역을 사용할 때는 I18nProvider로 명시적으로 context를 감쌀 수 있다.

예시:

import { I18nProvider } from 'next-translate';
import i18nConfig from '../i18n/i18n';

<I18nProvider lang="ko" namespaces={{ signup: { title: '회원가입' } }} config={i18nConfig}>
  <SignUpForm />
</I18nProvider>

lang: 언어 지정
namespaces: 직접 번역 값 주입
config: i18n.ts 설정 전달

📌 이 방식은 주로 Storybook, Unit Test, Preview 환경 등에서 사용 되는 듯하다.

⚠️ 주의할 점

항목	설명
네임스페이스 누락	`useTranslation("ns")` 호출 시 해당 파일이 로드되지 않음
JSON key 오타	`t()`가 fallback으로 key 자체를 출력함
`pages` 설정 누락	자동 로딩되지 않아 runtime 오류 발생 가능

✅ 요약

항목	설명
사용 라이브러리	`next-translate`
번역 파일 위치	`/locales/{lang}/{namespace}.json`
주요 훅	`useTranslation('namespace')`
설정 파일	`i18n.ts` or `i18n.js`
Provider 사용	대부분 불필요 (예외: 테스트/프리뷰 환경)

✍️ 마치며

그동안 글로벌 플랫폼은 어떻게 운영되는지에 대한 궁금증이 있었는데, 실제로 현업에서 next-translate를 통해 다국어 설정이 어떻게 되어있는지 살펴보고, 또 관련한 버그를 수정해 보면서 배울 수 있었다.

단순히 텍스트를 번역하는 것을 넘어, 언어별 파일 구조 관리, 페이지 기반 네임스페이스 로딩, 그리고 SSR을 고려한 번역 처리 흐름까지 생각해야 한다는 점이 인상 깊고 알면 알수록 디테일한 고려사항들이 숨어 있는 신비한(?) 프론트엔드 세계...

dayannne

이전 포스트