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