Next.js 국제화(i18n) 경험 공유

1. 배경

2. 국제화와 지역화

국제화(Internationalization, i18n)

현지화(Localization, l10n)

요약

• 국제화(i18n): 글로벌 시장을 지원할 수 있도록 제품을 설계하고 개발하는 준비 과정. (예: 유니코드 지원, 날짜 및 텍스트 방향 처리)

• 지역화(l10n): 특정 언어 및 문화에 맞는 콘텐츠를 번역하고 최적화하는 구현 작업. (예: 텍스트 번역, 화폐 및 날짜 형식 변환)

3. Next.js를 위한 국제화 라이브러리 선택

1. 다양한 언어로 된 콘텐츠를 쉽게 관리할 수 있어야 한다.

2. 사용법이 간단하고 문서가 잘 정리되어 있어야 한다.

3. 활발하게 유지보수되고 있으며 사용자가 많아야 한다.

4. 최신 Next.js와 잘 호환되어야 한다.

라이브러리 비교

국제화 라이브러리 선택: next-intl

1. Next.js 호환성: 최신 Next.js의 서버 컴포넌트와 완벽히 호환되며, 클라이언트와 서버 양쪽을 모두 지원합니다.

2. 편리한 사용성: 사용법이 간단하고 문서가 잘 정리되어 있어 학습 곡선이 낮습니다.

3. 활발한 커뮤니티와 유지보수: Github에서 정기적인 업데이트가 이루어지고 있으며, npm trends에서도 높은 다운로드 수를 기록하고 있습니다.

4. VSCode 확장 플러그인 지원: i18n-ally 또는 sherlock으로 번역 상태를 시각적으로 확인하거나, VS Code와 통합된 GUI로 번역 메시지를 쉽게 편집할 수 있습니다.

3. next-intl을 사용하여 해결한 Next.js 국제화 문제

locale 관리

1. Dynamic routes으로 최상위 경로 세그먼트에 locale을 추가하여 관리하기
1. 예) /[locale]/products → /en/products, /ko/products

2. 도메인으로 locale을 관리하는 방식
1. 예) en.helloworld.com/products, ko.helloworld.com/product

• 단일 도메인 내에서 언어별 콘텐츠를 명확히 구분할 수 있어 SEO 관리가 용이합니다.

• Next.js의 Dynamic routes와 결합해 쉽게 구현할 수 있습니다.

• locale 변경 시 경로만 변경하면 되므로, 유지보수가 간단합니다.

경로 탐색 관리

Link (component)

import {Link} from '@/i18n/routing';
 
// 사용자가 '/ko'의 하위 경로에 있다면, '/ko/about'으로 이동함
<Link href="/about">About</Link>

// locale을 en으로 변경하여 '/en/about'으로 이동함
// (a 태그의 `hreflang`속성이 함께 설정됨)
<Link href="/about" locale="en">Switch to English</Link>

useRouter (react hook)

'use client';
 
import {useRouter} from '@/i18n/routing';
 
const router = useRouter();
 
// 사용자가 '/ko'의 하위 경로에 있다면, '/ko/about'으로 이동함
router.push('/about');
 
// locale을 en으로 변경하여 '/en/about'으로 이동함
router.replace('/about', {locale: 'en'});

번역 메시지 관리

next-intl에서 권장하는 방법

• 이렇게 하면 파일을 하나 추가하는 것으로 언어를 추가할 수 있으므로 편리합니다.

• useTranslations이라는 훅을 사용하면 현재 선택된 locale과 대응되는 json 파일에서 키에 접근하여 메시지 객체를 가져올 수 있고, 객체의 멤버에 접근하여 원하는 메시지를 가져올 수 있습니다.

{
  "ProductInfoPage": {
    "addToCartButton": "장바구니에 담기",
    "title": "상품 정보",
    //... 생략
  }
}

import { useTranslations } from "next-intl";
// ... import 생략

export default function MainPage() {
  const t = useTranslations("ProductInfoPage");
  return (
	  <div>
		  <h1>{t("title")}</h1>
		  {/* 생략 */}
		  <button>{t("addToCartButton")}</button>
	  </div>
  );
}

예외적으로 이 프로젝트에서 사용한 방법

• 우선 초기 개발 과정에서 프로젝트의 경로나 페이지의 이름이 계속 변경될 수 있어서 json의 키를 관리하기 불편하다는 점 (일반적으로 page 이름으로 키 값을 정함)

• 상황에 따라 페이지 이름이 중복될 경우 키 값으로 페이지를 사용하기 어려운 점

• 컴포넌트에서 멀리 떨어져 있는 json 파일에서 컨텐츠를 확인해야 해서 개발 시 불편하다는 점 (i18n-ally로 해결할 수 있는 문제)

