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