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

Чекор 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 во согласност со документацијата за 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!