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