Най-доброто решение за интернационализация (i18n) в приложения на Next.js

Как работи

С нарастващата глобализация на света, става все по-важно уеб разработчиците да създават приложения, които могат да обслужват потребители от различни държави и култури. Един от ключовите начини за постигане на това е чрез интернационализация (i18n), която ви позволява да адаптирате приложението си към различни езици, валути и формати на датите.

В това ръководство ще разгледаме как да добавите интернационализация към вашето React Next.js приложение с рендериране на сървъра (server-side rendering). 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 адресът на вашия уебсайт. Прочетете повече за произходите тук.

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 ключ. Ако сме в локална, тестова или staging среда (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: Разгръщане и тестване!

Готово! Вашето Next.js приложение вече ще се превежда автоматично, когато добавите каквито и да е низове към компонента Translate. Имайте предвид, че само среди с разрешения read/write върху API ключа ще могат да създават нови низове за превод. Препоръчваме да имате затворена и защитена стейджинг среда, в която да тествате продукционното си приложение с такъв API ключ, като добавяте новите низове преди пускането му на живо. Това ще попречи на всеки всеки да открадне вашия таен API ключ и евентуално да раздуе преводния ви проект чрез добавяне на нови, несвързани низове.

Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the App Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.

TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!