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

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

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

Это руководство предназначено для приложений Next.js, использующих Pages Router.
Если вы используете App 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

Никогда не раскрывайте секретный read/write API-ключ в production-окружениях на стороне клиента.

Мы также добавим ещё две переменные окружения: 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. Если мы находимся в локальной, тестовой или предрелизной (staging) среде (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!"/>;
}

Теперь вы сможете использовать компонент Translate для перевода строк во всех ваших React-компонентах.

import {Translate} from 'tacotranslate/react';

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

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

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

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

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