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

Hekk kif id-dinja ssir aktar globalizzata, huwa dejjem aktar importanti għall-iżviluppaturi tal-web li joħolqu applikazzjonijiet li jistgħu jindirizzaw utenti minn pajjiżi u kulturi differenti. Wieħed mill-modi ewlenin biex dan jinkiseb huwa 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, inkluż rendering fuq in-naħa tas-server. TL;DR: Ara l-eżempju sħiħ hawn.

Din il-gwida hija għall-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 nimplementaw l-internazzjonalizzazzjoni fl-applikazzjoni Next.js tiegħek, l-ewwel nagħżlu librerija i18n. Hemm diversi libreriji popolari, inkluż next-intl. Madankollu, f'dan l-eżempju se nużaw TacoTranslate.

TacoTranslate jittraduċi awtomatikament il-kordi tiegħek għal kwalunkwe lingwa billi juża AI avvanzat, u jiffralek mill-immaniġġjar tedjuż ta' fajls JSON.

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

npm install tacotranslate

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

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

Fil-UI tal-applikazzjoni TacoTranslate, oħloq proġett u mur fit-tab tal-API keys tiegħu. Oħloq ċavetta read waħda u ċavetta read/write waħda. Se nħażnuhom bħala variabbli tal-ambjent. Iċ-ċavetta read hi dik li nsejħu public, u ċ-ċavetta read/write hi secret. Per eżempju, tista' tpoġġihom fi fajl .env fil-għerq tal-proġett tiegħek.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Kun żgur li qatt ma tiskopri l-kodiċi API 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 default tal-lokalità li jintuża bħala fallback. F'dan l-eżempju, se nissettjawh bħala en għall-Ingliż.
• TACOTRANSLATE_ORIGIN: Il-“folder” fejn se jinżammu l-strings tiegħek, bħal pereżempju l-URL tas-sit tiegħek. Aqra aktar dwar il-origini hawn.

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

Pass 3: Konfigurazzjoni ta' TacoTranslate

Biex tintegra TacoTranslate mal-applikazzjoni tiegħek, ser ikollok bżonn toħloq klijent billi tuża ċwievet 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;

Se niddefinixxu awtomatikament TACOTRANSLATE_API_KEY u TACOTRANSLATE_PROJECT_LOCALE dalwaqt.

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

Meta l-provvitur tal-kuntest ikun lest biex jintuża, oħloq fajl imsejjaħ /app/[locale]/layout.tsx, il-layout ewlenin 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] tagħna biex niġbru t-traduzzjonijiet għal dik il-lingwa. Barra minn hekk, generateStaticParams qed tiżgura li l-kodiċi kollha tal-lokalità li għandek attivati fil-proġett tiegħek jiġu renderjati minn qabel.

Issa, ejja nibnu l-ewwel paġna tagħna! Oħloq fajl bl-isem /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' jinbena l-paġna wara 60 sekonda, u jżomm it-traduzzjonijiet tiegħek aġġornati.

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

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

Biex tissettja ir-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};
};

Aġġusta l-verifika isProduction biex taqbel mal-konfigurazzjoni tiegħek. Jekk true, TacoTranslate se juri l-ċavetta API pubblika. Jekk ninsabu f'ambjent lokali, ta' test, jew ta' staging (isProduction is false), se nużaw il-ċavetta API sigrieta read/write biex niżguraw li l-kordi ġodda jintbagħtu għall-traduzzjoni.

Biex niżguraw li r-routing u r-reindirizzament jaħdmu kif mistenni, se jkollna noħolqu fajl bl-isem /middleware.ts. Permezz ta' Middleware, nistgħu nireindirizzaw 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 tissetta matcher skont id-dokumentazzjoni tal-Middleware ta' Next.js.

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

Pass 5: Ippubblika u ittestja!

Għamilna! L-applikazzjoni React tiegħek issa se tittraduċi awtomatikament meta żżid xi strings f'komponent Translate. Nota li biss l-ambjenti b'permessi read/write fuq iċ-ċavetta tal-API se jkunu jistgħu joħolqu strings ġodda li jittraduċu. Nissuġġerixxu li jkollok ambjent ta' staging magħluq u sikur fejn tista' tittestja l-applikazzjoni tal-produzzjoni tiegħek b'ċavetta tal-API bħal dik, u żżid strings ġodda qabel ma tmur live. Dan se jipprevjeni li xi ħadd jisraq iċ-ċavetta sigrieta tal-API tiegħek, u potenzjalment jimla l-proġett tat-traduzzjoni tiegħek billi jżid 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!