Skip to main content

Next.js 국제화 완벽 가이드

App Router에서 next-intl을 설정하고 로케일 라우팅을 구성한 뒤 AI로 번역을 자동화하세요.

1

next-intl 설치

next-intl은 Next.js App Router의 로케일 라우팅, 메시지 로드, 번역 훅을 하나로 처리하는 패키지예요.

Terminal
npm install next-intl
next-i18next보다 next-intl을 선택하는 이유는 무엇일까요? next-intl은 App Router와 서버 컴포넌트를 위해 만들었어요. next-i18next는 Pages Router용으로 설계되어 App Router 지원이 제한적이에요.
2

i18n 요청 구성 생성

메시지 로드용 src/i18n/request.ts와 로케일 정의용 src/i18n/routing.ts, 두 파일을 만드세요. 이 파일에서 next-intl이 메시지와 경로를 해석하는 방식을 구성해요.

src/i18n/routing.ts
// src/i18n/routing.ts
import { defineRouting } from 'next-intl/routing';
import { createNavigation } from 'next-intl/navigation';

export const routing = defineRouting({
  locales: ['en', 'de', 'ja', 'es'],
  defaultLocale: 'en',
  localePrefix: 'as-needed',  // /about for en, /de/about for de
});

export const { Link, redirect, usePathname, useRouter } =
  createNavigation(routing);
Turbopack (Next.js 15의 기본 번들러)을 사용하려면 next.config.js에 experimental.turbo.resolveAlias가 필요해요. 이 설정이 없으면 "Couldn't find next-intl config file" 오류가 발생해요.
3

미들웨어 구성

로케일 감지, URL 재작성, 리디렉션을 처리하도록 middleware.ts를 추가하세요. 미들웨어가 모든 요청을 가로채 올바른 로케일이 적용되도록 해요.

middleware.ts
// middleware.ts  <- Must be in project ROOT, not src/
import createMiddleware from 'next-intl/middleware';
import { routing } from './src/i18n/routing';

export default createMiddleware(routing);

export const config = {
  matcher: ['/((?!api|_next|.*\\..*).*)'],
};
middleware.ts는 src/ 안이 아니라 반드시 프로젝트 루트 디렉터리에 있어야 해요. next-intl에서 가장 흔한 구성 실수예요.
4

[locale] 폴더 구조 설정

앱 경로를 app/[locale]/ 안으로 옮기세요. 빌드할 때 로케일별 페이지를 생성하도록 generateStaticParams를 추가하세요. 그러면 /en/about, /de/about 같은 URL 구조가 만들어져요.

app/[locale]/layout.tsx
// app/[locale]/layout.tsx
import { routing } from '@/i18n/routing';

export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}
번역을 사용하는 모든 page.tsx와 layout.tsx에서 반드시 setRequestLocale(locale)을 호출하세요. 호출하지 않으면 Next.js가 동적 렌더링으로 폴백해 빌드 성능이 크게 떨어져요.
5

루트 레이아웃 업데이트

getMessages()로 메시지를 로드하고 루트 로케일 레이아웃의 NextIntlClientProvider에 전달하세요. 로케일 매개변수로 html lang 속성을 설정하세요.

app/[locale]/layout.tsx
// app/[locale]/layout.tsx
import { NextIntlClientProvider } from 'next-intl';
import { getMessages, setRequestLocale } from 'next-intl/server';
import { routing } from '@/i18n/routing';
import { notFound } from 'next/navigation';

export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}

export default async function LocaleLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: { locale: string };
}) {
  const { locale } = await params;
  if (!routing.locales.includes(locale as any)) notFound();

  setRequestLocale(locale);
  const messages = await getMessages();

  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider locale={locale} messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}
NextIntlClientProvider에는 locale prop을 명시해야 해요. 생략하면 클라이언트 컴포넌트에서 디버깅하기 어려운 미묘한 오류가 발생해요.
6

컴포넌트에서 번역 사용

서버 컴포넌트는 getTranslations (async, await)를 사용하고 클라이언트 컴포넌트는 useTranslations (훅)을 사용해요. 컴포넌트가 렌더링되는 위치에 따라 선택하세요. 서버 컴포넌트는 번역을 JavaScript 번들에서 완전히 제외해요.

app/[locale]/page.tsx
// Server Component (default)
import { getTranslations, setRequestLocale } from 'next-intl/server';

