Как реализовать интернационализацию в приложении 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-ключи из предыдущего этапа. Например, создайте файл с именем /utilities/tacotranslate.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 Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import tacoTranslate from '../utilities/tacotranslate';

type PageProperties = {
	origin: string;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

Если у вас уже есть пользовательские pageProps и _app.tsx, пожалуйста, расширьте определение с помощью свойств и кода из выше.

Шаг 4: Реализация серверной отрисовки

TacoTranslate позволяет осуществлять серверный рендеринг ваших переводов. Это значительно улучшает пользовательский опыт, поскольку переводимый контент отображается немедленно, вместо того чтобы сначала показывать мгновение непереведенного контента. Кроме того, мы можем избежать сетевых запросов на клиенте, потому что у нас уже есть все необходимые переводы.

Мы начнем с создания или изменения /next.config.js.

const tacoTranslate = require('./utilities/tacotranslate');

module.exports = async () => {
	const locales = await tacoTranslate.getLocales();
	const isProduction =
		process.env.TACOTRANSLATE_ENV === 'production' ||
		process.env.VERCEL_ENV === 'production' ||
		(!(process.env.TACOTRANSLATE_ENV || process.env.VERCEL_ENV) &&
			process.env.NODE_ENV === 'production');

	const [projectLocale] = locales;

	return {
		env: {
			TACOTRANSLATE_ORIGIN: process.env.TACOTRANSLATE_ORIGIN,
			TACOTRANSLATE_API_KEY: isProduction
				? process.env.TACOTRANSLATE_PUBLIC_API_KEY
				: process.env.TACOTRANSLATE_SECRET_API_KEY,
			TACOTRANSLATE_DEFAULT_LOCALE: isProduction ? projectLocale : undefined,
		},
		i18n: {
			defaultLocale: projectLocale,
			locales,
		},
	};
};

Обратите внимание на несколько моментов. Во-первых, мы извлекаем все языки, которые вы активировали для вашего проекта перевода. Первая строка в массиве ответа – это код локали, который вы установили для проекта.

Теперь к важной части: Определение, находимся ли мы в производственной среде. Измените isProduction проверку в соответствии с вашей настройкой. Если мы находимся в локальной, тестовой или промежуточной среде, мы должны использовать секретный read/write API ключ, чтобы убедиться, что новые строки отправляются на перевод. Если мы находимся в производственной среде, мы должны использовать публичный read ключ.

До сих пор мы только настроили приложение Next.js с перечнем поддерживаемых языков. Следующее, что мы сделаем, это получим переводы для всех ваших страниц. Сначала создайте новый файл /utilities/custom-get-static-props.ts.

import {type GetStaticPropsContext} from 'next';
import {type Origin} from 'tacotranslate';
import tacoTranslate from './tacotranslate';

export default async function customGetStaticProps(
	{
		locale = process.env.TACOTRANSLATE_DEFAULT_LOCALE,
		locales,
	}: GetStaticPropsContext,
	additionalOrigins: Origin[] = []
) {
	const origin = process.env.TACOTRANSLATE_ORIGIN;
	const origins = [origin, ...additionalOrigins];
	const localizations = await tacoTranslate.getLocalizations({locale, origins});

	return {
		props: {locale, locales, localizations, origin},
		revalidate: 60,
	};
}

Эта функция принимает два аргумента: один объект Next.js Static Props Context и необязательный массив дополнительных источников для получения переводов, если вы используете более одного в своем приложении. Также обратите внимание на revalidate свойство в return операторе, которое сообщает Next.js о необходимости повторной сборки страницы через 60 секунд. Это позволит поддерживать переводы, отрендеренные на сервере, в актуальном состоянии.

Чтобы использовать эту функцию на странице, предположим, что у вас есть файл страницы, например, /pages/hello-world.tsx.

import {Translate} from 'tacotranslate/react';
import customGetStaticProps from '../utilities/custom-get-static-props';

export async function getStaticProps(context) {
	return customGetStaticProps(context);
}

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