Как реализовать интернационализацию в приложении Next.js, использующем App Router

По мере того как мир становится более глобальным, для веб-разработчиков всё важнее создавать приложения, которые могут обслуживать пользователей из разных стран и культур. Один из ключевых способов этого достичь — международная локализация (i18n), которая позволяет адаптировать ваше приложение к разным языкам, валютам и форматам дат.

В этой статье мы рассмотрим, как добавить международную локализацию в ваше React Next.js приложение с использованием серверного рендеринга. TL;DR: Полный пример смотрите здесь.

Это руководство предназначено для приложений Next.js, использующих App Router.
Если вы используете Pages Router, смотрите это руководство.

Шаг 1: Установите библиотеку i18n

Чтобы реализовать интернационализацию в вашем приложении Next.js, сначала выберем библиотеку i18n. Существует несколько популярных библиотек, включая next-intl. В этом примере мы будем использовать TacoTranslate.

TacoTranslate автоматически переводит ваши строки на любой язык с помощью передовых технологий ИИ и избавляет вас от утомительного управления JSON-файлами.

Давайте установим её с помощью npm в вашей терминале:

npm install tacotranslate

Шаг 2: Создайте бесплатную учетную запись TacoTranslate

Теперь, когда модуль установлен, пришло время создать аккаунт TacoTranslate, проект перевода и соответствующие API ключи. Создайте аккаунт здесь. Это бесплатно и не требует добавления кредитной карты.

В интерфейсе приложения TacoTranslate создайте проект и перейдите на вкладку его API ключей. Создайте один ключ типа read, и один ключ типа read/write. Мы сохраним их как переменные окружения. Ключ read называют public, а ключ read/write — secret. Например, вы можете добавить их в файл .env в корне вашего проекта.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Обязательно не допускайте утечки секретного ключа API read/write в производственной среде на стороне клиента.

Мы также добавим еще две переменные окружения: 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_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

Мы скоро автоматически определим TACOTRANSLATE_API_KEY и TACOTRANSLATE_PROJECT_LOCALE.

Создание клиента в отдельном файле облегчает его повторное использование в дальнейшем. getLocales — это просто вспомогательная функция с некоторой встроенной обработкой ошибок. Теперь создайте файл с названием /app/[locale]/tacotranslate.tsx, где мы реализуем провайдер TacoTranslate.

'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] — динамический параметр.

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.

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:

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), мы будем использовать секретный API-ключ read/write для того, чтобы новые строки отправлялись на перевод.

Чтобы обеспечить корректную работу маршрутизации и перенаправлений, нам нужно создать файл с именем /middleware.ts. Используя Middleware, мы можем перенаправлять пользователей на страницы, отображаемые на их предпочитаемом языке.

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);
}

Обязательно настройте matcher в соответствии с документацией по Middleware Next.js.

На клиенте вы можете изменить cookie-файл locale, чтобы изменить предпочитаемый пользователем язык. Пожалуйста, смотрите полный пример кода для идей о том, как это сделать!

Шаг 5: Разверните и протестируйте!

Мы закончили! Ваше React-приложение теперь будет автоматически переводиться, когда вы добавляете любые строки в компонент Translate. Обратите внимание, что создавать новые строки для перевода смогут только среды с разрешениями read/write по ключу API. Мы рекомендуем иметь закрытую и защищённую staging-среду, где вы сможете тестировать ваше production-приложение с таким ключом API, добавляя новые строки перед запуском в продакшн. Это предотвратит кражу вашего секретного ключа API и потенциальное раздувание вашего проекта переводов за счёт добавления новых, не связанных строк.

Обязательно ознакомьтесь с полным примером в нашем профиле на GitHub. Там вы также найдете пример того, как это сделать с использованием Pages Router! Если у вас возникнут какие-либо проблемы, не стесняйтесь связаться с нами, и мы с радостью поможем.

TacoTranslate позволяет вам автоматически локализовать ваши React-приложения быстро на любой язык и с любого языка. Начните сегодня!