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

Обов’язково ніколи не розкривайте секретний ключ API read/write у клієнтських продакшн-середовищах.

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

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

TacoTranslate дозволяє вам швидко автоматично локалізувати ваші React-застосунки на будь-яку мову і з будь-якої мови. Почніть вже сьогодні!