Internationalization(국제화)

Next.js를 사용하면 여러 언어를 지원하도록 콘텐츠 라우팅 및 렌더링을 구성할 수 있습니다. 사이트를 다양한 로캘에 맞게 조정하려면 번역된 콘텐츠(로컬라이제이션)와 국제화된 경로가 포함됩니다.

1. Terminology(용어)

Locale(현지의): 언어 및 서식 기본 설정 집합에 대한 식별자입니다. 여기에는 일반적으로 사용자가 선호하는 언어와 해당 지역의 언어가 포함됩니다.

en-US: 미국에서 사용되는 영어
nl-NL: 네덜란드에서 사용되는 네덜란드어
nl: 네덜란드어, 특정 지역 없음

2. Routing Overview

브라우저에서 사용자의 언어 기본 설정을 사용하여 사용할 Locale을 선택하는 것이 좋습니다. 기본 언어를 변경하면 애플리케이션으로 들어오는 Accept-Language 헤더가 수정됩니다.

예를 들어, 다음 라이브러리를 사용하면 수신 요청을 살펴보고 헤더, 지원하려는 Locale 및 기본 Locale에 따라 선택할 Locale을 결정할 수 있습니다.

middleware.js

1import { match } from '@formatjs/intl-localematcher'
2import Negotiator from 'negotiator'
3
4let headers = { 'accept-language': 'en-US,en;q=0.5' }
5let languages = new Negotiator({ headers }).languages()
6let locales = ['en-US', 'nl-NL', 'nl']
7let defaultLocale = 'en-US'
8
9match(languages, locales, defaultLocale) // -> 'en-US'

라우팅은 하위 경로(/fr/products) 또는 도메인(my-site.fr/products)을 통해 국제화할 수 있습니다. 이 정보를 통해 이제 미들웨어 내부의 Locale에 따라 사용자를 리디렉션할 수 있습니다.

middleware.js

1
2let locales = ['en-US', 'nl-NL', 'nl']
3
4// Get the preferred locale, similar to the above or using a library
5function getLocale(request) { ... }
6
7export function middleware(request) {
8  // Check if there is any supported locale in the pathname
9  const { pathname } = request.nextUrl
10  const pathnameHasLocale = locales.some(
11    (locale) => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`
12  )
13
14  if (pathnameHasLocale) return
15
16  // Redirect if there is no locale
17  const locale = getLocale(request)
18  request.nextUrl.pathname = `/${locale}${pathname}`
19  // e.g. incoming request is /products
20  // The new URL is now /en-US/products
21  return Response.redirect(request.nextUrl)
22}
23
24export const config = {
25  matcher: [
26    // Skip all internal paths (_next)
27    '/((?!_next).*)',
28    // Optional: only run on root (/) URL
29    // '/'
30  ],
31}

마지막으로 app/ 내부의 모든 특수 파일이 app/[lang] 아래에 중첩되도록 합니다. 이렇게 하면 Next.js 라우터가 라우트에서 다양한 Locale을 동적으로 처리하고, 모든 레이아웃과 페이지에 lang 매개 변수를 전달할 수 있습니다.

예를 들어:

app/[lang]/page.js

1// You now have access to the current locale
2// e.g. /en-US/products -> `lang` is "en-US"
3export default async function Page({ params: { lang } }) {
4  return ...
5}

루트 레이아웃은 새 폴더에 중첩할 수도 있습니다. (e.g. app/[lang]/layout.js)

3. Localization(지역화)

사용자가 선호하는 Locale 또는 현지화에 따라 표시되는 콘텐츠를 변경하는 것은 Next.js에만 국한된 것이 아닙니다. 아래에 설명된 패턴은 모든 웹 애플리케이션에서 동일하게 작동합니다.

애플리케이션 내에서 영어와 네덜란드어 콘텐츠를 모두 지원한다고 가정해 보겠습니다. 일부 키에서 현지화된 문자열로의 매핑을 제공하는 객체인 두 개의 서로 다른 ‘사전(dictionaries)‘을 유지할 수 있습니다. 예를 들어:

dictionaries/en.json

1{
2  "products": {
3    "cart": "Add to Cart"
4  }
5}

dictionaries/nl.json

1{
2  "products": {
3    "cart": "Toevoegen aan Winkelwagen"
4  }
5}

그런 다음 getDictionary 함수를 만들어 요청된 locale에 대한 번역을 로드할 수 있습니다:

app/[lang]/dictionaries.js

1import 'server-only'
2
3const dictionaries = {
4  en: () => import('./dictionaries/en.json').then(module => module.default),
5  nl: () => import('./dictionaries/nl.json').then(module => module.default),
6}
7
8export const getDictionary = async locale => dictionaries[locale]()

현재 선택된 언어가 주어지면, 레이아웃이나 페이지 내에서 사전을 가져올 수 있습니다.

app/[lang]/page.js

1import { getDictionary } from './dictionaries'
2
3export default async function Page({ params: { lang } }) {
4  const dict = await getDictionary(lang) // en
5  return <button>{dict.products.cart}</button> // Add to Cart
6}

app/ 디렉토리의 모든 레이아웃과 페이지는 기본적으로 서버 컴포넌트를 사용하므로, 번역 파일의 크기가 클라이언트 측 JavaScript 번들 크기에 영향을 미치는 것에 대해 걱정할 필요가 없습니다. 이 코드는 서버에서만 실행되며 결과 HTML만 브라우저로 전송됩니다.

4. Static Generation(정적 생성)

지정된 locales 집합에 대한 정적 경로를 생성하려면 페이지 또는 레이아웃에 generateStaticParams를 사용할 수 있습니다. 예를 들어 루트 레이아웃에서 전역으로 사용할 수 있습니다:

app/[lang]/layout.js

1export async function generateStaticParams() {
2  return [{ lang: 'en-US' }, { lang: 'de' }]
3}
4
5export default function Root({ children, params }) {
6  return (
7    <html lang={params.lang}>
8      <body>{children}</body>
9    </html>
10  )
11}

5. Resources(자원)

13-Middleware 01-데이터 가져오기, 캐싱 및 유효성 재검사