Как реализовать интернационализацию в приложении 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 вашего сайта. Подробнее об origin'ах читайте здесь.

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!"/>;
}

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

import {Translate} from 'tacotranslate/react';

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

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

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

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

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