콘텐츠로 바로 가기
Next.js i18n

App Router를 지원하는 Next.js i18n

Next.js 애플리케이션을 위한 Server Components, ISR, 엣지 최적화 번역.

Set up in 4 steps

1

Install

Add @better-i18n/use-intl, use-intl, and the Next.js adapter to your project.

terminal
npm install @better-i18n/use-intl use-intl
2

Add middleware for locale detection

The middleware reads the Accept-Language header and URL prefix to detect the user's locale and redirect accordingly.

middleware.ts
import { betterI18nMiddleware } from '@better-i18n/next';
export const middleware = betterI18nMiddleware;
export const config = { matcher: ['/((?!api|_next).*)'] };
3

Load messages in a Server Component

Use getMessages() in your root layout to fetch translations server-side and pass them to BetterI18nProvider.

app/[locale]/layout.tsx
// app/[locale]/layout.tsx
import { BetterI18nProvider } from '@better-i18n/use-intl';
import { getMessages } from '@better-i18n/use-intl/server';

export default async function RootLayout({ children, params }) {
  const messages = await getMessages({
    project: 'your-org/your-project',
    locale: params.locale,
  });
  return (
    <html lang={params.locale}>
      <body>
        <BetterI18nProvider messages={messages} locale={params.locale} project="your-org/your-project">
          {children}
        </BetterI18nProvider>
      </body>
    </html>
  );
}
4

Use translations in Client Components

Call useTranslations() in any Client Component. Messages are already hydrated from the server — no extra fetch.

components/HeroSection.tsx
'use client';
import { useTranslations } from '@better-i18n/use-intl';

export function HeroSection() {
  const t = useTranslations('home');
  return <h1>{t('title')}</h1>;
}

기능

App Router 및 Pages Router 지원
자동 로케일 감지를 위한 미들웨어
React Server Components 지원
generateStaticParams로 정적 생성
점진적 정적 재생성(ISR)
타입 안전 번역
엣지 CDN 제공
hreflang로 SEO 최적화
로케일 기반 라우팅

Middleware Setup

Add locale detection and routing to your Next.js app with a single middleware file.

// middleware.ts — locale detection
import { betterI18nMiddleware } from '@better-i18n/next'
export const middleware = betterI18nMiddleware
export const config = { matcher: ['/((?!api|_next).*)'] }

빠른 시작

몇 줄의 코드만으로 Next.js 앱에 i18n을 추가하세요.

// app/[locale]/page.tsx
import { getTranslations } from '@better-i18n/next';

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

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

정보·감시·정찰(ISR) 및 국제화

증분 정적 재생성과 국제화를 결합하여 빠르고 항상 최신 상태를 유지하는 다국어 페이지를 구현하세요.

// app/[locale]/layout.tsx — ISR with i18n
import { getMessages } from '@better-i18n/use-intl/server';
import { BetterI18nProvider } from '@better-i18n/use-intl';

export const revalidate = 3600; // Revalidate every hour

export default async function LocaleLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: { locale: string };
}) {
  const messages = await getMessages({
    project: 'your-org/your-project',
    locale: params.locale,
  });

  return (
    <BetterI18nProvider messages={messages} locale={params.locale}>
      {children}
    </BetterI18nProvider>
  );
}

ISR with generateStaticParams

Pre-render pages for every locale at build time, then refresh with ISR on a schedule.

// app/[locale]/[slug]/page.tsx — Generate static pages per locale
import { getMessages } from '@better-i18n/use-intl/server';

export async function generateStaticParams() {
  const locales = ['en', 'de', 'fr', 'ja'];
  const slugs = await fetchAllSlugs();
  return locales.flatMap((locale) =>
    slugs.map((slug) => ({ locale, slug }))
  );
}

export const revalidate = 1800; // ISR: refresh every 30 min

export default async function Page({
  params,
}: {
  params: { locale: string; slug: string };
}) {
  const t = await getMessages({
    project: 'your-org/your-project',
    locale: params.locale,
    namespace: 'blog',
  });
  return <article><h1>{t[params.slug + '.title']}</h1></article>;
}

On-Demand Revalidation

