Как да внедрите интернационализация в 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 адреса на вашия уебсайт. Научете повече за 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 езика и обратно. Започнете още днес!