Найкраще рішення для інтернаціоналізації (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 ключ у продакшн-середовищах на стороні клієнта.

Ми також додамо ще два змінні середовища: 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), ми будемо використовувати секретний ключ API read/write , щоб переконатися, що нові рядки відправлені на переклад.

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

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

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