Як реалізувати інтернаціоналізацію в застосунку 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-ключ у продуктивних середовищах на стороні клієнта.

Ми також додамо ще дві змінні середовища: 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!