export default async function AboutPage({
  params,
}: { params: { locale: string } }) {
  const { locale } = await params;
  setRequestLocale(locale);
  const t = await getTranslations('AboutPage');

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

// Client Component ('use client')
'use client';
import { useTranslations } from 'next-intl';

export default function SearchBar() {
  const t = useTranslations('SearchBar');
  return <input placeholder={t('placeholder')} />;
}
번역된 콘텐츠에는 서버 컴포넌트를 우선 사용하세요. 번역 문자열이 클라이언트 JavaScript 번들에 포함되지 않아 사용자의 로드 시간이 줄어들어요.
7

SEO 추가: 메타데이터 및 Hreflang

generateMetadata로 로케일별 페이지 제목과 설명을 생성하세요. 검색 엔진이 모든 페이지의 각 언어 버전을 찾을 수 있도록 hreflang 태그에 alternates.languages를 추가하세요.

app/[locale]/layout.tsx
// app/[locale]/layout.tsx or any page.tsx
import { getTranslations } from 'next-intl/server';
import { routing } from '@/i18n/routing';

export async function generateMetadata({
  params,
}: { params: { locale: string } }) {
  const { locale } = await params;
  const t = await getTranslations({ locale, namespace: 'Metadata' });

  return {
    title: t('title'),
    description: t('description'),
    alternates: {
      languages: Object.fromEntries(
        routing.locales.map((l) => [l, `/${l}`])
      ),
    },
  };
}
Vercel에서는 metadataBase를 설정하지 않으면 빌드가 localhost를 표준 URL로 생성할 수 있어요. 루트 레이아웃의 metadataBase를 항상 실제 서비스 도메인으로 설정하세요.
8

오류 및 Not Found 페이지 처리

error.tsx와 not-found.tsx는 일반 로케일 레이아웃 밖에서 렌더링될 수 있으므로 별도 처리가 필요해요. 루트 not-found.tsx에서 현지화된 오류 메시지를 표시하려면 자체 i18n 제공자 설정이 필요해요.

app/[locale]/error.tsx
// app/[locale]/error.tsx
'use client';
import { useTranslations } from 'next-intl';

export default function Error() {
  const t = useTranslations('Error');
  return (
    <div>
      <h1>{t('title')}</h1>
      <p>{t('description')}</p>
    </div>
  );
}

// app/not-found.tsx (root level -- needs own provider)
import { routing } from '@/i18n/routing';

export default async function GlobalNotFound() {
  return (
    <html lang={routing.defaultLocale}>
      <body>
        <h1>404 - Page Not Found</h1>
      </body>
    </html>
  );
}
Next.js는 코드에서 notFound()를 명시적으로 호출할 때만 현지화된 404 페이지를 렌더링해요. 일치하는 페이지가 없는 알 수 없는 경로에는 현지화된 버전이 아니라 기본 Next.js 404가 표시돼요.
9

번역 자동화

i18n 설정을 마쳤다면 IDE에서 바로 AI로 메시지 파일을 번역하거나 CI/CD 파이프라인에서 i18n Agent CLI를 사용해 배포할 때마다 번역을 자동화하세요.

Terminal
# In your IDE, ask your AI assistant:
> Translate messages/en.json to German, Japanese, and Spanish

✓ messages/de.json created (1.1s)
✓ messages/ja.json created (1.4s)
✓ messages/es.json created (1.0s)
next-intl-localechain으로 지능형 로케일 폴백을 사용하세요. 브라질 포르투갈어가 없을 때 pt-BR 사용자에게 영어 대신 pt-PT 번역이 표시돼요.

번역 품질 검사 자동화

i18n-validate를 사용해 누락된 키와 손상된 플레이스홀더를 배포 전에 찾아내세요. 실제 번역이 준비되기 전에 i18n-pseudo의 의사 번역으로 UI를 테스트하세요.

Next.js i18n용 오픈 소스 도구

이 오픈 소스 패키지는 Next.js 국제화 워크플로에서 자주 겪는 문제를 해결해요.

next-intl-localechain

기본 next-intl은 번역이 없으면 기본 로케일로 바로 폴백해요. 쓸 수 있는 pt-PT 번역이 있어도 브라질 포르투갈어 사용자에게 영어가 표시돼요. next-intl-localechain은 지능형 폴백 체인을 추가하고 관련 로케일의 번역을 재귀적으로 병합해 지역 사용자가 항상 가장 가까운 번역을 볼 수 있게 해요.

src/i18n/request.ts
import { getRequestConfig } from 'next-intl/server';
import { withLocaleChain } from 'next-intl-localechain';

export default getRequestConfig(withLocaleChain({
  loadMessages: (locale) =>
    import(`../../messages/${locale}.json`).then(m => m.default),
  defaultLocale: 'en'
}));
로케일 체인 전체의 번역 자동 재귀 병합
포르투갈어, 스페인어, 프랑스어, 독일어 등의 내장 체인
누락된 메시지 파일을 오류 없이 안전하게 건너뛰기
기존 getRequestConfig를 감싸는 한 줄 설정
GitHub에서 보기

@i18n-agent/cli

터미널을 벗어나지 않고 Next.js 메시지 파일을 번역하는 명령줄 도구예요. 파일을 직접 번역하고 작업 상태를 확인하며 결과를 다운로드할 수 있어요. API 키 인증을 사용해 CI/CD 파이프라인에서도 작동하므로 현지화 워크플로를 완전히 자동화할 수 있어요.

Terminal
# Install the CLI
npm install -g @i18n-agent/cli

# Authenticate
i18nagent login

# Translate your message files
i18nagent translate ./messages/en.json --lang de,ja,es

# Or use in CI/CD with an API key
export I18N_AGENT_API_KEY=your-key-here
i18nagent translate ./messages/en.json --lang de,ja,es
터미널에서 JSON, YAML, PO 및 기타 i18n 파일 형식 번역
CI/CD 지원: 환경 변수로 인증해 파이프라인 자동화
작업 상태 추적, 실패한 작업 재개, 결과 다운로드
스크립트 및 자동화를 위한 기계 판독 가능 JSON 출력
GitHub에서 보기

흔한 실수

"Unable to find next-intl locale"

미들웨어가 요청과 일치하지 않아요. middleware.ts가 프로젝트 루트에 있는지, matcher 패턴이 정적 파일을 올바르게 제외하는지, 로케일이 라우팅 구성에 포함되어 있는지 확인하세요.

예기치 않은 동적 렌더링

페이지나 레이아웃에 setRequestLocale(locale)이 없어요. 이 호출이 없으면 next-intl이 헤더와 쿠키로 로케일을 감지하므로 동적 렌더링이 강제되고 정적 생성이 불가능해요.

i18n과 병렬 경로의 호환성 문제

병렬 경로(@modal)와 가로채기 경로((.)photo)는 [locale] 동적 세그먼트와 호환되지 않는 것으로 알려져 있어요. 이러한 고급 라우팅 패턴에는 미들웨어 기반 라우팅을 우회 방법으로 사용하세요.

언어 전환 시 현재 경로 손실

로케일을 전환할 때 usePathname()으로 현재 경로 이름을 유지하고 로케일 세그먼트만 바꾸세요. 동적 경로 매개변수는 새 로케일에 맞춰 다시 해석해야 하므로 주의하세요.

권장 파일 구조

Project Structure
my-nextjs-app/
├── middleware.ts              # Locale routing (project root!)
├── next.config.mjs
├── messages/
│   ├── en.json                # Source messages
│   ├── de.json
│   └── ja.json
├── src/
│   ├── i18n/
│   │   ├── request.ts         # Message loading config
│   │   └── routing.ts         # Locale definitions
│   └── app/
│       └── [locale]/
│           ├── layout.tsx     # Root locale layout
│           ├── page.tsx       # Home page
│           ├── error.tsx      # Localized error page
│           ├── not-found.tsx  # Localized 404
│           └── about/
│               └── page.tsx
└── package.json

지금 i18n Agent 사용해 보기

번역 파일을 여기에 드롭

JSON, YAML, PO, XML, CSV, Markdown, Properties

또는 클릭하여 파일 선택

대상 언어

가입 불필요즉시 견적

next-intl-localechain을 활용한 로케일 폴백

pt-BR 같은 지역 로케일에 번역 키가 없으면 next-intl은 상위 로케일 pt를 먼저 확인하지 않고 기본 로케일로 바로 폴백해요.

Terminal
npm install next-intl-localechain
Configuration
import { withLocaleChain } from 'next-intl-localechain';

export default withLocaleChain({
  fallbacks: {
    'pt-BR': ['pt', 'en'],
    'zh-Hant-HK': ['zh-Hant', 'zh', 'en'],
  },
  defaultLocale: 'en',
  loadMessages: (locale) => import(`./messages/${locale}.json`),
});

지원 프레임워크와 75개 내장 체인의 전체 목록은 로케일 폴백 가이드에서 확인하세요. Learn more →

자주 묻는 질문