Как да внедрите интернационализация в 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: Езиковият код за резервен (fallback) локал по подразбиране. В този пример ще го зададем на 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 ключа ще могат да създават нови низове за превод. Препоръчваме да имате затворена и защитена стейджинг среда, в която да тествате продукционното си приложение с такъв API ключ, като добавяте нови низове преди да пуснете приложението на живо. Това ще предотврати кражбата на вашия таен API ключ и евентуално раздуване на проекта за преводи чрез добавяне на нови, несвързани низове.

Не забравяйте да разгледате пълния пример в нашия GitHub профил. Там ще намерите и пример за това как да го направите, използвайки App Router! Ако срещнете проблеми, не се колебайте да се свържете с нас, и ще се радваме да помогнем.

TacoTranslate ви позволява автоматично и бързо да локализирате вашите React приложения от и към над 75 езика. Започнете още днес!