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

Мы также добавим ещё две переменные окружения: 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!"/>;
}

Теперь вы должны иметь возможность использовать компонент 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-приложения быстро на любой язык и обратно. Начните сегодня!