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

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