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

Biż-żieda tal-globalizzazzjoni fid-dinja, saret dejjem aktar importanti għall-iżviluppaturi tal-web li jinbnew applikazzjonijiet li jistgħu jilqgħu lill-utenti minn pajjiżi u kulturi differenti. Wieħed mit-toroq ewlenin biex dan jintlaħaq 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, se nesploraw kif iżżid l-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ħall-applikazzjonijiet Next.js li qed jużaw il-App Router.
Jekk qed tuża l-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 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-kontenut tat-test tiegħek għal kwalunkwe lingwa billi juża AI avvanzat, u jiffrankak mill-immaniġġjar tedjanti 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 TacoTranslate tiegħek, proġett ta' traduzzjoni, u ċwieki tal-API assoċjati. Oħloq kont hawn. Huwa b'xejn, u ma jeħtieġx li żżid karta ta' kreditu.

Fil-UI tal-applikazzjoni TacoTranslate, oħloq proġett u mur fit-tab tal-API keys tal-proġett. Oħloq waħda read ċavetta u waħda read/write ċavetta. Se nissalvawhom bħala varjabbli tal-ambjent. Il-ċavetta read hija dak li nsejħu public u l-ċavetta read/write hija secret. Per eżempju, tista' iżżidhom fil-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 tikxef il-ċavetta sigrieta read/write tal-API fl-ambjenti ta' produzzjoni fuq in-naħa tal-klijent.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Il-kodiċi default tal-lokal li jintuża bħala fallback. F’dan l-eżempju, se nissettjawh għal en għall-Ingliż.
• TACOTRANSLATE_ORIGIN: Il-“folder” fejn jinżammu l-kontenuti testwali 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 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;

Awtomatikament se niddeterminaw TACOTRANSLATE_API_KEY u TACOTRANSLATE_PROJECT_LOCALE dalwaqt.

It-tqegħid tal-klijent f'fajl separat jagħmilha faċli li jerġa' jintuża aktar tard. getLocales huwa biss funzjoni ta' utilità b'xi ġestjoni ta' żbalji integrata. Issa, oħloq fajl bl-isem /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 tindika li dan huwa komponent tal-klijent.

Meta l-fornitur tal-kuntest ikun lest, oħloq fajl imsejjaħ /app/[locale]/layout.tsx, il-layout prinċipali fl-applikazzjoni tagħna. Nota li din il-path 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 hija li qed nużaw il-parametru Dynamic Route [locale] biex nġibu t-traduzzjonijiet għal dik il-lingwa. Barra minn hekk, generateStaticParams qed jiżgura li l-kodiċijiet tal-lokal kollha li għandek attivati fil-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!" />
	);
}

Nota 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 tal-rendering fuq in-naħa tas-server

TacoTranslate jappoġġja ir-rendering fuq in-naħa tas-server. Dan jtejjeb b’mod sinifikanti l-esperjenza tal‑utent billi juri l-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 meħtieġa għall-paġna li l-utent qed jara.

Biex tissettja r-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-key pubblika tal-API. Jekk ninsabu f'ambjent lokali, ta' test, jew ta' staging (isProduction is false), se nużaw il-key sigriet tal-API read/write biex niżguraw li stringijiet ġodda jintbagħtu għall-traduzzjoni.

Biex niżguraw li r-rotta u r-rindirizzament jaħdmu kif mistenni, se jkollna bżonn noħolqu fajl imsejjaħ /middleware.ts. Bl-użu ta' Middleware, nistgħu nirindirizzaw l-utenti lejn il-paġni ppreżentati fil-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 l-matcher skont id-dokumentazzjoni tal-Middleware ta’ Next.js.

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: Inniedi u tittestja!

Lest! Issa l-applikazzjoni React tiegħek se tiġi tradotta awtomatikament meta żżid kwalunkwe kordi f'komponent Translate. Innota li biss l-ambjenti b’permessi read/write fuq il-API key se jkunu jistgħu joħolqu kordi ġodda li għandhom jiġu tradotti. 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 kordi ġodda qabel ma tippubblika. Dan se jipprevjeni lil kull min milli jisraq il-API key sigriet tiegħek, u potenzjalment jagħmel lill-proġett tat-traduzzjoni tiegħek jikber b’kordi ġ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!