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

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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 ключ. Якщо ми знаходимося у локальному, тестовому або staging середовищі (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 зможуть створювати нові рядки для перекладу. Ми рекомендуємо мати закрите та захищене тестове середовище, де ви можете тестувати вашу продукційну програму з таким ключем API, додаючи нові рядки перед запуском. Це запобігатиме крадіжці вашого секретного ключа API та потенційному роздуванню вашого проекту перекладу шляхом додавання нових, не пов’язаних рядків.

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

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