• 하나의 json에 저장해야 할 내용이 너무 많고, 그에 따라 중복되는 텍스트를 관리하기 어렵다는 점

• Next.js가 경로 단위로 페이지를 생성하므로, 경로 단위로 번역 메시지를 관리할 수 있는 옵션이 필요함

• 또한 개별 컴포넌트에서도 다양한 언어를 지원해야 하므로 컴포넌트 단위로도 번역 메시지를 관리할 수 있는 기능이 필요함

• 경로나 컴포넌트가 변경되어도 json이 연동되어서 문제가 발생하지 않도록 해야 함

4. 사용하면서 느낀 next-intl의 장단점

장점

• 호환성: 최신 Next.js 15 버전과 잘 호환되므로, 새로운 Next.js 프로젝트에도 다국어 기능을 적용하기 유리합니다.

• 쉬운 사용
• Json 기반의 메시지 관리 방식으로 코드와 번역 파일을 분리하여 관리합니다
• 또한 Next.js의 라우터 API를 래핑하여 기존 Next.js 유저에게 익숙한 사용성을 제공합니다.

• 활발한 커뮤니티: github에서 자주 업데이트가 이루어지며, 공식 문서도 상세하게 정리되어 있어 학습 곡선이 낮습니다.

• VS Code 확장 프로그램: i18n-ally으로 번역 상태를 시각적으로 확인하거나, VS Code와 통합된 GUI로 번역 메시지를 쉽게 편집할 수 있습니다.

단점

• 언어 별로 하나의 json 파일에 모든 메시지를 관리하는 경우, 컴포넌트의 수가 많아지고 페이지 경로가 복잡해질 수록 유지보수하기 불리합니다.
• json 파일 하나로 모든 메시지를 관리하는 이유 중 하나는 crowdin과 같은 외부 번역 툴이 선호하는 방식이기 때문입니다. 그래서 이러한 단점은 번역 편의를 높이기 위한 트레이드 오프로 볼 수 있습니다.
• 따라서 json의 키 값을 경로 기반으로 정하거나, 또는 적절한 네이밍 컨벤션을 정해서 유지보수가 용이하도록 json 키 값을 관리할 필요가 있습니다.
• 언어 별로 여러 개의 json 파일을 만들 수 있으나, i18n-ally에서 여러 개로 분리된 json 파일을 정상적으로 인식하지 못합니다. 그래서 확장 프로그램의 편의 기능을 이용할 수 없다는 단점이 있습니다.

(부록) next-intl 예제 프로젝트: 반려 동물 소개 웹사이트

Next.js 프로젝트 생성 및 next-intl 설치

# Next.js 프로젝트 생성 명령어
npx create-next-app@latest

# next-intl 패키지 설치
npm install next-intl

필요한 파일 및 폴더 준비

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

(1) message 폴더

{
  "MainPage": {
    "pageTitle": "우리의 사랑스러운 반려 동물들",
    "description": "우리의 반려 동물들을 소개합니다.",
    //... 생략
  }
}

(2) next.config.ts

import type { NextConfig } from "next";
import createNextIntlPlugin from "next-intl/plugin";

const withNextIntl = createNextIntlPlugin();

const nextConfig: NextConfig = {
  /* config options here */
};

export default withNextIntl(nextConfig);

(3) src/i18n/routing.ts

import { defineRouting } from "next-intl/routing";
import { createNavigation } from "next-intl/navigation";

export const routing = defineRouting({
  locales: ["en", "ko", "jp"],
  defaultLocale: "ko",
});

export type Locale = (typeof routing.locales)[number];

export const { Link, redirect, usePathname, useRouter, getPathname } =
  createNavigation(routing);

• routing 객체: middleware에서 사용할 라우팅 설정입니다. 지원할 locale 목록과 기본 locale을 지정합니다.

• Locale: 타입 검사를 하기 위해 만든 locale 타입입니다. 필수는 아닙니다.

• createNavigation: Next.js에서 제공하는 기본 라우팅 API 들을 래핑하여 반환합니다. 반환된 API는 Next.js 프로젝트 내에서 다양하게 활용될 수 있습니다.

(4) src/middleware.ts 추가

import createMiddleware from "next-intl/middleware";
import { routing } from "./i18n/routing";

export default createMiddleware(routing);

export const config = {
  // Match only internationalized pathnames
  matcher: ["/", "/(ko|en|jp)/:path*"],
};

• 만약 별도의 middleware 로직이 필요하다면, 아래와 같이 요청을 핸들링할 수 있습니다.

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
import { routing } from "./i18n/routing";

