ReactNextCentral

국제화

Published on
국제화 라우팅 및 지역화된 콘텐츠를 통해 다양한 언어 지원을 추가합니다.
Table of Contents

Next.js는 여러 언어를 지원하기 위해 콘텐츠의 라우팅 및 렌더링을 구성할 수 있게 해줍니다. 다양한 지역에 맞게 사이트를 적용하려면 번역된 콘텐츠(지역화) 및 국제화된 라우트가 필요합니다.

용어 설명

Locale: 언어 및 형식 지정 기본 설정에 대한 식별자입니다. 이는 사용자의 선호 언어와 그들의 지리적 지역을 포함할 수 있습니다.

  • en-US: 미국에서 사용되는 영어
  • nl-NL: 네덜란드에서 사용되는 네덜란드어
  • nl: 지역 특정이 아닌 네덜란드어
한국어 설정

Next.js에서 대한민국에서 사용하는 한국어를 설정하기 위해서는 ko-KR를 사용하면 됩니다.

다국어 지원과 국제화(i18n)을 Next.js 프로젝트에 적용하려면, 다음과 같은 단계를 따르면 됩니다:

  1. next.config.js 파일에서 i18n 설정을 추가하세요.
module.exports = {
  i18n: {
    locales: ['ko-KR', 'en-US'],  // 여러 언어를 지원한다면 배열에 추가
    defaultLocale: 'ko-KR',
  },
}
  1. 여기서 locales는 지원하는 언어 목록입니다. 필요한 경우 다른 언어 코드를 추가할 수 있습니다. defaultLocale은 기본 언어를 설정하는 부분입니다. 이 예제에서는 대한민국에서 사용하는 한국어인 ko-KR를 기본으로 설정했습니다.
  2. 이 설정을 마치면 Next.js가 자동으로 각 언어별로 라우팅을 처리합니다. 예를 들면, /en-US/about는 영어로 된 "about" 페이지로 이동하고, /ko-KR/about는 한국어로 된 "about" 페이지로 이동합니다.
  3. 각 언어에 따른 문자열을 제공하려면, 예를 들어 locales 폴더 내에 각 언어별 폴더를 만들고 그 안에 번역된 문자열을 관리하는 방법 등 다양한 방법이 있습니다. 번역 라이브러리(예: next-i18next, react-intl 등)를 사용하여 이를 보다 효율적으로 관리할 수 있습니다.

이렇게 설정하면 Next.js에서 대한민국에서 사용하는 한국어 설정을 적용할 수 있습니다.

라우팅 개요

브라우저에서 사용자의 언어 선호도를 사용하여 어떤 로케일을 사용할 것인지 결정하는 것이 권장됩니다. 선호하는 언어를 변경하면 어플리케이션으로의 Accept-Language 헤더가 수정됩니다.

예를 들어, 다음 라이브러리들을 사용하여 들어오는 Request를 확인하여 Headers, 지원할 로케일 및 기본 로케일을 기반으로 어떤 로케일을 선택할 것인지 결정할 수 있습니다.

middleware.js
import { match } from '@formatjs/intl-localematcher'
import Negotiator from 'negotiator'

let headers = { 'accept-language': 'en-US,en;q=0.5' }
let languages = new Negotiator({ headers }).languages()
let locales = ['en-US', 'nl-NL', 'nl']
let defaultLocale = 'en-US'

match(languages, locales, defaultLocale) // -> 'en-US'

라우팅은 서브 경로(/fr/products) 또는 도메인(my-site.fr/products)을 통해 국제화될 수 있습니다. 이 정보를 통해 사용자를 로케일을 기반으로 Middleware 내에서 리디렉션할 수 있습니다.

middleware.js
import { NextResponse } from 'next/server'

let locales = ['en-US', 'nl-NL', 'nl']

// 선호하는 로케일을 가져옵니다. 위와 유사하게 혹은 라이브러리를 사용하여
function getLocale(request) { ... }

export function middleware(request) {
  // 경로에 지원하는 로케일이 있는지 확인합니다
  const pathname = request.nextUrl.pathname
  const pathnameIsMissingLocale = locales.every(
    (locale) => !pathname.startsWith(`/${locale}/`) 
        && pathname !== `/${locale}`
  )

  // 로케일이 없다면 리디렉션합니다
  if (pathnameIsMissingLocale) {
    const locale = getLocale(request)

    // 예: 들어오는 요청이 /products 일 경우
    // 새 URL은 이제 /en-US/products 입니다
    return NextResponse.redirect(
      new URL(`/${locale}/${pathname}`, request.url)
    )
  }
}

export const config = {
  matcher: [
    // 모든 내부 경로(_next) 건너뛰기
    '/((?!_next).*)',
    // 선택적: 루트(/) URL에서만 실행
    // '/'
  ],
}

마지막으로, app/ 안의 모든 특별한 파일들이 app/[lang] 아래에 중첩되도록 합니다. 이를 통해 Next.js 라우터는 라우트 내의 다양한 로케일을 동적으로 처리하고 모든 레이아웃 및 페이지에 lang 매개변수를 전달할 수 있습니다. 예를 들면:

app/[lang]/page.js
// 현재 로케일에 접근할 수 있습니다
// 예: /en-US/products -> `lang`은 "en-US" 입니다
export default async function Page({ params: { lang } }) {
  return ...
}

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

지역화 (Localization)

사용자의 선호 로케일에 기반하여 표시되는 내용을 변경하는 것, 즉 지역화는 Next.js에만 특정한 것이 아닙니다. 아래에서 설명하는 패턴은 어떤 웹 애플리케이션에서도 동일하게 작동합니다.

예를 들어, 애플리케이션 내에서 영어와 네덜란드어 콘텐츠 모두를 지원하려고 한다고 가정해봅시다. 우리는 키에서 지역화된 문자열로의 매핑을 제공하는 두 개의 다른 "사전"을 유지할 수 있습니다. 예를 들면:

dictionaries/en.json
{
  "products": {
    "cart": "Add to Cart"
  }
}
dictionaries/nl.json
{
  "products": {
    "cart": "Toevoegen aan Winkelwagen"
  }
}

요청된 로케일의 번역을 불러오기 위해 getDictionary 함수를 생성할 수 있습니다:

app/[lang]/dictionaries.js
import 'server-only'

const dictionaries = {
  en: () => 
    import('./dictionaries/en.json').then((module) => module.default),
  nl: () => 
    import('./dictionaries/nl.json').then((module) => module.default),
}

export const getDictionary = async (locale) => dictionaries[locale]()

현재 선택된 언어를 기반으로 레이아웃이나 페이지 내에서 사전을 가져올 수 있습니다.

app/[lang]/page.js
import { getDictionary } from './dictionaries'

export default async function Page({ params: { lang } }) {
  const dict = await getDictionary(lang) // en
  // Add to Cart
  return <button>{dict.products.cart}</button> 
}

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

정적 생성 (Static Generation)

주어진 로케일 집합에 대한 정적 라우트를 생성하기 위해, 어떤 페이지나 레이아웃에서도 generateStaticParams를 사용할 수 있습니다. 예를 들면, 루트 레이아웃에서 전역적으로 사용될 수 있습니다:

app/[lang]/layout.js
export async function generateStaticParams() {
  return [{ lang: 'en-US' }, { lang: 'de' }]
}

export default function Root({ children, params }) {
  return (
    <html lang={params.lang}>
      <body>{children}</body>
    </html>
  )
}

참고 자료