Kif għandek timplimenta l-internazzjonalizzazzjoni f'applikazzjoni Next.js li qed tuża App Router

Hekk kif id-dinja ssir aktar globalizzata, issir dejjem iktar importanti għall-iżviluppaturi tal-web li jibnu applikazzjonijiet li jistgħu jilqgħu l-bżonnijiet ta' utenti minn pajjiżi u kulturi differenti. Wieħed mill-aktar modi ewlenin biex dan jintlaħaq huwa l-internazzjonalizzazzjoni (i18n), li tippermetti li tadatta l-applikazzjoni tiegħek għal lingwi, muniti u formati tad-data differenti.

F'dan l-artiklu, se nesploraw kif iżżid internazzjonalizzazzjoni fl-applikazzjoni React Next.js tiegħek, b'rendering fuq in-naħa tas-server. TL;DR: Ara l-eżempju sħiħ hawn.

Din il-gwida hija għal applikazzjonijiet Next.js li qed jużaw App Router.
Jekk qed tuża Pages Router, ara din il-gwida minflok.

Pass 1: Installa librerija għall-i18n

Biex nimplimentaw l-internazzjonalizzazzjoni fl-applikazzjoni Next.js tiegħek, l-ewwel se nagħżlu librerija i18n. Hemm diversi libreriji popolari, inklużi next-intl. F'dan l-eżempju, madankollu, se nużaw TacoTranslate.

TacoTranslate jittraduċi awtomatikament il-strings tiegħek għal kwalunkwe lingwa billi juża AI avvanzat, u jiffranka lilek mill-ġestjoni tedjuża ta' fajls JSON.

Ejja ninstallawh billi nużaw npm fil-terminal tiegħek:

npm install tacotranslate

Pass 2: Oħloq kont b'xejn ta' TacoTranslate

Issa li għandek il-modulu installat, wasal iż-żmien li toħloq il-kont TacoTranslate tiegħek, proġett ta' traduzzjoni, u ċwievet tal-API assoċjati. Oħloq kont hawn. Huwa b'xejn, u ma teħtieġx li żżid karta ta' kreditu.

F'interfaċċa tal-applikazzjoni TacoTranslate, oħloq proġett u mur fit-tab tal-muftijiet tal-API tiegħu. Oħloq ċavetta waħda read u ċavetta waħda read/write. Se ninħażnhom bħala variabbli tal-ambjent. Iċ-ċavetta read hija dak li nsejħu public u iċ-ċavetta read/write hija secret. Per eżempju, tista' iżżidhom f'fajl .env fil-root tal-proġett tiegħek.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Kun żgur li qatt ma tnixxi l-muftieħ sigriet tal-API read/write fl-ambjenti tal-produzzjoni fuq in-naħa tal-klijent.

Se nżidu wkoll żewġ varjabbli tal-ambjent: TACOTRANSLATE_DEFAULT_LOCALE u TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Il-kodiċi tal-lokal tal-fallback predefinit. F'dan l-eżempju, se nissettjawh għal en għall-Ingliż.
• TACOTRANSLATE_ORIGIN: Il-“folder” fejn se jkunu maħżuna l-kordi tiegħek, bħal pereżempju l-URL tas-sit tiegħek. Aqra aktar dwar l-oriġini hawn.

TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

Pass 3: Issettjar ta' TacoTranslate

Biex tintegra TacoTranslate fl-applikazzjoni tiegħek, se jkollok bżonn toħloq klijent billi tuża l-kliavi tal-API msemmija qabel. Per eżempju, oħloq fajl imsejjaħ /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;

Dalwaqt se niddefinixxu awtomatikament TACOTRANSLATE_API_KEY u TACOTRANSLATE_PROJECT_LOCALE.

