🌐 Next.js에서 다국어 지원하기 (next-intl)

Hailey·2024년 4월 30일

next-intl

목록 보기

1/3

Next.js App Router에서 next-intl을 사용해 다국어를 지원하는 방법에 대해 알아보겠습니다.

들어가며

먼저, Next.js 공식문서 Routing > Internationalization 페이지를 살펴보면, Accept-Language 헤더와 미들웨어, json 파일 등을 사용하여 다국어를 지원하는 방법을 소개하고 있습니다.

하지만 저는 더 편리한 개발과 안정적인 서비스를 위해 외부 라이브러리를 도입하기로 결정했고, 아래와 같은 이유로 next-intl을 사용하게 되었습니다.

`next-intl`을 선택한 이유

npm trends로 비교해 보았을 때 다운로드 수가 월등히 높음.
Next.js App Router와 Server Component를 지원함.
공식문서가 잘 작성되어 있음.
설치와 사용이 간편하면서 필요한 기능을 다 제공함.

그러면 본격적으로 next-intl을 사용하는 방법을 소개하겠습니다.

설치하기 💪

Tip💡 공식문서에 방법이 잘 나와 있어서 문서를 보면서 만들어 보시고, 이해가 안 되거나 에러가 발생하는 경우에만 제 글을 참고하시면 좋을 것 같습니다.

파일 구조

먼저, 파일 구조는 아래와 같습니다.
npm i -D next-intl 커맨드로 패키지를 설치하시고, 아래의 파일과 폴더를 만들어 주세요.

├── messages (1)
│   ├── en.json
│   └── ...
├── next.config.mjs (2)
└── src
    ├── i18n.ts (3)
    ├── middleware.ts (4)
    └── app
        └── [locale]
            ├── layout.tsx (5)
            └── page.tsx (6)

1. messages

root/messages 폴더 안에 지원하실 언어마다 json 파일을 만들어 주세요.
나중에 잘 작동하는지 확인할 수 있도록 간단한 테스트 내용을 작성하시는 것도 좋습니다.

저는 이렇게 작성해 보았습니다.

// messages/en.json

{	
	"Home": {
		"title": "Hi! I'm Hailey Kim.",
		"subtitle": "I'm a front-end developer."
	}
}

// messages/ko.json

{	
	"Home": {
		"title": "안녕하세요!",
		"subtitle": "프론트엔드 개발자 김혜원입니다."
	}
}

2. next.config.mjs

원래 있던 next.config.mjs 파일에 아래의 코드를 작성해 주세요. (next.config.js 파일을 사용하신다면 공식문서를 참고해 주세요.)

// next.config.mjs

import createNextIntlPlugin from 'next-intl/plugin';

const withNextIntl = createNextIntlPlugin();

/** @type {import('next').NextConfig} */
const nextConfig = {};

export default withNextIntl(nextConfig);

3. src/i18n.ts

src 폴더 안에 만든 i18n.ts 파일에 아래의 코드를 작성해 주세요.

// src/i18n.ts

import {notFound} from 'next/navigation';
import {getRequestConfig} from 'next-intl/server';
 
// 이 부분은 다른 파일에서 임포트해 올 수 있습니다.
const locales = ['en', 'de'];
 
export default getRequestConfig(async ({locale}) => {
  if (!locales.includes(locale as any)) notFound();
 
  return {
    messages: (await import(`../messages/${locale}.json`)).default
  };
});

+ `locales`를 `config`로 관리하기 (선택 사항)

저는 위에 locales를 config 파일에 따로 담아서 관리하기로 결정했습니다.

그래서 아래와 같이 intl.config.ts(파일명은 상관없습니다)를 root에 생성해서 locales를 export 하고, i18n.ts에서 import 하도록 코드를 작성했습니다.

// intl.config.ts

export const locales: string[] = ['en', 'ko'];

// src/i18n.ts

import { notFound } from 'next/navigation';
import { getRequestConfig } from 'next-intl/server';
import { locales } from '../intl.config';

export default getRequestConfig(async ({ locale }) => {
    if (!locales.includes(locale as any)) notFound();

    return {
        messages: (await import(`../messages/${locale}.json`)).default,
    };
});

