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

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

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