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

TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

Шаг 3: Настройка TacoTranslate

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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-ключа смогут создавать новые строки для перевода. Мы рекомендуем иметь закрытую и защищённую staging-среду, где вы можете тестировать ваше production-приложение с таким API-ключом, добавляя новые строки перед запуском. Это предотвратит кражу вашего секретного API-ключа и возможное раздувание вашего проекта перевода за счёт добавления новых, не связанных строк.

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

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