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

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

У цьому підручнику ми розглянемо, як додати інтернаціоналізацію до вашого React Next.js застосунку із серверним рендерингом. TL;DR: Перегляньте повний приклад тут.

Цей посібник розрахований на застосунки Next.js, що використовують Pages Router.
Якщо ви використовуєте App 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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Незабаром ми автоматично визначимо TACOTRANSLATE_API_KEY.

Створення клієнта в окремому файлі спрощує його повторне використання надалі. Тепер, використовуючи кастомний /pages/_app.tsx, ми додамо провайдера TacoTranslate.

import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

type PageProperties = {
	origin: Origin;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, locales, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

Якщо у вас вже є власні pageProps та _app.tsx, будь ласка, розширте визначення властивостями та кодом, наведеними вище.

Крок 4: Впровадження рендерингу на стороні сервера

TacoTranslate дозволяє виконувати серверний рендеринг ваших перекладів. Це значно покращує досвід користувача, бо перекладений вміст відображається одразу, замість короткочасного показу неперекладеного контенту. Крім того, ми можемо уникнути мережевих запитів на боці клієнта, оскільки в нас уже є всі необхідні переклади.

Почнемо зі створення або редагування /next.config.js.

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		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'),
	});
};

Змініть перевірку isProduction відповідно до вашої конфігурації. Якщо true, TacoTranslate відобразить публічний API-ключ. Якщо ми перебуваємо в локальному, тестовому або стадінговому середовищі (isProduction is false), ми використовуватимемо секретний read/write API-ключ, щоб переконатися, що нові рядки надсилаються для перекладу.

До цього часу ми лише налаштували застосунок Next.js зі списком підтримуваних мов. Наступне, що ми зробимо, — це отримати переклади для всіх ваших сторінок. Для цього ви використаєте або getTacoTranslateStaticProps або getTacoTranslateServerSideProps залежно від ваших вимог.

Ці функції приймають три аргументи: один об'єкт Next.js Static Props Context, конфігурацію для TacoTranslate та необов'язкові властивості Next.js. Зауважте, що revalidate в getTacoTranslateStaticProps за замовчуванням встановлено на 60, щоб ваші переклади залишалися актуальними.

Щоб використати будь-яку з цих функцій на сторінці, припустимо, що у вас є файл сторінки, наприклад /pages/hello-world.tsx.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

export default function Page() {
	return <Translate string="Hello, world!"/>;
}

Тепер ви зможете використовувати компонент Translate для перекладу рядків у всіх ваших React-компонентах.

import {Translate} from 'tacotranslate/react';

function Component() {
	return <Translate string="Hello, world!"/>
}

Крок 5: Розгорніть і протестуйте!

Готово! Ваш React‑додаток тепер буде перекладатися автоматично, коли ви додаєте будь‑які рядки у компонент Translate. Зауважте, що лише середовища з дозволами read/write на ключі API зможуть створювати нові рядки для перекладу. Рекомендуємо мати закрите та захищене staging‑середовище, де ви зможете протестувати ваш production‑застосунок із таким ключем API, додаючи нові рядки перед запуском. Це запобіжить викраденню вашого секретного API‑ключа та потенційному роздуванню вашого проекту перекладів через додавання нових, не пов’язаних рядків.

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

TacoTranslate дозволяє автоматично локалізувати ваші React‑застосунки швидко в обох напрямках (понад 75 мов). Почніть сьогодні!