Како да се имплементира интернационализација во 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 клуч. Ако сме во локална, тест или стејџинг средина (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 во согласност со документацијата за Next.js Middleware.

На клиентската страна, можете да го измените колачињето 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!