Лучшее решение для интернационализации (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-ключи. Создайте учетную запись здесь. Это бесплатнo и не требует добавления кредитной карты.

В интерфейсе приложения 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: Разверните и протестируйте!

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

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

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