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

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

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

이 가이드는 Pages Router를 사용하고 있는 Next.js 애플리케이션을 위한 것입니다.
만약 App 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 파일에 추가할 수 있습니다.

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에 대해 더 읽어보세요.

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 속성들입니다. getTacoTranslateStaticProps의 revalidate가 기본값으로 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!"/>
}

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

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

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

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