Trigger ISR revalidation when translations are updated — hook into the Better i18n publish webhook.

// app/api/revalidate/route.ts — On-demand ISR for translation updates
import { revalidatePath } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const { locale, path, secret } = await request.json();

  if (secret !== process.env.REVALIDATION_SECRET) {
    return NextResponse.json({ error: 'Invalid secret' }, { status: 401 });
  }

  // Revalidate the specific locale path
  revalidatePath(`/${locale}${path}`);
  return NextResponse.json({ revalidated: true, locale, path });
}

Edge 런타임 및 로케일 감지

전 세계적으로 50밀리초 미만의 응답 시간을 위해 에지에서 로케일 감지 및 메시지 로딩을 실행합니다.

// middleware.ts — Edge-based locale detection
import { NextRequest, NextResponse } from 'next/server';

const SUPPORTED_LOCALES = ['en', 'de', 'fr', 'ja', 'es'] as const;
const DEFAULT_LOCALE = 'en';

function getPreferredLocale(request: NextRequest): string {
  // 1. Check URL prefix
  const pathname = request.nextUrl.pathname;
  const urlLocale = SUPPORTED_LOCALES.find(
    (l) => pathname.startsWith(`/${l}/`) || pathname === `/${l}`
  );
  if (urlLocale) return urlLocale;

  // 2. Check cookie
  const cookieLocale = request.cookies.get('NEXT_LOCALE')?.value;
  if (cookieLocale && SUPPORTED_LOCALES.includes(cookieLocale as any)) {
    return cookieLocale;
  }

  // 3. Parse Accept-Language header
  const acceptLang = request.headers.get('accept-language') ?? '';
  const preferred = acceptLang
    .split(',')
    .map((part) => part.split(';')[0].trim().substring(0, 2))
    .find((code) => SUPPORTED_LOCALES.includes(code as any));

  return preferred ?? DEFAULT_LOCALE;
}

