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

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

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