Как да внедрите интернационализация в приложение на 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 адресът на вашия уебсайт. Прочетете повече за произходите тук.

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 езика. Започнете още днес!