App Router를 사용하는 Next.js 애플리케이션에서 국제화(i18n) 구현 방법

React 애플리케이션을 더욱 접근성 높게 만들고 국제화(i18n)를 통해 새로운 시장에 진출하세요.

세계가 점점 더 글로벌화됨에 따라 웹 개발자들이 다양한 국가와 문화의 사용자를 대상으로 하는 애플리케이션을 구축하는 것이 점점 더 중요해지고 있습니다. 이를 달성하는 주요 방법 중 하나는 국제화(i18n)를 통해 애플리케이션을 다양한 언어, 통화 및 날짜 형식에 맞게 조정하는 것입니다.

이 글에서는 서버사이드 렌더링과 함께 React Next.js 애플리케이션에 국제화를 추가하는 방법을 살펴보겠습니다. TL;DR: 전체 예제는 여기를 참조하세요.

이 가이드는 App Router를 사용하는 Next.js 애플리케이션을 위한 것입니다.
만약 Pages Router를 사용하고 있다면, 대신 이 가이드를 참조하세요.

1단계: i18n 라이브러리 설치하기

Next.js 애플리케이션에서 국제화를 구현하려면 먼저 i18n 라이브러리를 선택해야 합니다. 여러 인기 있는 라이브러리가 있으며, 그중에는 next-intl도 포함되어 있습니다. 하지만 이 예제에서는 TacoTranslate를 사용할 것입니다.

TacoTranslate는 최첨단 AI를 사용하여 문자열을 자동으로 모든 언어로 번역해 주며, JSON 파일 관리의 번거로움에서 해방시켜 줍니다.

터미널에서 npm을 사용하여 설치해 보겠습니다:

npm install tacotranslate

2단계: 무료 TacoTranslate 계정을 만드세요

모듈을 설치했으니 이제 TacoTranslate 계정, 번역 프로젝트, 그리고 관련 API 키를 생성할 차례입니다. 여기에서 계정을 생성하세요. 무료이며, 신용카드 등록이 필요하지 않습니다.

TacoTranslate 애플리케이션 UI 내에서 프로젝트를 생성하고, API 키 탭으로 이동하세요. read 키 하나와 read/write 키 하나를 생성합니다. 이 키들은 환경 변수로 저장할 것입니다. read 키는 public 키라고 부르며, read/write 키는 secret 키입니다. 예를 들어, 프로젝트 루트의 .env 파일에 추가할 수 있습니다.

.env

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

비밀 read/write API 키가 클라이언트 측 프로덕션 환경에 절대 노출되지 않도록 주의하세요.

또한 두 개의 환경 변수인 TACOTRANSLATE_DEFAULT_LOCALE과 TACOTRANSLATE_ORIGIN을 추가할 것입니다.

TACOTRANSLATE_DEFAULT_LOCALE: 기본 대체 로케일 코드입니다. 이 예제에서는 영어를 위해 en으로 설정합니다.
TACOTRANSLATE_ORIGIN: 문자열이 저장될 “폴더”로, 예를 들어 웹사이트의 URL과 같습니다. 여기에서 origins에 대해 더 읽어보세요.

.env

TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

3단계: TacoTranslate 설정하기

TacoTranslate를 애플리케이션과 통합하려면, 앞서 받은 API 키를 사용하여 클라이언트를 생성해야 합니다. 예를 들어, /tacotranslate-client.js라는 파일을 만드십시오.

/tacotranslate-client.js

const {default: createTacoTranslateClient} = require('tacotranslate');

