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

Billi d-dinja ssir aktar globalizzata, issir dejjem iktar importanti għall-iżviluppaturi tal-web li jibnu applikazzjonijiet li jistgħu jservu lill-utenti minn pajjiżi u kultura differenti. Wieħed mill-modijiet ewlenin biex tagħmel dan huwa permezz tal-internazzjonalizzazzjoni (i18n), li tippermettilek tadatta l-applikazzjoni tiegħek għal lingwi, muniti, u formati ta’ data differenti.

F’dan l-artikolu, ser nesploraw kif tista’ iżżid l-internazzjonalizzazzjoni fl-applikazzjoni tiegħek ta’ React Next.js, b’rendiment fuq in-naħa tas-server. TL;DR: Ara l-eżempju sħiħ hawn.

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

Pass 1: Installa librerija i18n

Biex timplimenta internazzjonalizzazzjoni fl-applikazzjoni Next.js tiegħek, l-ewwel se nagħżlu librerija i18n. Hemm diversi libreriji popolari, inkluż next-intl. Fil-każ ta’ din l-eżempju, madankollu, se nużaw TacoTranslate.

TacoTranslate jgħaddi awtomatikament is-sħab kollha tiegħek għal kwalunkwe lingwa billi juża AI avvanzata, u jħallik mid-dipendenza tedjosa fuq il-ġestjoni tal-fajls JSON.

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

npm install tacotranslate

Pass 2: Oħloq kont ħieles ta’ TacoTranslate

Issa li installajt il-modulu, wasal iż-żmien li toħloq kont fuq TacoTranslate, proġett ta' traduzzjoni, u ċ-ċwievet API assoċjati. Oħloq kont hawn. Huwa b'xejn, u ma jirrikjedix li żżid karta ta' kreditu.

Within the TacoTranslate application UI, crea proġett, u naviga għat-tab tal-API keys tiegħu. Oħloq waħda read key, u waħda read/write key. Aħna se ninżluhom bħala varjabbli ambjentali. Il-key read hija dak li nsejħu public u l-key read/write hija secret. Per eżempju, tista’ żżidhom f’fajl .env fil-ħajt tal-proġett tiegħek.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Kun żgur li qatt ma tħarbat il-mira sigrieta read/write API key lill-ambjenti ta' produzzjoni fuq in-naħa tal-klijent.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Il-kodiċi tal-lokal default li jintuża jekk oħrajn ma jinstabux. F'dan l-eżempju, se nissettjawh għal en għall-Ingliż.
• TACOTRANSLATE_ORIGIN: Il-“folder” fejn jgħaddu jżommuk il-frażijiet tiegħek, bħal pereżempju l-URL tal-websajt tiegħek. Ikteb aktar dwar l-origini hawn.

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

Pass 3: Twaqqif ta’ TacoTranslate

Biex tintegra TacoTranslate mal-applikazzjoni tiegħek, għandek toħloq client bl-użu tal-API keys minn qabel. Per eżempju, ikteb 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 nkunu qed nifformalaw awtomatikament TACOTRANSLATE_API_KEY u TACOTRANSLATE_PROJECT_LOCALE dalwaqt.

Il-ħolqien tal-klijent f’fajl separata jagħmilha faċli biex tużah mill-ġdid aktar tard. getLocales hija biss funzjoni ta’ utilità b’xi ħarsien mill-iżbalji mibni ġewwa. Issa, oħloq fajl imsejjaħ /app/[locale]/tacotranslate.tsx, fejn se nimplementaw 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.

Billi l-fornitur tal-kuntest huwa lest biex jintuża, oħloq fajl imsejjaħ /app/[locale]/layout.tsx, il-layout bażiku fl-applikazzjoni tagħna. Nota li dan il-perkorż 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 iżżomm f’moħħok hawn hi li qed nużaw il-parametru Dynamic Route tagħna [locale] biex niffrankaw it-traduzzjonijiet għal dik il-lingwa. Barra minn hekk, generateStaticParams qed jiżgura li l-kodiċi kollha tal-lokalitajiet li attivajt 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!" />
	);
}

Note the revalidate varjabbli li jgħid lil Next.js biex jibni mill-ġdid il-paġna wara 60 sekonda, u biex iżomm it-traduzzjonijiet tiegħek aġġornati.

Pass 4: Implimentazzjoni ta' rendering fuq in-naħa tas-server

TacoTranslate jappoġġja server side rendering. Dan itejjeb ħafna l-esperjenza tal-utent billi jelenka kontenut tradott immedjatament, minflok flash ta’ kontenut mhux tradott fil-bidu. Barra minn hekk, nistgħu nevitaw talbiet tan-netwerk fuq il-klijent, għax diġà għandna t-traduzzjonijiet li neħtieġu għall-paġna li l-utent qed jara.

Biex tistabbilixxi server side rendering, oħloq jew immaċċella /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};
};

Ibdel il-verifika isProduction biex taqbel mas-settjar tiegħek. Jekk true, TacoTranslate se juri l-mappa pubblika tal-API key. Jekk qegħdin f’ambjent lokali, ta’ test, jew staging (isProduction is false), se nużaw il-mappa sigrieta read/write tal-API key biex niżguraw li strixxi ġodda jintbagħtu għall-kwalita tat-traduzzjoni.

Biex niżguraw li r-rotta u r-riedirezzjoni jaħdmu kif mistenni, se jkollna noħolqu fajl imsejjaħ /middleware.ts. Billi nużaw Middleware, nistgħu nirridirezzjonaw lill-utenti għal 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 tħaddem il-matcher skont id-dokumentazzjoni ta’ Next.js Middleware.

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

Pass 5: Ippubblika u ipprova!

Spiċċajna! L-applikazzjoni React tiegħek issa se titħaddem awtomatikament meta żżid kwalunkwe strings ma’ komponent Translate. Innota li biss ambjenti b’permessi read/write fuq il-key tal-API se jkunu jistgħu joħolqu strings ġodda biex titħaddem it-traduzzjoni tagħhom. Nirrakkomandaw li jkollok ambjent ta’ staging magħluq u sigur fejn tista’ tittestja l-applikazzjoni tal-produzzjoni tiegħek b'key tal-API bħal dak, billi żżid strings ġodda qabel tmur live. Dan se jipprevjeni li xi ħadd joqtollek il-key tas-sigriet tal-API tiegħek, u potenzjalment jistifika t-tkabbir mhux meħtieġ fil-proġett tat-traduzzjoni tiegħek billi żż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!