4. src/middleware.ts

src 폴더 안에 만든 middleware.ts 파일에 아래의 코드를 작성해 주세요.

// src/middleware.ts

import createMiddleware from 'next-intl/middleware';
 
export default createMiddleware({
  locales: ['en', 'ko'],
  defaultLocale: 'en'
});
 
export const config = {
  matcher: ['/', '/(en|ko)/:path*']
};

+ `locales`를 다른 파일에서 불러오는 경우

// src/middleware.ts

import createMiddleware from 'next-intl/middleware';
import { locales } from '../intl.config';

export default createMiddleware({
    locales,
    defaultLocale: locales[0],
});

export const config = {
    matcher: ['/', '/(en|ko)/:path*'],
};

config.matcher 부분도 '/(en|ko)/:path*'를 직접 쓰는 게 아니라 locales를 이용해 보려고 했지만, array.map을 사용하거나 외부에서 matcher를 만들어 사용하는 등의 방법은 모두 404 에러가 발생해서 en|ko를 직접 작성할 수밖에 없었습니다.

만약 이게 정말 싫다면, Next.js 공식문서에서 사용한 것과 같이 matcher: ['/((?!_next).*)']를 쓰는 방법도 있습니다. (실제로 해봤고, 에러 없이 잘 작동합니다.)

5. app/[locale]

src/app 안에 [locale] 폴더를 생성하고, 폴더 안에 layout.tsx와 page.tsx를 생성해 주세요. 아래의 코드를 작성해 주세요.

5-1. layout.tsx

// app/[locale]/layout.tsx

export default function LocaleLayout({
  children,
  params: {locale}
}: {
  children: React.ReactNode;
  params: {locale: string};
}) {
  return (
    <html lang={locale}>
      <body>{children}</body>
    </html>
  );
}

5-2. page.tsx

// app/[locale]/page.tsx

import {useTranslations} from 'next-intl';
 
export default function Index() {
  const t = useTranslations('Index');
  return <h1>{t('title')}</h1>;
}

+ layout.tsx에서 generateStaticParams() 사용하기 (선택 사항)

저는 아래의 코드를 작성해 static rendering이 되고(빌드 타임에 미리 생성 가능), 정해진 locale 값으로만 /[locale]에 접근할 수 있도록 설정했습니다.

// app/[locale]/layout.tsx

export const dynamicParams = false;
export function generateStaticParams() {
    return locales.map((locale) => ({ locale }));
}

결과물 ✨

잘 되는지 시험해 보기 위해 page.tsx를 다음과 같이 작성해 봤습니다.

// app/[locale]/page.tsx

import { useTranslations } from 'next-intl';

export default function Home() {
    const t = useTranslations('Home');
    return (
        <>
            <h1 className="mt-20 w-72 mx-auto">{t('title')}</h1>
            <h2 className="w-72 mx-auto">{t('subtitle')}</h2>
        </>
    );
}

아래의 시연 영상을 보시면, / 주소로 접근했을 때 바로 사용자의 브라우저 설정 언어로 (/en) redirect 되고, 그에 맞게 텍스트도 잘 렌더링 되는 것을 볼 수 있습니다. /ko로 접근하면 한국어로 잘 변환되고, 이 상태에서 다시 /로 들어가면 마지막으로 설정했던 언어를 기억해서 /ko로 redirect 되는 것을 볼 수 있습니다.

더 나아가기 🚀

위의 내용만 따라하셔도 useTranslations를 사용해 어디서든 json 파일에 작성 된 텍스트를 언어에 맞게 불러올 수 있습니다.
하지만 더 다양하게 사용하고 싶으시다면 아래 내용을 참고해 주시기 바랍니다.

Metadata에 다국어 지원하기

메타데이터도 언어에 따라 다르게 생성할 수 있습니다.
🌐 Next.js Metadata에 다국어 지원하기 (next-intl)

ICU messages 다양하게 사용하기

단순히 메세지를 그대로 불러오는 t('title') 외에도 다양한 사용 방법이 있습니다.
🌐 next-intl의 ICU messages 사용하기

Hailey

빠르게 발전하는 프론트엔드 개발자

다음 포스트