Како да се имплементира интернационализација во Next.js апликација која користи App Router

Како што светот станува се повеќе глобализиран, сè повеќе е важно веб-развојците да создаваат апликации кои можат да ги задоволат корисниците од различни земји и култури. Еден од клучните начини за тоа е интернационализацијата (i18n), која ви овозможува да ја прилагодите вашата апликација на различни јазици, валути и формати на датуми.

Во оваа статија ќе разгледаме како да додадете интернационализација во вашата React Next.js апликација, со рендерирање на серверот. TL;DR: Погледнете го целиот пример овде.

Овој водич е за Next.js апликации кои го користат App Router.
Ако го користите Pages 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_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

Наскоро ќе ги дефинираме автоматски TACOTRANSLATE_API_KEY и TACOTRANSLATE_PROJECT_LOCALE.

Креирање на клиентот во посебна датотека го олеснува повторното користење подоцна. getLocales е само помошна функција со вградена обработка на грешки. Сега, креирајте датотека со име /app/[locale]/tacotranslate.tsx, во која ќе го имплементираме провајдерот TacoTranslate.

'use client';

import React, {type ReactNode} from 'react';
import {
	type TranslationContextProperties,
	TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';

export default function TacoTranslate({
	locale,
	origin,
	localizations,
	children,
}: TranslationContextProperties & {
	readonly children: ReactNode;
}) {
	return (
		<ImportedTacoTranslate
			client={tacoTranslateClient}
			locale={locale}
			origin={origin}
			localizations={localizations}
		>
			{children}
		</ImportedTacoTranslate>
	);
}

Обратете внимание на 'use client'; што укажува дека ова е клиентска компонента.

Со контекст-провајдерот сега спремен за употреба, создадете датотека со име /app/[locale]/layout.tsx, коренскиот layout во нашата апликација. Имајте на ум дека оваа патека содржи папка која користи Dynamic Routes, каде што [locale] е динамичкиот параметар.

import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';

export async function generateStaticParams() {
	const locales = await tacoTranslateClient.getLocales();
	return locales.map((locale) => ({locale}));
}

type RootLayoutParameters = {
	readonly params: Promise<{locale: Locale}>;
	readonly children: ReactNode;
};

export default async function RootLayout({params, children}: RootLayoutParameters) {
	const {locale} = await params;
	const origin = process.env.TACOTRANSLATE_ORIGIN;
	const localizations = await tacoTranslateClient.getLocalizations({
		locale,
		origins: [origin /* , other origins to fetch */],
	});

	return (
		<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
			<body>
				<TacoTranslate
					locale={locale}
					origin={origin}
					localizations={localizations}
				>
					{children}
				</TacoTranslate>
			</body>
		</html>
	);
}

Првата работа што треба да се забележи овде е дека го користиме нашиот Dynamic Route параметар [locale] за да ги повлечеме преводите за тој јазик. Дополнително, generateStaticParams се погрижува дека сите кодови на локали што сте ги активирале за вашиот проект се претходно генерирани.

Сега, да ја изградиме нашата прва страница! Креирајте датотека со името /app/[locale]/page.tsx.

import React from 'react';
import {Translate} from 'tacotranslate/react';

export const revalidate = 60;
export default async function Page() {
	return (
		<Translate string="Hello, world!" />
	);
}

Обратете внимание на променливата revalidate, која му кажува на Next.js да ја пресоздаде страницата по 60 секунди и да ги одржува преводите ажурни.

Чекор 4: Имплементација на серверско рендерирање

TacoTranslate поддржува рендерирање на серверот. Ова значително го подобрува корисничкото искуство, прикажувајќи ја преведената содржина веднаш, наместо прво да се појави краток миг на непреведена содржина. Дополнително, можеме да ги прескокнеме мрежните барања на клиентот, бидејќи веќе ги имаме преводите што ни се потребни за страницата која корисникот ја гледа.

За да го поставите серверското рендерирање, креирајте или изменете /next.config.js:

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = await withTacoTranslate(
		{},
		{
			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'),
		}
	);

	// NOTE: Remove i18n from config when using the app router
	return {...config, i18n: undefined};
};

Променете ја проверката isProduction за да одговара на вашата поставка. Ако true, TacoTranslate ќе го прикаже јавниот API клуч. Ако сме во локална, тест или staging околина (isProduction is false), ќе го користиме тајниот read/write API клуч за да се осигураме дека новите низи ќе бидат испратени на превод.

За да осигураме дека рутирањето и пренасочувањето ќе работат како што се очекува, ќе треба да создадеме датотека со име /middleware.ts. Користејќи го Middleware, можеме да ги пренасочуваме корисниците кон страници прикажани на нивниот префериран јазик.

import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';

export const config = {
	matcher: ['/((?!api|_next|favicon.ico).*)'],
};

export async function middleware(request: NextRequest) {
	return tacoTranslateMiddleware(tacoTranslate, request);
}

Осигурајте се да го поставите matcher во согласност со документацијата за Middleware на Next.js.

На клиентската страна, можете да го промените колачиќот locale за да го смените претпочитаниот јазик на корисникот. Ве молиме погледнете го целосниот пример со код за идеи како да го направите тоа!

Чекор 5: Објавете и тестирајте!

Готово! Вашата React апликација сега ќе биде автоматски преведена кога ќе додадете какви било низи во компонентата 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 Pages 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!