Як реалізувати інтернаціоналізацію в застосунку Next.js, який використовує App Router

У міру того, як світ стає дедалі більш глобалізованим, для веб-розробників стає все важливішим створювати застосунки, які можуть враховувати користувачів з різних країн і культур. Один із ключових способів досягти цього — це інтернаціоналізація (i18n), яка дозволяє адаптувати ваш застосунок до різних мов, валют і форматів дати.

У цій статті ми розглянемо, як додати інтернаціоналізацію до вашого React Next.js застосунку з серверним рендерингом. TL;DR: See the full example here.

Цей посібник призначений для застосунків 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!