Il-ħolqien tal-klijent f'fajl separat jagħmilha faċli biex jintuża mill-ġdid aktar tard. getLocales hija biss funzjoni ta' utilità b'xi ġestjoni tal-iżbalji mibnija ġewwa. Issa, oħloq fajl imsejjaħ /app/[locale]/tacotranslate.tsx, fejn se nimplementaw il-provayder 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>
	);
}

Innota 'use client'; li jindika li dan huwa komponent tal-klijent.

Issa li l-provvitur tal-kuntest hu lest, oħloq fajl imsejjaħ /app/[locale]/layout.tsx, il-layout prinċipali fl-applikazzjoni tagħna. Innota li din it-triq għandha folder li juża Dynamic Routes, fejn [locale] huwa l-parametru dinamiku.

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>
	);
}

L-ewwel ħaġa li għandek tinnota hawn hi li qed nużaw il-parametru Dynamic Route [locale] biex niġbru t-traduzzjonijiet għal dik il-lingwa. Barra minn hekk, generateStaticParams qed jagħmel ċert li l-kodiċi kollha tal-lokalitajiet li għandek attivati għall-proġett tiegħek jiġu pre-renderjati.

Issa, ejja nibnu l-ewwel paġna tagħna! Oħloq fajl imsejjaħ /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!" />
	);
}

Innota l-varjabbli revalidate li jgħid lil Next.js biex jerġa' jibni l-paġna wara 60 sekondi, u iżomm it-traduzzjonijiet tiegħek aġġornati.

Pass 4: Implementazzjoni tal-rendering fuq in-naħa tas-server

TacoTranslate jappoġġja rendering fuq in-naħa tas-server. Dan iġġib titjib kbir fl-esperjenza tal-utent billi juri l-kontenut tradott immedjatament, minflok l-ewwel juri kontenut mhux tradott għal mument qasir. Barra minn hekk, nistgħu nevitaw talbiet tan-netwerk fil-klijent, għax diġà għandna t-traduzzjonijiet li għandna bżonn għall-paġna li l-utent qed jara.

Biex tissettja rendering fuq in-naħa tas-server, oħloq jew ibdel /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};
};

Modifika l-iċċekkjar isProduction biex jaqbel mas-settjar tiegħek. Jekk true, TacoTranslate se juri l-API key pubblika. Jekk ninsabu f'ambjent lokali, ta' test, jew ta' staging (isProduction is false), se nużaw l-API key sigrieta read/write biex niżguraw li l-strings ġodda jintbagħtu għall-traduzzjoni.

Biex niżguraw li r-routing u r-ridirezzjoni jaħdmu kif mistenni, se jkollna bżonn noħolqu fajl bl-isem /middleware.ts. Bl-użu ta' Middleware, nistgħu nirridireġu l-utenti lejn paġni ppreżentati bil-lingwa preferuta tagħhom.

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);
}

Kun żgur li tissettja matcher skont id-dokumentazzjoni tal-Middleware ta' Next.js.

Fuq il-klijent, tista' tbiddel il-cookie locale biex tibdel il-lingwa preferuta tal-utent. Ara il-kodiċi tal-eżempju sħiħ għal ideat dwar kif tagħmel dan!

Pass 5: Ippubblika u ittestja!

Issa tlestajna! L-applikazzjoni React tiegħek issa se tittraduċi awtomatikament meta żżid kwalunkwe stringa ma' komponent Translate. Nota li biss ambjenti b'permessi read/write fuq il-key tal-API se jkunu jistgħu joħolqu stringi ġodda għat-traduzzjoni. Nirrakkomandaw li jkollok ambjent ta' staging magħluq u sikur fejn tista' tittestja l-applikazzjoni tal-produzzjoni tiegħek b'API key bħal dak, u żżid stringi ġodda qabel ma tmur live. Dan se jipprevjeni li xi ħadd xi ħadd jiksib il-key tal-API sigriet tiegħek b'mod illegali, u potenzjalment jimbotta l-proġett tat-traduzzjoni tiegħek billi jiżdiedu stringi ġodda mhux relatati.

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!