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

세계화가 진행됨에 따라 웹 개발자들은 여러 국가와 문화의 사용자들을 수용할 수 있는 애플리케이션을 만드는 것이 점점 더 중요해지고 있습니다. 국제화(i18n)는 애플리케이션을 다양한 언어, 통화 및 날짜 형식에 맞게 조정할 수 있게 해주는 주요 방법 중 하나입니다.

이 튜토리얼에서는 서버 사이드 렌더링을 포함하여 React Next.js 애플리케이션에 국제화를 추가하는 방법을 살펴봅니다. TL;DR: 전체 예제는 여기에서 확인하세요.

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

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

Next.js 애플리케이션에 국제화(i18n)를 구현하려면 먼저 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 파일에 추가할 수 있습니다.

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과 같습니다. 여기에서 오리진에 대해 자세히 알아보세요.

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

3단계: TacoTranslate 설정하기

TacoTranslate를 애플리케이션과 통합하려면 앞서 생성한 API 키를 사용해 클라이언트를 만들어야 합니다. 예를 들어, /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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

곧 자동으로 TACOTRANSLATE_API_KEY을 정의할 예정입니다.

클라이언트를 별도의 파일에 만들어 두면 나중에 다시 사용하기가 더 쉬워집니다. 이제 커스텀 /pages/_app.tsx에서 TacoTranslate 프로바이더를 추가하겠습니다.

import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

type PageProperties = {
	origin: Origin;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, locales, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

이미 커스텀 pageProps와 _app.tsx가 있는 경우, 위의 속성과 코드를 사용해 정의를 확장하세요.

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

TacoTranslate는 번역을 서버 사이드에서 렌더링할 수 있게 해줍니다. 이렇게 하면 번역되지 않은 콘텐츠가 잠깐 보이는 현상(플래시) 대신 번역된 내용을 즉시 보여줘 사용자 경험이 크게 개선됩니다. 또한 필요한 모든 번역을 이미 가지고 있으므로 클라이언트에서의 네트워크 요청을 생략할 수 있습니다.

먼저 /next.config.js 파일을 만들거나 수정하는 것부터 시작합니다.

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

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		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'),
	});
};

환경에 맞게 isProduction 검사를 수정하세요. 만약 true이면, TacoTranslate는 공개 API 키를 표시합니다. 로컬, 테스트 또는 스테이징 환경(isProduction is false)에 있다면, 새 문자열이 번역으로 전송되도록 비밀 read/write API 키를 사용합니다.

지금까지는 Next.js 애플리케이션에 지원되는 언어 목록만 설정했습니다. 다음으로 할 일은 모든 페이지에 대한 번역을 가져오는 것입니다. 이를 위해 요구사항에 따라 getTacoTranslateStaticProps 또는 getTacoTranslateServerSideProps 중 하나를 사용하게 됩니다.

이 함수들은 세 개의 인자를 받습니다: 하나의 Next.js Static Props Context 객체, TacoTranslate 설정, 그리고 선택적인 Next.js 속성들. 참고로 revalidate는 getTacoTranslateStaticProps에서 기본적으로 60으로 설정되어 있어 번역이 최신 상태로 유지됩니다.

페이지에서 어느 한 함수를 사용하려면, 예를 들어 /pages/hello-world.tsx와 같은 페이지 파일이 있다고 가정해 보겠습니다.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

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

이제 모든 React 컴포넌트에서 문자열을 번역하기 위해 Translate 컴포넌트를 사용할 수 있습니다.

import {Translate} from 'tacotranslate/react';

function Component() {
	return <Translate string="Hello, world!"/>
}

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

이제 끝났습니다! 이제 React 애플리케이션은 Translate 컴포넌트에 문자열을 추가하면 자동으로 번역됩니다. API 키에 대한 read/write 권한이 있는 환경에서만 번역할 새 문자열을 생성할 수 있다는 점에 유의하세요. 운영 환경에서 사용하기 전에, 그러한 API 키로 프로덕션 애플리케이션을 테스트하고 라이브로 전환하기 전에 새 문자열을 추가할 수 있는 폐쇄적이고 보안된 스테이징 환경을 마련할 것을 권장합니다. 이렇게 하면 누군가가 귀하의 비밀 API 키를 도용하는 것을 막고, 관련 없는 새 문자열을 추가해 번역 프로젝트가 불필요하게 커지는 것을 방지할 수 있습니다.

저희 GitHub 프로필에 있는 전체 예제를 꼭 확인해 보세요. 거기에서 App Router을 사용하여 이를 수행하는 예제도 찾을 수 있습니다! 문제가 있으면 언제든지 문의해 주세요, 저희가 기꺼이 도와드리겠습니다.

TacoTranslate는 React 애플리케이션을 75개 이상의 언어로 신속하게 자동 현지화할 수 있게 해줍니다. 지금 시작하세요!