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