Как да внедрите интернационализация в приложение на 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: Кодът на подразбиращия се резервен локал. В този пример ще го зададем като 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 езика. Започнете днес!