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

До сих пор мы настроили приложение 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 можно создавать новые строки для перевода. Рекомендуется иметь закрытую и защищённую тестовую среду, где вы можете тестировать ваше продуктивное приложение с таким ключом API, добавляя новые строки перед запуском. Это предотвратит кражу вашего секретного ключа API и возможное разрастание вашего проекта перевода за счёт добавления новых, не связанных строк.

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

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