export function middleware(request: NextRequest) {
  const locale = getPreferredLocale(request);
  const { pathname } = request.nextUrl;

  const hasLocale = SUPPORTED_LOCALES.some(
    (l) => pathname.startsWith(`/${l}/`) || pathname === `/${l}`
  );

  if (!hasLocale) {
    return NextResponse.redirect(
      new URL(`/${locale}${pathname}`, request.url)
    );
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

Edge-Compatible Message Loading

Cache translations at the edge with a lightweight in-memory TTL cache for instant responses.

// lib/edge-messages.ts — Edge-compatible message loading
const messageCache = new Map<string, { data: Record<string, string>; ts: number }>();
const TTL = 60_000; // 1 minute cache at edge

export async function getEdgeMessages(
  locale: string,
  namespace: string
): Promise<Record<string, string>> {
  const cacheKey = `${locale}:${namespace}`;
  const cached = messageCache.get(cacheKey);

  if (cached && Date.now() - cached.ts < TTL) {
    return cached.data;
  }

  const response = await fetch(
    `https://cdn.better-i18n.com/your-org/your-project/${locale}/${namespace}.json`,
    { next: { revalidate: 60 } }
  );

  const data = await response.json();
  messageCache.set(cacheKey, { data, ts: Date.now() });
  return data;
}

Edge API Route with i18n

Return translated API responses from edge functions with minimal cold start.

// app/api/translate/route.ts — Edge API route with i18n
import { getEdgeMessages } from '@/lib/edge-messages';

export const runtime = 'edge';

export async function GET(request: Request) {
  const url = new URL(request.url);
  const locale = url.searchParams.get('locale') ?? 'en';
  const key = url.searchParams.get('key') ?? '';

  const messages = await getEdgeMessages(locale, 'api-responses');
  const translated = messages[key] ?? key;

  return Response.json({ text: translated, locale });
}

일반적인 국제화 문제 해결

수분 불일치, 누락된 로케일 대체 처리, 날짜/숫자 서식 차이를 수정하십시오.

// Fix: Hydration mismatch with date/number formatting
// Problem: Server renders "1,000" but client renders "1.000"
// Solution: Ensure the same locale is used on both server and client

// app/[locale]/layout.tsx
import { getFormatter } from '@better-i18n/use-intl/server';

export default async function Layout({ children, params }: {
  children: React.ReactNode;
  params: { locale: string };
}) {
  // Pre-format on server with the explicit locale
  const formatter = await getFormatter(params.locale);

  return (
    <html lang={params.locale} suppressHydrationWarning>
      <body>{children}</body>
    </html>
  );
}

// components/Price.tsx — Client component
'use client';
import { useFormatter } from '@better-i18n/use-intl';

export function Price({ amount }: { amount: number }) {
  const format = useFormatter();
  // useFormatter automatically uses the locale from the provider
  // ensuring server and client render the same output
  return <span>{format.number(amount, { style: 'currency', currency: 'USD' })}</span>;
}

Locale Fallback Chain

Define fallback chains so regional variants like pt-BR fall back to pt, then en.

// lib/i18n-config.ts — Locale fallback chain
const FALLBACK_CHAIN: Record<string, string[]> = {
  'pt-BR': ['pt', 'en'],
  'zh-TW': ['zh-CN', 'en'],
  'en-GB': ['en'],
  'de-AT': ['de', 'en'],
};

export function resolveMessages(
  locale: string,
  allMessages: Record<string, Record<string, string>>
): Record<string, string> {
  const chain = FALLBACK_CHAIN[locale] ?? ['en'];
  const primary = allMessages[locale] ?? {};

  // Merge fallback messages (primary overrides fallbacks)
  return chain.reduceRight(
    (merged, fallbackLocale) => ({
      ...merged,
      ...(allMessages[fallbackLocale] ?? {}),
    }),
    primary
  );
}

Consistent Date Formatting

Avoid server/client date mismatches by explicitly setting timeZone to UTC.

// components/LocalizedDate.tsx — Consistent date formatting
'use client';
import { useFormatter, useLocale } from '@better-i18n/use-intl';

export function LocalizedDate({ date }: { date: Date | string }) {
  const format = useFormatter();
  const locale = useLocale();
  const dateObj = typeof date === 'string' ? new Date(date) : date;

  return (
    <time dateTime={dateObj.toISOString()}>
      {format.dateTime(dateObj, {
        year: 'numeric',
        month: 'long',
        day: 'numeric',
        // Explicitly set timeZone to avoid server/client mismatch
        timeZone: 'UTC',
      })}
    </time>
  );
}

고급 패턴

중첩된 레이아웃, 병렬 경로, 타입 안전 번역을 지원하는 서버 액션.

// app/[locale]/dashboard/layout.tsx — Nested layout with namespace
import { getMessages } from '@better-i18n/use-intl/server';
import { BetterI18nProvider } from '@better-i18n/use-intl';
import { DashboardNav } from '@/components/DashboardNav';

export default async function DashboardLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: { locale: string };
}) {
  // Load dashboard-specific namespace alongside common messages
  const [commonMessages, dashMessages] = await Promise.all([
    getMessages({ project: 'your-org/your-project', locale: params.locale, namespace: 'common' }),
    getMessages({ project: 'your-org/your-project', locale: params.locale, namespace: 'dashboard' }),
  ]);

  const messages = { ...commonMessages, ...dashMessages };

  return (
    <BetterI18nProvider messages={messages} locale={params.locale}>
      <DashboardNav />
      <main>{children}</main>
    </BetterI18nProvider>
  );
}

Parallel Routes with i18n

Load translations independently in parallel route slots for modular, locale-aware layouts.

// app/[locale]/@analytics/page.tsx — Parallel route with i18n
import { getTranslations } from '@better-i18n/next';

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

  return (
    <section aria-label={t('title')}>
      <h2>{t('title')}</h2>
      <p>{t('description')}</p>
    </section>
  );
}

// app/[locale]/layout.tsx — Consuming parallel routes
export default function Layout({
  children,
  analytics,
  notifications,
}: {
  children: React.ReactNode;
  analytics: React.ReactNode;
  notifications: React.ReactNode;
}) {
  return (
    <div>
      <main>{children}</main>
      <aside>{analytics}</aside>
      <aside>{notifications}</aside>
    </div>
  );
}

Server Actions with Translation

Return translated validation errors and success messages from server actions.

