Лучшее решение для интернационализации (i18n) в приложениях Next.js

Как это работает

По мере того как мир становится всё более глобализованным, веб‑разработчикам становится всё важнее создавать приложения, которые могут обслуживать пользователей из разных стран и культур. Одним из ключевых способов добиться этого является интернационализация (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-ключ. Если мы находимся в локальной, тестовой или стейджинговой среде (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: Разверните и протестируйте!

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

Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the App Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.

TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!