const handleI18nRouting = createMiddleware(routing);
 
export function middleware(request: NextRequest) {
	// do something
	
	return handleI18nRouting(request);
}
 
export const config = {
  // Match only internationalized pathnames
  matcher: ["/", "/(ko|en|jp)/:path*"],
};

(5) src/i18n/request.ts

import { getRequestConfig } from "next-intl/server";
import { Locale, routing } from "./routing";

export default getRequestConfig(async ({ requestLocale }) => {
  // This typically corresponds to the `[locale]` segment
  let locale = await requestLocale;

  // Ensure that a valid locale is used
  if (!locale || !routing.locales.includes(locale as Locale)) {
    locale = routing.defaultLocale;
  }

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

(6) src/app/[locale]/layout.tsx

import { Locale, routing } from "@/i18n/routing";
import { NextIntlClientProvider } from "next-intl";
import { getMessages } from "next-intl/server";
import { notFound } from "next/navigation";
// ... import 생략

export default async function RootLayout({
  children,
  params,
}: Readonly<{
  children: React.ReactNode;
  params: Promise<{ locale: Locale }>; // Next.js 15에서는 Promise로 params를 받아야 합니다.
}>) {
  const locale = (await params).locale;

  // Ensure that the incoming `locale` is valid
  if (!routing.locales.includes(locale as Locale)) {
    notFound();
  }

  const messages = await getMessages();

  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}

(7) src/app/[locale]/page.tsx

• useTranslations 훅을 사용하여 현재 locale 에 맞는 텍스트를 json에서 가져옵니다.

• json 속성에서 하위 속성에 접근할 때 .(점)을 사용합니다. 예를 들어 강아지 설명을 가져오려면 “pets.dot.description”이라는 키워드를 사용합니다. 오브젝트 멤버에 접근하는 것과 유사한데 큰따옴표를 붙여야 한다는 점이 특징입니다.

import { useTranslations } from "next-intl";
// ... import 생략

export default function MainPage() {
  const t = useTranslations("MainPage");
  return (
    <div className="h-dvh flex flex-col items-center justify-between">
      {/* 생략 */}
        <section className="w-full text-center p-4">
          <h1 className="text-3xl font-bold">{t("pageTitle")}</h1>
          <p>{t("description")}</p>
        </section>
        <section className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
          <PetCard
            name={t("pets.dog.name")}
            description={t("pets.dog.description")}
            imageUrl={dogImageUrl}
          />
          {/* 생략 */}
        </section>
      </main>
      {/* 생략 */}
    </div>
  );
}

드롭 다운 입력을 사용하여 locale 변경하기

• useLocale 훅으로 현재 locale 값을 가져올 수 있습니다. 참고로 next-intl의 useLocale은 서버 컴포넌트에서도 사용할 수 있습니다.

• usePathname 훅으로 [locale] 세그먼트를 제외한 현재 경로를 가져올 수 있습니다. i18n/routing.ts 파일에서 가져온 것임에 유의합니다.

• useRouter 훅으로 경로를 이동하거나, locale을 변경할 수 있습니다. i18n/routing.ts 파일에서 가져온 것임에 유의합니다.

"use client";

import { usePathname, useRouter } from "@/i18n/routing";
import { useLocale } from "next-intl";

export default function LocaleDropdown() {
  const locale = useLocale();
  const pathname = usePathname();
  const router = useRouter();

  const handleChange = (e: React.ChangeEvent<HTMLSelectElement>) => {
    const locale = e.target.value;
    router.push({ pathname }, { locale });
  };

  return (
    <select
      value={locale}
      onChange={handleChange}
      className="border rounded p-1"
    >
      <option value="ko">한국어</option>
      <option value="en">English</option>
      <option value="jp">日本語</option>
    </select>
  );
}

결과

4. next-intl 사용 팁

VSCode 확장 플러그인: i18n-ally

• json에 저장된 텍스트 메시지를 코드 상에 표시하고, 커서를 호버하면 바로 번역 또는 편집하는 GUI를 띄우는 기능

• 미리 볼 수 있는 메시지의 locale을 전환하는 기능

• 하드코딩된 텍스트를 json으로 추출하는 기능

• 번역 메시지를 일괄적으로 관리하고 상태를 확인할 수 있는 탭

next-intl의 navigation API 사용하기

Navigation APIs – Internationalization (i18n) for Next.js

Internationalization (i18n) for Next.js

https://next-intl.dev/docs/routing/navigation

notFound 페이지 커스텀

Internationalization in Next.js error files – Internationalization (i18n) for Next.js

Internationalization (i18n) for Next.js

https://next-intl.dev/docs/environments/error-files