Як реалізувати інтернаціоналізацію в додатку 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

Ніколи не розкривайте секретний ключ API read/write у клієнтських production‑середовищах.

Ми також додамо ще дві змінні середовища: TACOTRANSLATE_DEFAULT_LOCALE та TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Код локалі за замовчуванням (fallback). У цьому прикладі ми встановимо його як en для англійської.
• TACOTRANSLATE_ORIGIN: «папка», у якій зберігатимуться ваші рядки, наприклад URL вашого сайту. Дізнайтеся більше про origins тут.

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), ми використовуватимемо секретний read/write API-ключ, щоб нові рядки надсилалися на переклад.

До цього часу ми лише налаштували додаток 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-ключа зможуть створювати нові рядки для перекладу. Рекомендуємо мати закрите та захищене staging-середовище, де ви зможете протестувати продакшн-застосунок з таким API-ключем, додаючи нові рядки перед запуском. Це запобігатиме тому, щоб будь-хто будь-хто вкрав ваш секретний API-ключ і потенційно роздув проєкт перекладів, додаючи нові, не пов'язані рядки.

Обов'язково перегляньте повний приклад у нашому профілі на GitHub. Там ви також знайдете приклад того, як зробити це з використанням App Router! Якщо у вас виникнуть проблеми, не соромтеся зв'язатися з нами, і ми з радістю допоможемо.

TacoTranslate дозволяє автоматично локалізувати ваші додатки React у понад 75 мов (в обох напрямках). Почніть сьогодні!