Як реалізувати інтернаціоналізацію в Next.js-застосунку, який використовує App Router

У міру глобалізації світу веброзробникам стає дедалі важливіше створювати застосунки, які можуть задовольняти потреби користувачів з різних країн і культур. Одним із ключових способів досягти цього є інтернаціоналізація (i18n), яка дозволяє адаптувати ваш застосунок до різних мов, валют і форматів дат.

У цій статті ми розглянемо, як додати інтернаціоналізацію до вашого застосунку на React/Next.js із серверним рендерингом. TL;DR: Дивіться повний приклад тут.

Цей посібник призначений для додатків Next.js, які використовують App Router.
Якщо ви використовуєте Pages 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-ключ у клієнтських production-середовищах.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Код локалі за замовчуванням для резервного варіанта. У цьому прикладі ми встановимо його як 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_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

Незабаром ми автоматично визначимо TACOTRANSLATE_API_KEY і TACOTRANSLATE_PROJECT_LOCALE.

Створення клієнта в окремому файлі спрощує його повторне використання пізніше. getLocales — це всього лише утилітна функція з деякою вбудованою обробкою помилок. Тепер створіть файл під назвою /app/[locale]/tacotranslate.tsx, де ми реалізуємо провайдер TacoTranslate.

'use client';

import React, {type ReactNode} from 'react';
import {
	type TranslationContextProperties,
	TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';

export default function TacoTranslate({
	locale,
	origin,
	localizations,
	children,
}: TranslationContextProperties & {
	readonly children: ReactNode;
}) {
	return (
		<ImportedTacoTranslate
			client={tacoTranslateClient}
			locale={locale}
			origin={origin}
			localizations={localizations}
		>
			{children}
		</ImportedTacoTranslate>
	);
}

Зверніть увагу на 'use client';, що вказує на те, що це клієнтський компонент.

Тепер, коли провайдер контексту готовий до роботи, створіть файл з іменем /app/[locale]/layout.tsx, кореневий макет у нашому застосунку. Зверніть увагу, що цей шлях містить папку, яка використовує Dynamic Routes, де [locale] є динамічним параметром.

import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';

export async function generateStaticParams() {
	const locales = await tacoTranslateClient.getLocales();
	return locales.map((locale) => ({locale}));
}

type RootLayoutParameters = {
	readonly params: Promise<{locale: Locale}>;
	readonly children: ReactNode;
};

export default async function RootLayout({params, children}: RootLayoutParameters) {
	const {locale} = await params;
	const origin = process.env.TACOTRANSLATE_ORIGIN;
	const localizations = await tacoTranslateClient.getLocalizations({
		locale,
		origins: [origin /* , other origins to fetch */],
	});

	return (
		<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
			<body>
				<TacoTranslate
					locale={locale}
					origin={origin}
					localizations={localizations}
				>
					{children}
				</TacoTranslate>
			</body>
		</html>
	);
}

Перше, що слід зазначити, — ми використовуємо наш параметр Dynamic Route [locale] для отримання перекладів для цієї мови. Додатково, generateStaticParams забезпечує попередній рендер усіх кодів локалі, які ви активували для вашого проєкту.

Тепер давайте створимо нашу першу сторінку! Створіть файл з іменем /app/[locale]/page.tsx.

import React from 'react';
import {Translate} from 'tacotranslate/react';

export const revalidate = 60;
export default async function Page() {
	return (
		<Translate string="Hello, world!" />
	);
}

Зверніть увагу на змінну revalidate, яка наказує Next.js перегенерувати сторінку через 60 секунд і тримати ваші переклади в актуальному стані.

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

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

Щоб налаштувати рендеринг на стороні сервера, створіть або змініть /next.config.js:

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

module.exports = async () => {
	const config = await withTacoTranslate(
		{},
		{
			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'),
		}
	);

	// NOTE: Remove i18n from config when using the app router
	return {...config, i18n: undefined};
};

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

Щоб гарантувати, що маршрутизація та перенаправлення працюють належним чином, нам потрібно створити файл під назвою /middleware.ts. Використовуючи Middleware, ми можемо перенаправляти користувачів на сторінки, представлені їхньою бажаною мовою.

import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';

export const config = {
	matcher: ['/((?!api|_next|favicon.ico).*)'],
};

export async function middleware(request: NextRequest) {
	return tacoTranslateMiddleware(tacoTranslate, request);
}

Переконайтеся, що налаштували matcher відповідно до документації Next.js Middleware.

На стороні клієнта ви можете змінити cookie locale, щоб змінити мову, яку віддає перевагу користувач. Будь ласка, перегляньте повний приклад коду, щоб дізнатися, як це зробити!

Крок 5: Розгорніть і протестуйте!

Готово! Тепер ваш React‑додаток буде автоматично перекладатися щоразу, коли ви додаватимете будь‑які рядки до компонента Translate. Зверніть увагу, що лише середовища з дозволами read/write на ключ API зможуть створювати нові рядки для перекладу. Рекомендуємо мати закрите й захищене staging‑середовище, де ви зможете тестувати продукційну версію додатка з таким ключем API, додаючи нові рядки перед запуском у продакшн. Це запобіжить тому, що хтось вкраде ваш секретний ключ API та потенційно роздмухає ваш проєкт перекладів через додавання нових, не пов’язаних рядків.

Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the Pages Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.

TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!