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

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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 ключа та потенційному розростанню вашого проекту перекладів за рахунок додавання нових, нерелевантних рядків.

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

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