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