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

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

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