const tacoTranslate = createTacoTranslateClient({
	apiKey:
		process.env.TACOTRANSLATE_SECRET_API_KEY ??
		process.env.TACOTRANSLATE_PUBLIC_API_KEY ??
		process.env.TACOTRANSLATE_API_KEY,
	projectLocale:
		process.env.TACOTRANSLATE_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

곧 TACOTRANSLATE_API_KEY와 TACOTRANSLATE_PROJECT_LOCALE이 자동으로 정의될 예정입니다.

클라이언트를 별도의 파일에 생성하면 나중에 다시 사용하기 쉽습니다. getLocales는 내장된 오류 처리 기능이 포함된 유틸리티 함수일 뿐입니다. 이제 /app/[locale]/tacotranslate.tsx라는 파일을 생성하여 TacoTranslate 프로바이더를 구현하겠습니다.

/app/[locale]/tacotranslate.tsx

'use client';

import React, {type ReactNode} from 'react';
import {
	type TranslationContextProperties,
	TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';

export default function TacoTranslate({
	locale,
	origin,
	localizations,
	children,
}: TranslationContextProperties & {
	readonly children: ReactNode;
}) {
	return (
		<ImportedTacoTranslate
			client={tacoTranslateClient}
			locale={locale}
			origin={origin}
			localizations={localizations}
		>
			{children}
		</ImportedTacoTranslate>
	);
}

이것이 클라이언트 컴포넌트임을 나타내는 'use client';에 주목하세요.

컨텍스트 프로바이더가 준비되었으니, /app/[locale]/layout.tsx라는 파일을 생성하세요. 이 파일은 우리 애플리케이션의 루트 레이아웃입니다. 이 경로에는 Dynamic Routes가 사용된 폴더가 있으며, 여기서 [locale]은 동적 파라미터라는 점을 참고하세요.

/app/[locale]/layout.tsx

import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';

export async function generateStaticParams() {
	const locales = await tacoTranslateClient.getLocales();
	return locales.map((locale) => ({locale}));
}

type RootLayoutParameters = {
	readonly params: Promise<{locale: Locale}>;
	readonly children: ReactNode;
};

export default async function RootLayout({params, children}: RootLayoutParameters) {
	const {locale} = await params;
	const origin = process.env.TACOTRANSLATE_ORIGIN;
	const localizations = await tacoTranslateClient.getLocalizations({
		locale,
		origins: [origin /* , other origins to fetch */],
	});

	return (
		<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
			<body>
				<TacoTranslate
					locale={locale}
					origin={origin}
					localizations={localizations}
				>
					{children}
				</TacoTranslate>
			</body>
		</html>
	);
}

여기서 가장 먼저 주목할 점은 우리는 Dynamic Route 매개변수 [locale]를 사용하여 해당 언어에 대한 번역을 가져오고 있다는 것입니다. 또한, generateStaticParams는 프로젝트에 활성화된 모든 로케일 코드를 미리 렌더링하도록 보장하고 있습니다.

이제, 첫 번째 페이지를 만들어 봅시다! /app/[locale]/page.tsx라는 이름의 파일을 생성하세요.

/app/[locale]/page.tsx

import React from 'react';
import {Translate} from 'tacotranslate/react';

export const revalidate = 60;
export default async function Page() {
	return (
		<Translate string="Hello, world!" />
	);
}

revalidate 변수는 Next.js에 60초 후에 페이지를 다시 빌드하여 번역을 최신 상태로 유지하도록 지시하는 변수임을 주목하세요.

4단계: 서버 사이드 렌더링 구현하기

TacoTranslate는 서버 사이드 렌더링을 지원합니다. 이는 먼저 번역되지 않은 콘텐츠가 잠깐 보이는 대신, 즉시 번역된 콘텐츠를 보여줌으로써 사용자 경험을 크게 향상시킵니다. 또한, 사용자가 보고 있는 페이지에 필요한 번역이 이미 있기 때문에 클라이언트에서 네트워크 요청을 생략할 수 있습니다.

서버 사이드 렌더링을 설정하려면 /next.config.js 파일을 생성하거나 수정하세요:

/next.config.js

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = await withTacoTranslate(
		{},
		{
			client: tacoTranslateClient,
			isProduction:
				process.env.TACOTRANSLATE_ENV === 'production' ||
				process.env.VERCEL_ENV === 'production' ||
				(!(process.env.TACOTRANSLATE_ENV || process.env.VERCEL_ENV) &&
					process.env.NODE_ENV === 'production'),
		}
	);

	// NOTE: Remove i18n from config when using the app router
	return {...config, i18n: undefined};
};

isProduction 체크를 여러분의 설정에 맞게 수정하세요. 만약 true이면, TacoTranslate는 공개 API 키를 노출합니다. 로컬, 테스트 또는 스테이징 환경(isProduction is false)에서는 새로운 문자열이 번역으로 전송되도록 비밀 read/write API 키를 사용합니다.

라우팅과 리디렉션이 예상대로 작동하도록 하려면 /middleware.ts라는 파일을 생성해야 합니다. Middleware를 사용하여 사용자를 선호하는 언어로 제공되는 페이지로 리디렉션할 수 있습니다.

/middleware.ts

import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';

export const config = {
	matcher: ['/((?!api|_next|favicon.ico).*)'],
};

export async function middleware(request: NextRequest) {
	return tacoTranslateMiddleware(tacoTranslate, request);
}

반드시 Next.js Middleware 문서에 따라 matcher를 설정하세요.

클라이언트에서는 locale 쿠키를 수정하여 사용자가 선호하는 언어를 변경할 수 있습니다. 이 방법에 대한 아이디어는 전체 예제 코드를 참고하세요!

5단계: 배포하고 테스트하세요!

완료되었습니다! 이제 Translate 컴포넌트에 문자열을 추가하면 React 애플리케이션이 자동으로 번역됩니다. API 키에 대해 read/write 권한이 있는 환경에서만 새로운 번역 문자열을 생성할 수 있다는 점을 유의하세요. 라이브로 전환하기 전에 새로운 문자열을 추가하며 프로덕션 애플리케이션을 테스트할 수 있는 닫히고 보안이 강화된 스테이징 환경을 권장합니다. 이렇게 하면 비밀 API 키가 도난당하는 것을 방지하고, 새로운 관련 없는 문자열 추가로 인해 번역 프로젝트가 불필요하게 커지는 것을 막을 수 있습니다.

반드시 GitHub 프로필의 완전한 예제를 확인하세요. 거기에서는 Pages Router를 사용하여 이 작업을 수행하는 방법에 대한 예제도 찾을 수 있습니다! 문제가 발생하면 언제든지 연락해 주세요. 기꺼이 도와드리겠습니다.

TacoTranslate는 React 애플리케이션을 빠르게 모든 언어로 자동 현지화할 수 있게 해줍니다. 지금 시작하세요!