Як реалізувати інтернаціоналізацію в додатку 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), ми будемо використовувати секретний 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 відповідно до документації Next.js Middleware.

На клієнті ви можете змінити кукі 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!