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

Как работи

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

В този урок ще разгледаме как да добавите интернационализация към вашето React Next.js приложение с рендиране от страна на сървъра. TL;DR: Вижте пълния пример тук.

Това ръководство е за Next.js приложения, които използват Pages Router.
Ако използвате App Router, моля, вижте това ръководство вместо това.

Стъпка 1: Инсталирайте i18n библиотека

За да реализираме интернационализация във вашето Next.js приложение, първо ще изберем i18n библиотека. Съществуват няколко популярни библиотеки, включително next-intl. Въпреки това, в този пример ще използваме TacoTranslate.

TacoTranslate автоматично превежда вашите низове на всеки език, използвайки най-съвременен AI, и ви освобождава от досадното управление на 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: Публикувайте и тествайте!

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

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

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