작가:
    생성:2025-11-01마지막 업데이트:2026-05-31

    2025년에 next-intl을 사용하여 Next.js 애플리케이션을 국제화하는 방법

    목차

    next-intl이란?

    next-intl은 Next.js App Router를 위해 특별히 설계된 인기 있는 국제화(i18n) 라이브러리입니다. 뛰어난 TypeScript 지원과 내장 최적화를 제공하여 다국어 Next.js 애플리케이션을 원활하게 구축할 수 있습니다.

    원하신다면 next-i18next 가이드를 참고하거나, 직접 Intlayer를 사용할 수도 있습니다.
    비교 내용은 next-i18next vs next-intl vs Intlayer에서 확인하세요.

    따라야 할 모범 사례

    구현에 들어가기 전에, 다음과 같은 모범 사례를 따라야 합니다:

    • HTML lang 및 dir 속성 설정 레이아웃에서 getLocaleDirection(locale)를 사용하여 dir을 계산하고, 올바른 접근성과 SEO를 위해 <html lang={locale} dir={dir}>를 설정하세요.
    • 네임스페이스별 메시지 분리 로케일과 네임스페이스별로 JSON 파일을 구성하여 (예: common.json, about.json) 필요한 것만 로드하도록 하세요.
    • 클라이언트 페이로드 최소화 페이지에서 NextIntlClientProvider에 필요한 네임스페이스만 전송하세요 (예: pick(messages, ['common', 'about'])).
    • 정적 페이지 선호 성능과 SEO 향상을 위해 가능한 한 정적 페이지를 사용하세요.
    • 서버 컴포넌트에서의 i18n

    서버 컴포넌트는 페이지나 client로 표시되지 않은 모든 컴포넌트처럼 정적이며 빌드 시 미리 렌더링할 수 있습니다. 따라서 번역 함수를 props로 전달해야 합니다.

    • TypeScript 타입 설정
      애플리케이션 전반에 걸쳐 타입 안전성을 보장하기 위해 로케일에 대한 타입을 설정하세요.
    • 리디렉션을 위한 프록시
      로케일 감지와 라우팅을 처리하고 사용자를 적절한 로케일 접두사가 붙은 URL로 리디렉션하기 위해 프록시를 사용하세요.
    • 메타데이터, 사이트맵, robots.txt의 국제화
      Next.js에서 제공하는 generateMetadata 함수를 사용하여 메타데이터, 사이트맵, robots.txt를 국제화하여 모든 로케일에서 검색 엔진이 더 잘 인식하도록 하세요.
    • 링크 현지화
      Link 컴포넌트를 사용하여 링크를 현지화하고 사용자를 적절한 로케일 접두사가 붙은 URL로 리디렉션하세요. 이는 모든 로케일에서 페이지의 검색 가능성을 보장하는 데 중요합니다.
    • 테스트 및 번역 자동화 테스트와 번역 자동화는 다국어 애플리케이션을 유지 관리하는 데 소요되는 시간을 줄이는 데 도움이 됩니다.
    국제화 및 SEO에 대해 알아야 할 모든 내용을 정리한 문서를 참고하세요: next-intl과 함께하는 국제화(i18n).

    Next.js 애플리케이션에서 next-intl 설정 단계별 가이드

    ide.intlayer.org
    GitHub에서 애플리케이션 템플릿을 참조하세요.

    다음은 우리가 생성할 프로젝트 구조입니다:

    bash
    .├── global.ts├── locales│   ├── en│   │  ├── common.json│   │  └── about.json│   ├── fr│   │  ├── common.json│   │  └── about.json│   └── es│      ├── common.json│      └── about.json└── src # Src는 선택 사항입니다    ├── proxy.ts    ├── app    │   ├── i18n.ts    │   └── [locale]    │       ├── layout.tsx    │       ├── (home) # / (홈 리소스로 모든 페이지를 오염시키지 않기 위한 라우트 그룹)    │       │   ├── layout.tsx    │       │   └── page.tsx    │       └── about # /about    │           ├── layout.tsx    │           └── page.tsx    └── components        ├── ClientComponent.tsx        └── ServerComponent.tsx

    1. 의존성 설치

      npm을 사용하여 필요한 패키지를 설치하세요:

      bash
      npm install next-intl
      • next-intl: Next.js App Router용 핵심 국제화 라이브러리로, 번역 관리를 위한 훅, 서버 함수, 클라이언트 프로바이더를 제공합니다.

    2. 프로젝트 구성

      지원하는 로케일을 정의하고 next-intl의 요청 구성을 설정하는 구성 파일을 만드세요. 이 파일은 i18n 설정의 단일 진실 소스로 작동하며 애플리케이션 전반에 걸쳐 타입 안전성을 보장합니다.

      로케일 구성을 중앙 집중화하면 불일치를 방지하고 향후 로케일을 추가하거나 제거하기가 더 쉬워집니다. getRequestConfig 함수는 모든 요청 시 실행되며 각 페이지에 필요한 번역만 로드하여 코드 분할을 가능하게 하고 번들 크기를 줄입니다.

      src/i18n.ts
      import { notFound } from "next/navigation";import createMiddleware from "next-intl/middleware";import { createNavigation } from "next-intl/navigation";// 타입 안전성을 갖춘 지원 로케일 정의export const locales = ["en", "fr", "es"] as const;export type Locale = (typeof locales)[number];export const defaultLocale: Locale = "en";export function isRTL(locale: Locale | (string & {})) {  return /^(ar|fa|he|iw|ur|ps|sd|ug|yi|ckb|ku)(-|$)/i.test(locale);}// 코드 분할을 가능하게 하기 위해 로케일별로 메시지를 동적으로 로드합니다// Promise.all은 더 나은 성능을 위해 네임스페이스를 병렬로 로드합니다async function loadMessages(locale: Locale) {  // 레이아웃/페이지에서 필요한 네임스페이스만 로드합니다  const [common, home, about] = await Promise.all([    import(`../locales/${locale}/common.json`).then((m) => m.default),    import(`../locales/${locale}/home.json`).then((m) => m.default),    import(`../locales/${locale}/about.json`).then((m) => m.default),    // ... 향후 JSON 파일은 여기에 추가해야 합니다  ]);  return { common, home, about } as const;}// 지역화된 URL을 생성하는 헬퍼 함수 (예: /about vs /fr/about)export function localizedPath(locale: string, path: string) {  return locale === defaultLocale ? path : `/${locale}${path}`;}// getRequestConfig는 모든 요청 시 실행되며 서버 컴포넌트에 메시지를 제공합니다// next-intl이 Next.js의 서버 사이드 렌더링에 연결되는 부분입니다export default async function getRequestConfig({  requestLocale,}: {  requestLocale: Promise<string | undefined>;}) {  const requested: Locale = ((await requestLocale) as Locale) ?? defaultLocale;  if (!locales.includes(requested)) notFound();  return {    locale: requested,    messages: await loadMessages(requested),  };}export function getCookie(locale: Locale) {  return [    `NEXT_LOCALE=${locale}`,    "Path=/",    `Max-Age=${60 * 60 * 24 * 365}`, // 1년    "SameSite=Lax",  ].join("; ");}const routingOptions = {  locales,  defaultLocale,  localePrefix: "as-needed", // /en/... 경로를 /...로 변경  // 선택 사항: 지역화된 경로명  // pathnames: {  //   '/': '/',  //   '/about': {en: '/about', fr: '/a-propos', es: '/acerca-de'},  //   '/blog/[slug]': '/blog/[slug]'  // }  //  localeDetection: true, // 쿠키로 인한 "/" -> "/en" 리디렉션 방지} as const;export const { Link, redirect, usePathname, useRouter, getPathname } =  createNavigation(routingOptions);export const proxy = createMiddleware(routingOptions);

    3. 동적 로케일 라우트 정의

      앱 폴더에 [locale] 디렉토리를 생성하여 로케일 기반 동적 라우팅을 설정하세요. 이를 통해 Next.js는 각 로케일이 URL 세그먼트가 되는 로케일 기반 라우팅을 처리할 수 있습니다 (예: /en/about, /fr/about).

      동적 라우트를 사용하면 Next.js가 빌드 시 모든 로케일에 대해 정적 페이지를 생성할 수 있어 성능과 SEO가 향상됩니다. 레이아웃 컴포넌트는 로케일에 따라 HTML의 lang 및 dir 속성을 설정하는데, 이는 접근성과 검색 엔진 이해에 매우 중요합니다.

      src/app/[locale]/layout.tsx
      import type { ReactNode } from "react";import { locales } from "@/i18n";import { getLocaleDirection, setRequestLocale } from "next-intl/server";// 빌드 시 모든 로케일에 대해 정적 페이지를 미리 생성 (SSG)// 이는 성능과 SEO를 향상시킵니다export function generateStaticParams() {  return locales.map((locale) => ({ locale }));}export default function LocaleLayout({  children,  params,}: {  children: ReactNode;  params: Promise<{ locale: string }>;}) {  // Next.js App Router에서 params는 Promise입니다 (await 가능)  // 이를 통해 동적 라우트 세그먼트를 비동기적으로 해결할 수 있습니다  const { locale } = await params;  // 중요: setRequestLocale은 next-intl에 이 요청에 사용할 로케일을 알려줍니다  // 이것이 없으면 getTranslations()가 서버 컴포넌트에서 사용할 로케일을 알 수 없습니다  setRequestLocale(locale);  // 올바른 HTML 렌더링을 위해 텍스트 방향(LTR/RTL)을 가져옵니다  const dir = getLocaleDirection(locale);  return (    <html lang={locale} dir={dir}>      <body>{children}</body>    </html>  );}}
      src/app/[locale]/about/page.tsx
      import { getTranslations, getMessages, getFormatter } from "next-intl/server";import { NextIntlClientProvider } from "next-intl";import pick from "lodash/pick";import ServerComponent from "@/components/ServerComponent";import ClientComponent from "@/components/ClientComponent";export default async function AboutPage({  params,}: {  params: Promise<{ locale: string }>;}) {  const { locale } = await params;  // 메시지는 서버 측에서 로드됩니다. 클라이언트에는 필요한 것만 전달하세요.  // 이렇게 하면 브라우저로 전송되는 자바스크립트 번들이 최소화됩니다.  const messages = await getMessages();  const clientMessages = pick(messages, ["common", "about"]);  // 엄격히 서버 측에서만 사용하는 번역/포맷팅  // 이들은 서버에서 실행되며 컴포넌트에 props로 전달될 수 있습니다  const tAbout = await getTranslations("about");  const tCounter = await getTranslations("about.counter");  const format = await getFormatter();  const initialFormattedCount = format.number(0);  return (    // NextIntlClientProvider는 클라이언트 컴포넌트에서 번역을 사용할 수 있게 합니다    // 클라이언트 컴포넌트가 실제로 사용하는 네임스페이스만 전달하세요    <NextIntlClientProvider locale={locale} messages={clientMessages}>      <main>        <h1>{tAbout("title")}</h1>        <ClientComponent />        <ServerComponent          formattedCount={initialFormattedCount}          label={tCounter("label")}          increment={tCounter("increment")}        />      </main>    </NextIntlClientProvider>  );}

    4. 번역 파일 생성하기

      각 로케일과 네임스페이스별로 JSON 파일을 생성하세요. 이 구조는 번역을 논리적으로 구성하고 각 페이지에 필요한 번역만 로드할 수 있게 해줍니다.

      네임스페이스별로 번역을 구성하는 것(e.g., common.json, about.json)은 코드 분할을 가능하게 하며 번들 크기를 줄여줍니다. 이렇게 하면 각 페이지에 필요한 번역만 로드하여 성능을 향상시킬 수 있습니다.

      locales/en/common.json
      {  "welcome": "Welcome",  "greeting": "Hello, world!"}
      locales/fr/common.json
      {  "welcome": "Bienvenue",  "greeting": "Bonjour le monde!"}
      locales/en/about.json
      {  "title": "About",  "description": "About page description",  "counter": {    "label": "Counter",    "increment": "Increment"  }}
      locales/fr/about.json
      {  "title": "À propos",  "description": "Description de la page À propos",  "counter": {    "label": "Compteur",    "increment": "Incrémenter"  }}

    5. 페이지에서 번역 활용하기

      서버에서 번역을 로드하고 이를 서버 및 클라이언트 컴포넌트 모두에 전달하는 페이지 컴포넌트를 만드세요. 이렇게 하면 렌더링 전에 번역이 로드되어 콘텐츠 깜박임을 방지할 수 있습니다.

      서버 측에서 번역을 로드하면 SEO가 향상되고 FOUC(번역되지 않은 콘텐츠 깜박임)를 방지할 수 있습니다. pick을 사용하여 필요한 네임스페이스만 클라이언트 프로바이더에 전달함으로써 브라우저에 전송되는 자바스크립트 번들 크기를 최소화합니다.

      src/app/[locale]/about/page.tsx
      import { getTranslations, getMessages, getFormatter } from "next-intl/server";import { NextIntlClientProvider } from "next-intl";import pick from "lodash/pick";import ServerComponent from "@/components/ServerComponent";import ClientComponent from "@/components/ClientComponent";export default async function AboutPage({  params,}: {  params: Promise<{ locale: string }>;}) {  const { locale } = await params;  // 메시지는 서버 측에서 로드됩니다. 클라이언트에는 필요한 것만 전달하세요.  // 이렇게 하면 브라우저로 전송되는 JavaScript 번들이 최소화됩니다.  const messages = await getMessages();  const clientMessages = pick(messages, ["common", "about"]);  // 엄격히 서버 측 번역/포맷팅  // 이들은 서버에서 실행되며 컴포넌트에 props로 전달될 수 있습니다  const tAbout = await getTranslations("about");  const tCounter = await getTranslations("about.counter");  const format = await getFormatter();  const initialFormattedCount = format.number(0);  return (    // NextIntlClientProvider는 클라이언트 컴포넌트에서 번역을 사용할 수 있게 합니다.    // 클라이언트 컴포넌트가 실제로 사용하는 네임스페이스만 전달하세요.    <NextIntlClientProvider locale={locale} messages={clientMessages}>      <main>        <h1>{tAbout("title")}</h1>        <ClientComponent />        <ServerComponent          formattedCount={initialFormattedCount}          label={tCounter("label")}          increment={tCounter("increment")}        />      </main>    </NextIntlClientProvider>  );}

    6. 클라이언트 컴포넌트에서 번역 사용하기

      클라이언트 컴포넌트는 useTranslations 및 useFormatter 훅을 사용하여 번역 및 포맷팅 기능에 접근할 수 있습니다. 이 훅들은 NextIntlClientProvider 컨텍스트에서 값을 읽어옵니다.

      클라이언트 컴포넌트는 번역에 접근하기 위해 React 훅이 필요합니다. useTranslations와 useFormatter 훅은 next-intl과 원활하게 통합되며, 로케일이 변경될 때 반응형 업데이트를 제공합니다.

      페이지의 클라이언트 메시지에 필요한 네임스페이스를 추가하는 것을 잊지 마세요 (클라이언트 컴포넌트가 실제로 필요로 하는 네임스페이스만 포함하세요).
      src/components/ClientComponent.tsx
      "use client";import React, { useState } from "react";import { useTranslations, useFormatter } from "next-intl";const ClientComponent = () => {  // 중첩된 객체에 직접 범위를 지정  // useTranslations/useFormatter는 NextIntlClientProvider 컨텍스트에서 읽는 훅입니다.  // 이 훅들은 컴포넌트가 NextIntlClientProvider로 감싸져 있을 때만 작동합니다.  const t = useTranslations("about.counter");  const format = useFormatter();  const [count, setCount] = useState(0);  return (    <div>      <p>{format.number(count)}</p>      <button        aria-label={t("label")}        onClick={() => setCount((count) => count + 1)}      >        {t("increment")}      </button>    </div>  );};

    7. 서버 컴포넌트에서 번역 사용하기

      서버 컴포넌트는 React 훅을 사용할 수 없으므로, 부모 컴포넌트로부터 props를 통해 번역과 포매터를 전달받습니다. 이 방법은 서버 컴포넌트를 동기적으로 유지하며 클라이언트 컴포넌트 내부에 중첩될 수 있게 합니다.

      클라이언트 경계 내에 중첩될 수 있는 서버 컴포넌트는 동기적이어야 합니다. 번역된 문자열과 포맷된 값을 props로 전달함으로써 비동기 작업을 피하고 올바른 렌더링을 보장합니다. 부모 페이지 컴포넌트에서 번역과 포맷을 미리 계산하세요.

      src/components/ServerComponent.tsx
      // 클라이언트 컴포넌트 내에 중첩된 서버 컴포넌트는 동기적이어야 합니다// React는 서버/클라이언트 경계 간에 비동기 함수를 직렬화할 수 없습니다// 해결책: 부모에서 번역/포맷을 미리 계산하고 props로 전달type ServerComponentProps = {  formattedCount: string; // 포맷된 카운트 문자열  label: string; // 버튼 라벨  increment: string; // 증가 텍스트};const ServerComponent = ({  formattedCount,  label,  increment,}: ServerComponentProps) => {  return (    <div>      <p>{formattedCount}</p>      <button aria-label={label}>{increment}</button>    </div>  );};
      페이지나 레이아웃에서 next-intl/server의 getTranslations와 getFormatter를 사용하여 번역과 포맷팅을 미리 계산한 후, 이를 props로 서버 컴포넌트에 전달하세요.

    8. 콘텐츠의 언어 변경하기

      선택사항

      next-intl을 사용하여 콘텐츠의 언어를 변경하려면, 동일한 경로명을 가리키면서 로케일을 전환하는 로케일 인식 링크를 렌더링하세요. 프로바이더가 URL을 자동으로 재작성하므로 현재 경로만 지정하면 됩니다.

      src/components/LocaleSwitcher.tsx
      "use client";import Link from "next/link";import { usePathname } from "next/navigation";import { useLocale } from "next-intl";import { defaultLocale, getCookie, type Locale, locales } from "@/i18n";const getLocaleLabel = (locale: Locale): string => {  try {    const displayNames = new Intl.DisplayNames([locale], { type: "language" });    return displayNames.of(locale) ?? locale.toUpperCase();  } catch {    return locale.toUpperCase();  }};const localeFlags: Record<Locale, string> = {  en: "🇬🇧",  fr: "🇫🇷",  es: "🇪🇸",};export default function LocaleSwitcher() {  const activeLocale = useLocale();  const pathname = usePathname();  // 경로에서 로케일 접두사를 제거하여 기본 경로를 가져옵니다  const getBasePath = (path: string) => {    for (const locale of locales) {      if (path.startsWith(`/${locale}`)) {        return path.slice(locale.length + 1) || "/";      }    }    return path;  };  const basePath = getBasePath(pathname);  return (    <nav aria-label="언어 선택기">      <div>        {(locales as readonly Locale[]).map((locale) => {          const isActive = locale === activeLocale;          // 기본 로케일인지 여부에 따라 href를 생성합니다          const href =            locale === defaultLocale ? basePath : `/${locale}${basePath}`;          return (            <Link              key={locale}              href={href}              aria-current={isActive ? "page" : undefined}              onClick={() => {                document.cookie = getCookie(locale);              }}            >              <span>{localeFlags[locale]}</span>              <span>{getLocaleLabel(locale)}</span>              <span>{locale.toUpperCase()}</span>            </Link>          );        })}      </div>    </nav>  );}

    9. 현지화된 Link 컴포넌트 사용하기

      선택사항

      next-intl은 활성 로케일을 자동으로 적용하는 현지화된 링크 컴포넌트를 포함하는 서브패키지 next-intl/navigation을 제공합니다. 우리는 이미 @/i18n 파일에서 이를 추출해 두었으므로 다음과 같이 사용할 수 있습니다:

      src/components/MyComponent.tsx
      import { Link } from "@/i18n";return <Link href="/about">t("about.title")</Link>;

    10. 서버 액션 내에서 활성 로케일 접근하기

      선택사항

      서버 액션은 next-intl/server를 사용하여 현재 로케일을 읽을 수 있습니다. 이는 현지화된 이메일을 보내거나 제출된 데이터와 함께 언어 선호도를 저장하는 데 유용합니다.

      src/app/actions/get-current-locale.ts
      "use server";import { getLocale } from "next-intl/server";export async function getCurrentLocale() {  return getLocale();}export async function handleContactForm(formData: FormData) {  const locale = await getCurrentLocale();  // 템플릿, 분석 레이블 등을 선택하기 위해 locale을 사용합니다.  console.log(`locale ${locale}에서 받은 연락처 양식`);}
      getLocale는 next-intl 프록시가 설정한 locale을 읽기 때문에 서버 어디서나 작동합니다: Route Handlers, Server Actions, 그리고 edge functions.

    11. 메타데이터 국제화하기

      선택사항

      콘텐츠 번역도 중요하지만, 국제화의 주요 목표는 웹사이트를 전 세계에 더 잘 보이게 만드는 것입니다. I18n은 적절한 SEO를 통해 웹사이트 가시성을 향상시키는 놀라운 수단입니다.

      적절하게 국제화된 메타데이터는 검색 엔진이 페이지에서 어떤 언어가 사용 가능한지 이해하는 데 도움을 줍니다. 여기에는 hreflang 메타 태그 설정, 제목과 설명 번역, 각 로케일에 대해 정규화된 URL이 올바르게 설정되었는지 확인하는 작업이 포함됩니다.

      src/app/[locale]/about/layout.tsx
      import type { Metadata } from "next";import { locales, defaultLocale, localizedPath } from "@/i18n";import { getTranslations } from "next-intl/server";// generateMetadata는 각 로케일마다 실행되어 SEO 친화적인 메타데이터를 생성합니다// 이것은 검색 엔진이 대체 언어 버전을 이해하는 데 도움을 줍니다.export async function generateMetadata({  params,}: {  params: { locale: string };}): Promise<Metadata> {  const { locale } = params;  const t = await getTranslations({ locale, namespace: "about" });  const url = "/about";  const languages = Object.fromEntries(    locales.map((locale) => [locale, localizedPath(locale, url)])  );  return {    title: t("title"),    description: t("description"),    alternates: {      canonical: localizedPath(locale, url),      languages: { ...languages, "x-default": url },    },  };}// ... 페이지 나머지 코드

    12. 사이트맵 국제화하기

      선택사항

      모든 로케일 버전의 페이지를 포함하는 사이트맵을 생성하세요. 이는 검색 엔진이 모든 언어 버전의 콘텐츠를 발견하고 색인화하는 데 도움이 됩니다.

      적절하게 국제화된 사이트맵은 검색 엔진이 모든 언어 버전의 페이지를 찾고 색인화할 수 있도록 보장합니다. 이는 국제 검색 결과에서 가시성을 향상시킵니다.

      src/app/sitemap.ts
      import type { MetadataRoute } from "next";import { defaultLocale, locales } from "@/i18n";const origin = "https://example.com";const formatterLocalizedPath = (locale: string, path: string) =>  locale === defaultLocale ? `${origin}${path}` : `${origin}/${locale}${path}`;/** * 모든 로케일과 해당 로컬라이즈된 경로의 맵을 가져옵니다. * * 예시 출력: * { *   "en": "https://example.com", *   "fr": "https://example.com/fr", *   "es": "https://example.com/es", *   "x-default": "https://example.com" * } */const getLocalizedMap = (path: string) =>  Object.fromEntries([    ...locales.map((locale) => [locale, formatterLocalizedPath(locale, path)]),    ["x-default", formatterLocalizedPath(defaultLocale, path)],  ]);// 더 나은 SEO를 위해 모든 로케일 변형을 포함하는 사이트맵 생성// alternates 필드는 검색 엔진에 언어 버전을 알립니다export default function sitemap(): MetadataRoute.Sitemap {  return [    {      url: formatterLocalizedPath(defaultLocale, "/"),      lastModified: new Date(),      changeFrequency: "monthly",      priority: 1.0,      alternates: { languages: getLocalizedMap("/") },    },    {      url: formatterLocalizedPath(defaultLocale, "/about"),      lastModified: new Date(),      changeFrequency: "monthly",      priority: 0.7,      alternates: { languages: getLocalizedMap("/about") },    },  ];}

    13. robots.txt 국제화하기

      선택사항

      보호된 경로의 모든 로케일 버전을 적절히 처리하는 robots.txt 파일을 만드세요. 이를 통해 검색 엔진이 어떤 언어로든 관리자(admin)나 대시보드 페이지를 인덱싱하지 않도록 할 수 있습니다.

      모든 로케일에 대해 robots.txt를 올바르게 구성하면, 각 로케일별로 경로가 다를 때 민감한 페이지가 검색 엔진에 인덱싱되는 것을 방지할 수 있습니다.

      src/app/robots.ts
      import type { MetadataRoute } from "next";import { locales, defaultLocale } from "@/i18n";const origin = "https://example.com";// 모든 로케일에 대한 경로 생성 (예: /admin, /fr/admin, /es/admin)const withAllLocales = (path: string) => [  path,  ...locales    .filter((locale) => locale !== defaultLocale)    .map((locale) => "/" + locale + path),];export default function robots(): MetadataRoute.Robots {  const disallow = [    ...withAllLocales("/dashboard"),    ...withAllLocales("/admin"),  ];  return {    rules: { userAgent: "*", allow: ["/"], disallow },    host: origin,    sitemap: origin + "/sitemap.xml",  };}

    14. 로케일 라우팅을 위한 프록시 설정

      선택사항

      사용자의 선호 로케일을 자동으로 감지하고 적절한 로케일 접두사가 붙은 URL로 리디렉션하는 프록시를 만드세요. next-intl은 이를 자동으로 처리하는 편리한 프록시 함수를 제공합니다.

      프록시는 사용자가 사이트를 방문할 때 자동으로 선호하는 언어로 리디렉션되도록 보장합니다. 또한 사용자의 선호도를 저장하여 향후 방문 시 사용자 경험을 향상시킵니다.

      src/proxy.ts
      import { proxy } from "@/i18n";// 미들웨어는 라우트 이전에 실행되어 로케일 감지 및 라우팅을 처리합니다.// localeDetection: true는 Accept-Language 헤더를 사용하여 로케일을 자동 감지합니다.export default proxy;export const config = {  // API, Next 내부, 정적 자산은 건너뜁니다.  // 정규식: api, _next로 시작하거나 점(.)이 포함된 경로(파일)를 제외한 모든 경로와 매칭됩니다.  matcher: ["/((?!api|_next|.*\\..*).*)"],};

    15. 로케일에 대한 TypeScript 타입 설정

      선택사항

      TypeScript 설정은 키에 대한 자동완성과 타입 안전성을 제공하는 데 도움이 됩니다.

      프로젝트 루트에 global.ts 파일을 생성하고 다음 코드를 추가할 수 있습니다:

      global.ts
      import type { locales } from "@/i18n";type Messages = {  common: typeof import("./locales/en/common.json");  home: typeof import("./locales/en/home.json");  about: typeof import("./locales/en/about.json");  // ... 향후 JSON 파일도 여기에 추가해야 합니다};declare module "next-intl" {  interface AppConfig {    Locale: (typeof locales)[number];    Messages: Messages;  }}

      이 코드는 모듈 확장(Module Augmentation)을 사용하여 locales와 messages를 next-intl의 AppConfig 타입에 추가합니다.

    16. Intlayer를 사용하여 번역 자동화하기

      선택사항

      Intlayer는 애플리케이션의 현지화 과정을 지원하기 위해 설계된 무료이자 오픈 소스 라이브러리입니다. next-intl이 번역 로딩과 관리를 담당하는 반면, Intlayer는 번역 워크플로우를 자동화하는 데 도움을 줍니다.

      번역을 수동으로 관리하는 것은 시간 소모가 크고 오류가 발생하기 쉽습니다. Intlayer는 번역 테스트, 생성 및 관리를 자동화하여 시간을 절약하고 애플리케이션 전반에 걸쳐 일관성을 보장합니다.

      Intlayer는 다음을 가능하게 합니다:

      • 코드베이스 내 원하는 위치에 콘텐츠 선언하기
        Intlayer는 .content.{ts|js|json} 파일을 사용하여 코드베이스 내 원하는 위치에 콘텐츠를 선언할 수 있게 합니다. 이를 통해 콘텐츠를 더 잘 조직할 수 있으며, 코드베이스의 가독성과 유지보수성을 향상시킵니다.

      • 누락된 번역 테스트하기
        Intlayer는 CI/CD 파이프라인이나 단위 테스트에 통합할 수 있는 테스트 기능을 제공합니다. 번역 테스트에 대해 자세히 알아보세요.

      • 번역 자동화 Intlayer는 번역을 자동화할 수 있는 CLI와 VSCode 확장 기능을 제공합니다. 이는 CI/CD 파이프라인에 통합할 수 있습니다. 번역 자동화에 대해 자세히 알아보세요. 사용자는 자신의 API 키와 원하는 AI 제공자를 사용할 수 있습니다. 또한 상황에 맞는 번역을 제공하므로, 내용 채우기를 참고하세요.

      • 외부 콘텐츠 연결 Intlayer는 외부 콘텐츠 관리 시스템(CMS)에 콘텐츠를 연결할 수 있도록 합니다. 이를 최적화된 방식으로 가져와 JSON 리소스에 삽입할 수 있습니다. 외부 콘텐츠 가져오기에서 자세히 알아보세요.

      • 비주얼 에디터
        Intlayer는 비주얼 에디터를 사용하여 콘텐츠를 편집할 수 있는 무료 비주얼 에디터를 제공합니다. 번역 비주얼 편집에서 자세히 알아보세요.

      그리고 더 많은 기능들이 있습니다. Intlayer가 제공하는 모든 기능을 확인하려면 Intlayer의 관심사 문서를 참조하세요.

    next-i18next로 i18nnext-i18next 자동화

    댓글

    아직 댓글이 없습니다. 첫 번째로 의견을 나눠보세요.

    관련 게시물

    Intlayer와 next-i18next

    포괄적인 Next.js 국제화 솔루션을 위한 Intlayer와 next-i18next 통합

    Aymeric PINEAU

    Intlayer와 vue-i18n

    포괄적인 Vue.js 국제화 솔루션을 위해 Intlayer를 vue-i18n과 통합하기

    Aymeric PINEAU

    국제화란? 정의와 도전

    웹사이트를 국제화하는 이유를 알아보세요. 검색 엔진을 부스트 하고 사용자 경험을 향상시키고 전세계 방위를 확장하는 키 원칙을 배우세요.

    Aymeric PINEAU

    react-i18next vs react-intl vs Intlayer

    React 앱의 국제화(i18n)를 위해 react-i18next를 next-intl 및 Intlayer와 통합하기

    Aymeric PINEAU

    최근 게시물

    next-i18next를 사용하여 Next.js 애플리케이션 국제화하는 방법 - 완전한 번역 가이드: Translate Next.js 16 with next-i18next — App Router Setup

    번들 크기, SEO, 성능 및 유지보수성을 위한 최고의 솔루션. 2026년에 Next.js 16 웹사이트를 다국어로 만드세요, LLM 번역, Agent Skills & MCP.

    Aymeric PINEAU

    Intlayer와 next-i18next

    포괄적인 Next.js 국제화 솔루션을 위한 Intlayer와 next-i18next 통합

    Aymeric PINEAU

    Intlayer와 vue-i18n

    포괄적인 Vue.js 국제화 솔루션을 위해 Intlayer를 vue-i18n과 통합하기

    Aymeric PINEAU

    next-i18next vs next-intl vs Intlayer - 완전한 번역 가이드: next-i18next vs next-intl vs Intlayer: 2026 Comparison

    번들 크기, SEO, 성능 및 유지보수성을 위한 최고의 솔루션. 2026년에 Next.js 웹사이트를 다국어로 만드세요, LLM 번역, Agent Skills & MCP.

    Aymeric PINEAU