Next.js(Pages Router) v16에서 로케일 기반 라우팅 구현 방법

문제

다국어 애플리케이션을 구축할 때, 한 가지 근본적인 결정이 모든 것을 좌우합니다: 애플리케이션이 어떤 언어를 표시할지 어떻게 알 수 있을까요? 명시적인 메커니즘이 없으면 /about URL은 모호해집니다—어떤 언어의 콘텐츠든 나타낼 수 있습니다. 사용자는 특정 언어 버전에 대한 링크를 공유할 수 없으며, 검색 엔진은 어떤 버전이 어떤 대상에 속하는지 이해하는 데 어려움을 겪습니다. 이러한 모호성은 특정 언어로 된 콘텐츠를 식별하거나 북마크할 명확한 방법이 없기 때문에 사용자 경험과 SEO 모두에 문제를 야기합니다.

솔루션

Next.js의 내장 i18n 라우팅 지원을 구성하여 URL 경로에 언어 식별자를 직접 넣으세요. Next.js 구성에서 지원하려는 로케일과 기본 로케일을 선언하세요. Next.js는 자동으로 라우팅을 처리하여 /fr/about 및 /nl-NL/about와 같은 경로를 사용할 수 있게 하며, 기본 로케일에는 접두사가 없습니다. 이를 통해 모든 경로가 특정 언어에 고유하게 되어 사용자와 검색 엔진 모두에게 모호성이 제거됩니다.

단계

1. next.config.js에 i18n 구성 추가

next.config.js 파일에 i18n 구성을 추가하여 애플리케이션이 지원하는 로케일을 선언하세요.

module.exports = {
  i18n: {
    locales: ["en-US", "fr", "nl-NL"],
    defaultLocale: "en-US",
  },
};

로케일은 UTS 로케일 식별자로, 로케일을 정의하기 위한 표준화된 형식이며 일반적으로 대시로 구분된 언어, 지역 및 스크립트로 구성됩니다. defaultLocale은 로케일 접두사가 없는 경로를 방문할 때 사용됩니다.

2. 페이지에서 로케일 정보 액세스

페이지 컴포넌트에서 useRouter() 훅을 사용하여 로케일 정보에 액세스하세요.

import { useRouter } from "next/router";

export default function AboutPage() {
  const router = useRouter();
  const { locale, locales, defaultLocale } = router;

  return (
    <div>
      <h1>About Us</h1>
      <p>Current locale: {locale}</p>
    </div>
  );
}

locale 속성에는 현재 활성화된 로케일이 포함되고, locales에는 구성된 모든 로케일이 포함되며, defaultLocale에는 구성된 기본 로케일이 포함됩니다.

3. 데이터 페칭 함수에서 로케일 접근

getStaticProps 또는 getServerSideProps로 페이지를 사전 렌더링할 때 로케일 정보가 컨텍스트에 제공됩니다.

import { GetStaticProps } from "next";

export const getStaticProps: GetStaticProps = async (context) => {
  const { locale } = context;

  const messages = await import(`../messages/${locale}.json`);

  return {
    props: {
      messages: messages.default,
    },
  };
};

이를 통해 활성 로케일을 기반으로 빌드 시점 또는 요청 시점에 로케일별 데이터를 로드할 수 있습니다.

4. 로케일 간 링크

next/link를 locale prop과 함께 사용하여 다른 로케일로 전환합니다.

import Link from "next/link";

export default function LanguageSwitcher() {
  return (
    <nav>
      <Link href="/about" locale="en-US">
        English
      </Link>
      <Link href="/about" locale="fr">
        Français
      </Link>
      <Link href="/about" locale="nl-NL">
        Nederlands
      </Link>
    </nav>
  );
}

locale prop이 제공되지 않으면 클라이언트 전환 중에 현재 활성 로케일이 사용됩니다. locale prop을 사용하면 사용자가 동일한 논리적 페이지에 머무르면서 언어를 전환할 수 있습니다.

5. 모든 로케일에 대한 정적 경로 생성

getStaticPaths를 활용할 때 구성된 로케일은 컨텍스트 매개변수의 locales 아래에 제공되고 구성된 defaultLocale은 defaultLocale 아래에 제공됩니다.

import { GetStaticPaths } from "next";

export const getStaticPaths: GetStaticPaths = async (context) => {
  const { locales } = context;

  const paths = locales.flatMap((locale) => [
    { params: { slug: "getting-started" }, locale },
    { params: { slug: "advanced" }, locale },
  ]);

  return {
    paths,
    fallback: false,
  };
};

이를 통해 동적 페이지의 모든 로케일 버전이 빌드 시점에 사전 렌더링됩니다.