Како да се имплементира интернационализација во 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-то на вашата веб-страница. Прочитајте повеќе за 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_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 секунди и да ги одржува вашите преводи ажурни.

Step 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), ќе го користиме тајниот API клуч read/write за да се осигураме дека новите стрингови ќе бидат испратени на превод.

За да се осигури дека рутирањето и пренасочувањето функционираат како што се очекува, ќе треба да создадеме датотека со име /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.

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