Як реалізувати інтернаціоналізацію в додатку 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-ключі, вказані раніше. Наприклад, створіть файл із назвою /tacotranslate-client.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 Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

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

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

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

Якщо у вас вже є власні pageProps та _app.tsx, будь ласка, розширте визначення наведені вище властивостями та кодом.

Крок 4: Реалізація серверного рендерингу

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

Почнемо зі створення або редагування /next.config.js.

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		client: tacoTranslateClient,
		isProduction:
			process.env.TACOTRANSLATE_ENV === 'production' ||
			process.env.VERCEL_ENV === 'production' ||
			(!(process.env.TACOTRANSLATE_ENV || process.env.VERCEL_ENV) &&
				process.env.NODE_ENV === 'production'),
	});
};

Змініть перевірку isProduction відповідно до вашої конфігурації. Якщо true, TacoTranslate використовуватиме публічний API ключ. Якщо ми знаходимося в локальному, тестовому або стадійному середовищі (isProduction is false), ми використовуватимемо секретний API ключ read/write для того, щоб нові рядки відправлялися на переклад.

До цього моменту ми лише налаштували застосунок Next.js зі списком підтримуваних мов. Наступним кроком буде отримання перекладів для всіх ваших сторінок. Для цього ви будете використовувати або getTacoTranslateStaticProps або getTacoTranslateServerSideProps залежно від ваших вимог.

Ці функції приймають три аргументи: один об'єкт Next.js Static Props Context, конфігурацію для TacoTranslate та необов'язкові властивості Next.js. Зверніть увагу, що revalidate у getTacoTranslateStaticProps за замовчуванням встановлено на 60, щоб ваші переклади залишалися актуальними.

Щоб використовувати будь-яку з цих функцій на сторінці, припустимо, у вас є файл сторінки на кшталт /pages/hello-world.tsx.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

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-додатки швидко з і на понад 75 мов. Почніть вже сьогодні!