Як реалізувати інтернаціоналізацію в застосунку 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

Ніколи не розголошуйте секретний ключ API read/write у продуктивних середовищах на стороні клієнта.

Ми також додамо ще дві змінні середовища: 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), де ви зможете тестувати ваш продуктивний додаток з таким API-ключем, додаючи нові рядки перед запуском у продакшн. Це запобіжить крадіжці вашого секретного API-ключа та потенційному роздуванню вашого проєкту перекладу за рахунок додавання нових, не пов’язаних рядків.

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

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