Як реалізувати інтернаціоналізацію в застосунку 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-ключ. Якщо ми перебуваємо в локальному, тестовому або проміжному (staging) середовищі (isProduction is false), ми будемо використовувати секретний read/write API-ключ, щоб переконатися, що нові рядки відправляються на переклад.

Щоб забезпечити належну роботу маршрутизації та перенаправлення, нам потрібно створити файл під назвою /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 налаштовано відповідно до документації Middleware для Next.js.

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

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

Готово! Ваш React-додаток тепер буде автоматично перекладатися, коли ви додасте будь-які рядки у компонент Translate. Зверніть увагу, що лише середовища, в яких ключ API має дозволи read/write, зможуть створювати нові рядки для перекладу. Рекомендуємо мати закрите та захищене тестове (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!