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

Billi d-dinja ssir aktar globalizzata, issir dejjem iktar importanti għall-iżviluppaturi tal-web li jibnu applikazzjonijiet li jistgħu jolqtu lill-utenti minn pajjiżi u kulturi differenti. Wieħed mill-modi ewlenin biex dan jintlaħaq hu permezz tal-internazzjonalizzazzjoni (i18n), li tippermettilek tadatta l-applikazzjoni tiegħek għal lingwi, muniti u formati tad-data differenti.

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

Dan il-gwida huwa 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 i18n

Biex nimplementaw 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 is-strings tiegħek għal kwalunkwe lingwa bil-għajnuna ta' AI avvanzata, u jħollok mill-maniġjar tedjanti tal-fajls JSON.

Ejja ninstallawh billi nużaw npm fit-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 kont f'TacoTranslate, proġett ta' traduzzjoni, u ċwievet tal-API assoċjati. Oħloq kont hawn. Huwa b'xejn, u ma jirrikjedix li żżid karta ta' kreditu.

Fil-UI tal-applikazzjoni TacoTranslate, oħloq proġett u mur fit-tab tal-API keys tiegħu. Oħloq ċavetta waħda read, u ċavetta waħda read/write. Se npoġġuhom bħala varjabbli tal-ambjent. Il-read key huwa dak li nsejħu public, u l-read/write key huwa secret. Per eżempju, tista' iżżidhom f'file .env fil-root tal-proġett tiegħek.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Kun żgur li qatt ma tixxerja l-API key sigriet read/write f'ambjenti ta' produzzjoni fuq in-naħa tal-klijent.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Il-kodiċi tal-lokal predefinit li jintuża bħala fallback. F'dan l-eżempju, se nissettjawh għal en għall-Ingliż.
• TACOTRANSLATE_ORIGIN: Il-“folda” fejn se jinżammu s-strings tiegħek, bħall-URL tas-sit tiegħek. Aqra aktar dwar l-origini hawn.

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

Pass 3: Konfigurazzjoni ta' TacoTranslate

Sabiex tintegra TacoTranslate fl-applikazzjoni tiegħek, se jkollok bżonn toħloq klijent billi tuża l-API keys minn 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;

Se niddedefinixxu awtomatikament TACOTRANSLATE_API_KEY u TACOTRANSLATE_PROJECT_LOCALE dalwaqt.

Il-ħolqien tal-klijent f'fajl separat jagħmilha faċli li jerġa' jintuża aktar tard. getLocales hi sempliċiment funzjoni ta' utilità b'xi ġestjoni tal-iżbalji inkorporata. Issa oħloq fajl imsejjaħ /app/[locale]/tacotranslate.tsx, fejn se nimplementaw il-provider 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-provider tal-kuntest huwa lest, oħloq fajl bl-isem /app/[locale]/layout.tsx, il-layout prinċipali fl-applikazzjoni tagħna. Innota li dan il-perċors għandu 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 tagħna [locale] biex nġibu t-traduzzjonijiet għal dik il-lingwa. Barra minn hekk, generateStaticParams qed tiżgura li l-kodiċi kollha tal-lokali li inti attivajt għall-proġett tiegħek jiġu prerenderjati.

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 sekonda, u iżomm it-traduzzjonijiet tiegħek aġġornati.

Pass 4: Implimentazzjoni tar‑rendering tas‑server

TacoTranslate jappoġġja l-rendering fuq in-naħa tas-server. Dan jtejjeb b'mod sinifikanti l-esperjenza tal-utent billi juri immedjatament il-kontenut tradott, minflok flash ta' kontenut mhux tradott fil-bidu. Barra minn hekk, nistgħu nevitaw talbiet tan-netwerk fuq il-klijent, peress li diġà għandna t-traduzzjonijiet meħtieġa għall-paġna li l-utent qed jara.

Biex tissettja rendering fuq in‑naħa tas‑server, oħloq jew immodifika /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 mal-konfigurazzjoni 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 il-API key sigrieta read/write biex niżguraw li l-strings ġodda jintbagħtu għat-traduzzjoni.

Biex niżguraw li r-routing u r-redirezzjoni jaħdmu kif mistenni, se jkollna bżonn noħolqu fajl imsejjaħ /middleware.ts. Bl-użu ta' Middleware, nistgħu nibgħatu lill-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 ta' Next.js Middleware.

Fil-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!

Għamilna! L-applikazzjoni React tiegħek issa se tiġi tradotta awtomatikament meta tżid kwalunkwe string ma' komponent Translate. Nota li biss l-ambjenti li għandhom permessi read/write fuq il-key tal-API se jkunu kapaċi joħolqu strings ġodda li għandhom jiġu tradotti. Nirrakkomandaw li jkollok ambjent ta' staging magħluq u sigur fejn tista' tittestja l-applikazzjoni tal-produzzjoni tiegħek b'API key bħal dak, u żżid strings ġodda qabel ma tmur online. Dan se jipprevjeni lil ħadd milli jisraq il-key sigriet tal-API tiegħek, u potenzjalment jagħmel il-proġett tat-traduzzjoni tiegħek jikber b'mod mhux meħtieġ billi jiżdiedu strings ġ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!