// app/[locale]/contact/actions.ts — Server action with i18n
'use server';
import { getTranslations } from '@better-i18n/next';
import { headers } from 'next/headers';

export async function submitContactForm(formData: FormData) {
  const headersList = headers();
  const locale = headersList.get('x-locale') ?? 'en';
  const t = await getTranslations(locale, 'contact');

  const email = formData.get('email') as string;
  const message = formData.get('message') as string;

  if (!email || !message) {
    return { error: t('validation.required') };
  }

  try {
    await sendEmail({ email, message, locale });
    return { success: t('form.success') };
  } catch {
    return { error: t('form.error') };
  }
}

// app/[locale]/contact/page.tsx — Using the server action
'use client';
import { useTranslations } from '@better-i18n/use-intl';
import { submitContactForm } from './actions';

export default function ContactPage() {
  const t = useTranslations('contact');

  return (
    <form action={submitContactForm}>
      <label>{t('form.email')}</label>
      <input name="email" type="email" required />
      <label>{t('form.message')}</label>
      <textarea name="message" required />
      <button type="submit">{t('form.submit')}</button>
    </form>
  );
}

인기 있는 Next.js i18n 라이브러리와 호환

Better i18n은 좋아하는 i18n 라이브러리를 대체하는 것이 아닙니다 — 더 강력하게 만들어주는 번역 관리 레이어입니다.

Better i18n + next-intl

App Router 지원, 타입 안전 메시지, ICU 구문을 갖춘 가장 인기 있는 Next.js i18n 라이브러리.

Better i18n은 next-intl JSON 형식으로 번역을 직접 동기화합니다. 대시보드에서 관리하고 CDN을 통해 즉시 배포하세요.

Better i18n + next-i18next

i18next 기반의 검증된 Next.js i18n 라이브러리. Pages Router와 App Router 마이그레이션에 적합합니다.

i18next 호환 네임스페이스 JSON으로 내보내기. Better i18n이 번역 워크플로를, next-i18next가 런타임을 담당합니다.

Better i18n + Lingui

뛰어난 DX와 자동 메시지 추출을 갖춘 가볍고 매크로 기반의 i18n 라이브러리.

Lingui CLI로 메시지를 추출하고, Better i18n에서 번역을 관리하고, GitHub 연동으로 자동 동기화합니다.

Related Articles

2026년 최고의 AI 번역 도구: 개발자 가이드

2026년 최고의 AI 번역 도구: 개발자 가이드 2026년 개발자를 위한 최고의 AI 번역 도구는 DeepL API, Google Cloud Translation, Amazon Translate, Azure Translator, 그리고 better-i18n입니다. 각각...

Read more →

Django i18n mit KI-Übersetzung: Vollständige Einrichtungsanleitung

Django i18n mit KI-Übersetzung: Vollständige Einrichtungsanleitung Django wird mit einem ausgereiften Internationalisierungs-Framework (i18n) geliefert,...

Read more →

개발자 경험 심층 분석: Better i18n 플랫폼 UX가 현지화를 빠르고 직관적으로 만드는 방법

현지화 플랫폼은 투박한 인터페이스, 느린 편집기, 위원회에서 설계한 것 같은 워크플로우로 악명이 높습니다. 우리는 다른 철학으로 Better i18n을 구축했습니다: 모든 상호작용이 의도적이고, 빠르며, 개발자의 시간을 존중해야 합니다. 이 글은 Better i18n을 다르게...

Read more →

관련

React i18n

핵심 React Hooks 및 유틸리티

For Developers

개발자 팀을 위해 구축된 도구 및 워크플로

next-intl Alternative

next-intl과 비교

문서

완전한 설정 가이드 및 API 레퍼런스

다른 프레임워크 가이드 살펴보기

React i18nVue i18nNuxt i18nAngular i18nSvelte i18nVite i18nRemix & Hydrogen i18nExpo i18niOS i18nFlutter i18nTanStack Start i18nServer / Hono i18n

Next.js i18n으로 개발을 시작하세요

무료 플랜을 사용할 수 있습니다. 신용카드가 필요 없습니다.

무료로 시작하기문서 보기