Как реализовать интернационализацию в приложении 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 автоматически переводит ваши строки на любой язык, используя современные AI-технологии, и освобождает вас от утомительного управления файлами 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 быстро на любой язык и с любого языка. Начните сегодня!