Как реализовать интернационализацию в приложении 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-ключ смогут создавать новые строки для перевода. Мы рекомендуем иметь закрытую и защищённую staging-среду, где вы можете протестировать свое продукционное приложение с таким API-ключом, добавляя новые строки перед запуском. Это предотвратит любые попытки кражи вашего секретного API-ключа и потенциальное раздувание вашего проекта перевода путём добавления новых, не относящихся к делу строк.

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

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