Intlayer의 향후 출시 예정에 대한 알림을 받으세요
    생성:2024-12-07마지막 업데이트:2025-06-29

    Intlayer와 Next.js의 Page Router를 사용한 국제화(i18n) 시작하기

    Intlayer란 무엇인가요?

    Intlayer는 현대 웹 애플리케이션에서 다국어 지원을 간소화하기 위해 설계된 혁신적인 오픈 소스 국제화(i18n) 라이브러리입니다. Intlayer는 최신 Next.js 프레임워크와 원활하게 통합되며, 전통적인 Page Router도 포함합니다.

    Intlayer를 사용하면 다음을 할 수 있습니다:

    • 컴포넌트 수준에서 선언적 사전을 사용하여 번역을 쉽게 관리할 수 있습니다.
    • 메타데이터, 라우트 및 콘텐츠를 동적으로 현지화할 수 있습니다.
    • 자동 생성된 타입으로 TypeScript 지원을 보장하여 자동 완성 및 오류 감지를 향상시킵니다.
    • 동적 로케일 감지 및 전환과 같은 고급 기능을 활용할 수 있습니다.

    Intlayer는 Next.js 12, 13, 14, 15와 호환됩니다. Next.js App Router를 사용 중이라면 App Router 가이드를 참고하세요. Next.js 15의 경우 이 가이드를 따르세요.

    Page Router를 사용하는 Next.js 애플리케이션에서 Intlayer 설정 단계별 가이드

    1단계: 의존성 설치

    선호하는 패키지 관리자를 사용하여 필요한 패키지를 설치하세요:

    bash
    npm install intlayer next-intlayer
    • intlayer

    국제화 도구를 제공하는 핵심 패키지로, 구성 관리, 번역, 콘텐츠 선언, 트랜스파일링 및 CLI 명령어를 지원합니다.

    • next-intlayer

      Intlayer를 Next.js와 통합하는 패키지입니다. Next.js 국제화를 위한 컨텍스트 프로바이더와 훅을 제공합니다. 또한, Intlayer를 Webpack 또는 Turbopack과 통합하기 위한 Next.js 플러그인과 사용자의 선호 로케일 감지, 쿠키 관리, URL 리디렉션 처리를 위한 미들웨어도 포함하고 있습니다.

    2단계: 프로젝트 구성

    애플리케이션에서 지원하는 언어를 정의하기 위해 구성 파일을 만드세요:

    intlayer.config.ts
    import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // 여기에 다른 로케일을 추가하세요    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

    이 구성 파일을 통해 지역화된 URL, 미들웨어 리디렉션, 쿠키 이름, 콘텐츠 선언의 위치 및 확장자 설정, 콘솔에서 Intlayer 로그 비활성화 등 다양한 설정을 할 수 있습니다. 사용 가능한 모든 매개변수 목록은 구성 문서를 참조하세요.

    3단계: Next.js 구성에 Intlayer 통합하기

    Next.js 구성을 수정하여 Intlayer를 통합합니다:

    next.config.mjs
    import { withIntlayer } from "next-intlayer/server";/** @type {import('next').NextConfig} */const nextConfig = {  // 기존 Next.js 구성};export default withIntlayer(nextConfig);

    withIntlayer() Next.js 플러그인은 Intlayer를 Next.js와 통합하는 데 사용됩니다. 이 플러그인은 콘텐츠 선언 파일을 빌드하고 개발 모드에서 이를 모니터링하는 기능을 보장합니다. 또한 Webpack 또는 Turbopack 환경 내에서 Intlayer 환경 변수를 정의합니다. 추가로, 성능 최적화를 위한 별칭(alias)을 제공하며 서버 컴포넌트와의 호환성을 보장합니다.

    4단계: 로케일 감지를 위한 미들웨어 구성

    사용자의 선호 로케일을 자동으로 감지하고 처리하기 위해 미들웨어를 설정합니다:

    src/middleware.ts
    export { intlayerMiddleware as middleware } from "next-intlayer/middleware";export const config = {  matcher:    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",};

    matcher 매개변수를 애플리케이션의 경로에 맞게 조정하세요. 자세한 내용은 Next.js의 matcher 구성 문서를 참조하세요.

    5단계: 동적 로케일 경로 정의

    사용자의 로케일에 따라 현지화된 콘텐츠를 제공하기 위해 동적 라우팅을 구현합니다.

    1. 로케일별 페이지 생성:

      메인 페이지 파일 이름을 [locale] 동적 세그먼트를 포함하도록 변경합니다.

      bash
      mv src/pages/index.tsx src/pages/[locale]/index.tsx

    2. 현지화 처리를 위한 _app.tsx 업데이트:

      `_app.tsx`를 수정하여 Intlayer 프로바이더를 포함시킵니다. ```tsx fileName="src/pages/_app.tsx" codeFormat="typescript" import type { FC } from "react";

      import type { AppProps } from "next/app"; import { IntlayerClientProvider } from "next-intlayer";

    const App = FC({ Component, pageProps }) => { const { locale } = pageProps;

    return ( ); }

    export default MyApp;

    ```jsx fileName="src/pages/_app.mjx" codeFormat="esm" import { IntlayerClientProvider } from "next-intlayer"; const App = ({ Component, pageProps }) => ( <IntlayerClientProvider locale={locale}> <Component {...pageProps} /> </IntlayerClientProvider> ); export default App;

    자세한 내용은 콘텐츠 선언 가이드를 참조하세요.

    7단계: 코드에서 콘텐츠 활용하기

    애플리케이션 전반에서 콘텐츠 사전을 접근하여 번역된 콘텐츠를 표시하세요.

    src/pages/[locale]/index.tsx
    import type { FC } from "react";import { useIntlayer } from "next-intlayer";import { ComponentExample } from "@components/ComponentExample";const HomePage: FC = () => {  const content = useIntlayer("home");  return (    <div>      <h1>{content.title}</h1>      <p>{content.description}</p>      <ComponentExample />      {/* 추가 컴포넌트들 */}    </div>  );};// ... getStaticPaths 및 getStaticProps를 포함한 나머지 코드export default HomePage;

    string 속성(예: alt, title, href, aria-label)에서 번역을 사용할 때는 다음과 같이 함수 값을 호출하세요:

    jsx
    <img src={content.image.src.value} alt={content.image.value} />

    useIntlayer 훅에 대해 더 알아보려면 문서를 참조하세요.

    (선택 사항) 8단계: 메타데이터의 국제화

    페이지 제목과 같은 메타데이터를 국제화하려는 경우, Next.js 페이지 라우터에서 제공하는 getStaticProps 함수를 사용할 수 있습니다. 이 함수 내에서 getIntlayer 함수를 통해 콘텐츠를 가져와 메타데이터를 번역할 수 있습니다.

    src/pages/[locale]/metadata.content.ts
    import { type Dictionary, t } from "intlayer";import { type Metadata } from "next";const metadataContent = {  key: "page-metadata",  content: {    title: t({      en: "Create Next App",      fr: "Créer une application Next.js",      es: "Crear una aplicación Next.js",    }),    description: t({      en: "Generated by create next app",      fr: "Généré par create next app",      es: "Generado por create next app",    }),  },} satisfies Dictionary<Metadata>;export default metadataContent;
    src/pages/[locale]/index.tsx
    import { GetStaticPaths, GetStaticProps } from "next";import { getIntlayer, getMultilingualUrls } from "intlayer";import { useIntlayer } from "next-intlayer";import Head from "next/head";import type { FC } from "react";interface HomePageProps {  locale: string;  metadata: {    title: string;    description: string;  };  multilingualUrls: Record<string, string>;}const HomePage: FC<HomePageProps> = ({  metadata,  multilingualUrls,  locale,}) => {  const content = useIntlayer("page");  return (    <div>      <Head>        <title>{metadata.title}</title>        <meta name="description" content={metadata.description} />        {/* SEO를 위한 hreflang 태그 생성 */}        {Object.entries(multilingualUrls).map(([lang, url]) => (          <link key={lang} rel="alternate" hrefLang={lang} href={url} />        ))}        <link rel="canonical" href={multilingualUrls[locale]} />      </Head>      {/* 페이지 내용 */}      <main>{/* 여기에 페이지 콘텐츠를 작성하세요 */}</main>    </div>  );};export const getStaticProps: GetStaticProps<HomePageProps> = async ({  params,}) => {  const locale = params?.locale as string;  const metadata = getIntlayer("page-metadata", locale);  /**   * 각 로케일에 대한 모든 URL을 포함하는 객체를 생성합니다.   *   * 예시:   * ```ts   *  getMultilingualUrls('/about');   *   *  // 반환값   *  // {   *  //   en: '/about',   *  //   fr: '/fr/about',   *  //   es: '/es/about',   *  // }   * ```   */  const multilingualUrls = getMultilingualUrls("/");  return {    props: {      locale,      metadata,      multilingualUrls,    },  };};export default HomePage;// ... getStaticPaths를 포함한 나머지 코드

    next-intlayer에서 가져온 getIntlayer 함수는 콘텐츠를 IntlayerNode로 감싸서 반환하므로 시각적 편집기와의 통합이 가능합니다. 반면, intlayer에서 가져온 getIntlayer 함수는 추가 속성 없이 콘텐츠를 직접 반환합니다.

    또는 getTranslation 함수를 사용하여 메타데이터를 선언할 수 있습니다. 하지만 메타데이터의 번역을 자동화하고 콘텐츠를 외부화하기 위해서는 콘텐츠 선언 파일을 사용하는 것이 권장됩니다.

    src/pages/[locale]/index.tsx
    import { GetStaticPaths, GetStaticProps } from "next";import {  type IConfigLocales,  getTranslation,  getMultilingualUrls,} from "intlayer";import { useIntlayer } from "next-intlayer";import Head from "next/head";import type { FC } from "react";interface HomePageProps {  locale: string;  metadata: {    title: string;    description: string;  };  multilingualUrls: Record<string, string>;}const HomePage: FC<HomePageProps> = ({ metadata, multilingualUrls, locale }) => {  const content = useIntlayer("page");  return (    <div>      <Head>        <title>{metadata.title}</title>        <meta name="description" content={metadata.description} />        {/* SEO를 위한 hreflang 태그 생성 */}        {Object.entries(multilingualUrls).map(([lang, url]) => (          <link            key={lang}            rel="alternate"            hrefLang={lang}            href={url}          />        ))}        <link rel="canonical" href={multilingualUrls[locale]} />      </Head>      {/* 페이지 내용 */}      <main>        {/* 여기에 페이지 내용을 작성하세요 */}      </main>    </div>  );};export const getStaticProps: GetStaticProps<HomePageProps> = async ({  params}) => {  const locale = params?.locale as string;  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);  const metadata = {    title: t<string>({      en: "My title",      fr: "Mon titre",      es: "Mi título",    }),    description: t({      en: "My description",      fr: "Ma description",      es: "Mi descripción",    }),  };  const multilingualUrls = getMultilingualUrls("/");  return {    props: {      locale,      metadata,      multilingualUrls,    },  };};export default HomePage;// ... getStaticPaths를 포함한 나머지 코드

    메타데이터 최적화에 대해 더 알아보려면 공식 Next.js 문서를 참고하세요.

    (선택 사항) 9단계: 콘텐츠의 언어 변경하기

    Next.js에서 콘텐츠의 언어를 변경하려면, 권장되는 방법은 Link 컴포넌트를 사용하여 사용자를 적절한 현지화된 페이지로 리디렉션하는 것입니다. Link 컴포넌트는 페이지의 사전 로딩(prefetching)을 가능하게 하여 전체 페이지 리로드를 방지하는 데 도움이 됩니다.

    src/components/LanguageSwitcher.tsx
    import {  Locales,  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,} from "intlayer";import { useLocalePageRouter } from "next-intlayer";import { type FC } from "react";import Link from "next/link";const LocaleSwitcher: FC = () => {  const { locale, pathWithoutLocale, availableLocales } = useLocalePageRouter();  const { setLocaleCookie } = useLocaleCookie();  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <Link            href={getLocalizedUrl(pathWithoutLocale, localeItem)}            hrefLang={localeItem}            key={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={() => setLocaleCookie(localeItem)}          >            <span>              {/* 로케일 - 예: FR */}              {localeItem}            </span>            <span>              {/* 해당 로케일의 언어 - 예: Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* 현재 로케일에서의 언어 - 예: 현재 로케일이 Locales.SPANISH로 설정된 경우 Francés */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* 영어로 된 언어 - 예: French */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </Link>        ))}      </div>    </div>  );};

    대안으로 useLocale 훅에서 제공하는 setLocale 함수를 사용할 수 있습니다. 이 함수는 페이지를 미리 가져오는(prefetch) 기능을 허용하지 않으며 페이지를 새로고침합니다.

    이 경우, router.push를 사용한 리디렉션 없이 서버 측 코드만 콘텐츠의 로케일을 변경합니다.

    src/components/LocaleSwitcher.tsx
    "use client";import { useRouter } from "next/navigation";import { useLocale } from "next-intlayer";import { getLocalizedUrl } from "intlayer";// ... 나머지 코드const router = useRouter();const { setLocale } = useLocale({  onLocaleChange: (locale) => {    router.push(getLocalizedUrl(pathWithoutLocale, locale));  },});return (  <button onClick={() => setLocale(Locales.FRENCH)}>프랑스어로 변경</button>);

    useLocalePageRouter API는 useLocale과 동일합니다. useLocale 훅에 대해 자세히 알아보려면 문서를 참조하세요.

    문서 참고:

    (선택 사항) 10단계: 지역화된 링크 컴포넌트 만들기

    애플리케이션의 내비게이션이 현재 로케일을 준수하도록 하려면, 커스텀 Link 컴포넌트를 만들 수 있습니다. 이 컴포넌트는 내부 URL에 현재 언어 접두사를 자동으로 붙여줍니다. 예를 들어, 프랑스어 사용자가 "About" 페이지 링크를 클릭하면 /about 대신 /fr/about로 리디렉션됩니다.

    이 동작은 여러 가지 이유로 유용합니다:

    • SEO 및 사용자 경험: 지역화된 URL은 검색 엔진이 언어별 페이지를 올바르게 색인화하도록 도와주며, 사용자가 선호하는 언어로 콘텐츠를 제공합니다.
    • 일관성: 애플리케이션 전반에 걸쳐 지역화된 링크를 사용함으로써, 탐색이 현재 로케일 내에서 유지되어 예상치 못한 언어 전환을 방지합니다.
    • 유지보수성: 지역화 로직을 단일 컴포넌트에 중앙 집중화하여 URL 관리를 단순화하고, 애플리케이션이 성장함에 따라 코드베이스를 더 쉽게 유지보수하고 확장할 수 있습니다.

    아래는 TypeScript로 구현된 지역화된 Link 컴포넌트 예시입니다:

    src/components/Link.tsx
    "use client";import { getLocalizedUrl } from "intlayer";import NextLink, { type LinkProps as NextLinkProps } from "next/link";import { useLocale } from "next-intlayer";import { forwardRef, PropsWithChildren, type ForwardedRef } from "react";/** * 주어진 URL이 외부 링크인지 확인하는 유틸리티 함수입니다. * URL이 http:// 또는 https://로 시작하면 외부 링크로 간주합니다. */export const checkIsExternalLink = (href?: string): boolean =>  /^https?:\/\//.test(href ?? "");/** * 현재 로케일에 따라 href 속성을 조정하는 커스텀 Link 컴포넌트입니다. * 내부 링크의 경우 `getLocalizedUrl`을 사용하여 URL 앞에 로케일을 붙입니다 (예: /fr/about). * 이를 통해 네비게이션이 동일한 로케일 컨텍스트 내에서 유지되도록 보장합니다. */export const Link = forwardRef<  HTMLAnchorElement,  PropsWithChildren<NextLinkProps>>(({ href, children, ...props }, ref: ForwardedRef<HTMLAnchorElement>) => {  const { locale } = useLocale();  const isExternalLink = checkIsExternalLink(href.toString());  // 링크가 내부 링크이고 유효한 href가 제공된 경우, 지역화된 URL을 가져옵니다.  const hrefI18n: NextLinkProps["href"] =    href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;  return (    <NextLink href={hrefI18n} ref={ref} {...props}>      {children}    </NextLink>  );});Link.displayName = "Link";

    작동 방식

    • 외부 링크 감지:
      헬퍼 함수 checkIsExternalLink는 URL이 외부 링크인지 여부를 판단합니다. 외부 링크는 현지화가 필요 없으므로 변경하지 않습니다.

    • 현재 로케일 가져오기:
      useLocale 훅은 현재 로케일(예: 프랑스어의 경우 fr)을 제공합니다.

    • URL 현지화:
      내부 링크(즉, 외부 링크가 아닌 경우)에 대해서는 getLocalizedUrl을 사용하여 URL 앞에 현재 로케일을 자동으로 붙입니다. 예를 들어 사용자가 프랑스어 로케일에 있다면, href에 /about을 전달할 경우 /fr/about로 변환됩니다.

    • 링크 반환:
      이 컴포넌트는 현지화된 URL을 가진 <a> 요소를 반환하여, 네비게이션이 로케일에 맞게 일관되도록 보장합니다.

    이 Link 컴포넌트를 애플리케이션 전반에 통합하면 일관되고 언어 인식이 가능한 사용자 경험을 유지할 수 있으며, SEO와 사용성 향상에도 도움이 됩니다.

    (선택 사항) 11단계: 번들 크기 최적화

    next-intlayer를 사용할 때, 기본적으로 모든 페이지 번들에 사전이 포함됩니다. 번들 크기를 최적화하기 위해 Intlayer는 매크로를 사용하여 useIntlayer 호출을 지능적으로 대체하는 선택적 SWC 플러그인을 제공합니다. 이를 통해 실제로 사전을 사용하는 페이지의 번들에만 사전이 포함되도록 보장합니다.

    이 최적화를 활성화하려면 @intlayer/swc 패키지를 설치하세요. 설치가 완료되면 next-intlayer가 자동으로 플러그인을 감지하고 사용합니다:

    bash
    npm install @intlayer/swc --save-dev

    참고: 이 최적화는 Next.js 13 이상에서만 사용할 수 있습니다.

    참고: 이 패키지는 SWC 플러그인이 Next.js에서 아직 실험 단계이기 때문에 기본적으로 설치되지 않습니다. 향후 변경될 수 있습니다.

    TypeScript 구성

    Intlayer는 모듈 증강(module augmentation)을 사용하여 TypeScript의 이점을 활용하고 코드베이스를 더욱 견고하게 만듭니다.

    alt text

    alt text

    TypeScript 구성에 자동 생성된 타입이 포함되어 있는지 확인하세요.

    tsconfig.json
    {  // ... 기존 TypeScript 구성  "include": [    // ... 기존 TypeScript 구성    ".intlayer/**/*.ts", // 자동 생성된 타입 포함  ],}

    Git 구성

    저장소를 깔끔하게 유지하고 생성된 파일의 커밋을 방지하기 위해, Intlayer가 생성한 파일들을 무시하는 것이 권장됩니다.

    다음 내용을 .gitignore 파일에 추가하세요:

    .gitignore
    # Intlayer가 생성한 파일 무시.intlayer

    VS Code 확장 프로그램

    Intlayer와 함께 개발 경험을 향상시키기 위해 공식 Intlayer VS Code 확장 프로그램을 설치할 수 있습니다.

    VS Code 마켓플레이스에서 설치하기

    이 확장 프로그램은 다음 기능을 제공합니다:

    • 번역 키에 대한 자동 완성.
    • 누락된 번역에 대한 실시간 오류 감지.
    • 번역된 내용의 인라인 미리보기.
    • 번역을 쉽게 생성하고 업데이트할 수 있는 빠른 작업.

    확장 프로그램 사용 방법에 대한 자세한 내용은 Intlayer VS Code 확장 문서를 참조하세요.

    추가 자료

    이 가이드를 따르면 Next.js 애플리케이션에서 페이지 라우터를 사용하여 Intlayer를 효과적으로 통합할 수 있으며, 웹 프로젝트에 강력하고 확장 가능한 국제화 지원을 제공할 수 있습니다.

    더 나아가기

    더 나아가려면 비주얼 에디터를 구현하거나 CMS를 사용하여 콘텐츠를 외부화할 수 있습니다.

    문서 이력

    • 5.5.10 - 2025-06-29: 초기 이력
    Next.js 14 및 앱 라우터
    Intlayer와 React CRA
    Intlayer의 향후 출시 예정에 대한 알림을 받으세요