Найкраще рішення для інтернаціоналізації (i18n) у додатках Next.js

Як це працює

У міру глобалізації світу для веб-розробників стає дедалі важливішим створювати застосунки, які можуть задовольняти потреби користувачів з різних країн і культур. Одним із ключових способів досягти цього є інтернаціоналізація (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-ключ у клієнтському production-середовищі.

Ми також додамо ще дві змінні середовища: 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: Розгорніть і протестуйте!

Ми закінчили! Тепер ваш додаток Next.js автоматично перекладатиметься, коли ви додаватимете будь-які рядки в компонент Translate. Зауважте, що лише середовища з дозволами read/write на ключ API зможуть створювати нові рядки для перекладу. Рекомендуємо мати закрите та захищене staging-середовище, де ви зможете тестувати свій production-додаток з таким ключем API, додаючи нові рядки перед запуском у продакшн. Це запобіжить тому, щоб будь-хто будь-хто вкрав ваш секретний ключ API і, ймовірно, не дозволить роздути ваш проект перекладів шляхом додавання нових, не пов’язаних рядків.

Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the App Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.

TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!