Найкраще рішення для інтернаціоналізації (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 вашого вебсайту. Дізнайтеся більше про origin тут.

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

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

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