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

Bħalma d-dinja saret aktar globalizzata, huwa dejjem aktar importanti għall-iżviluppaturi tal-web li jibnu applikazzjonijiet li jistgħu jilqgħu lill-utenti minn pajjiżi u kulturi differenti. Wieħed mill-modi ewlenin biex dan jinkiseb huwa permezz tal-internazzjonalizzazzjoni (i18n), li tippermettilek taġġusta l-applikazzjoni tiegħek għal lingwi, muniti, u formati ta’ data differenti.

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

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

Pass 1: Installa librerija ta’ i18n

Biex tapplika l-internazzjonalizzazzjoni fl-applikazzjoni Next.js tiegħek, l-ewwel nerġgħu nagħżlu librerija i18n. Hemm diversi libreriji popolari, inkluż next-intl. F’dan l-eżempju, madankollu, se nużaw TacoTranslate.

TacoTranslate jittraduċi awtomatikament il-kordi tiegħek għal kwalunkwe lingwa billi juża AI avvanzat, u jħalli inti liberu mill-immaniġġjar tedjanti ta’ fajls JSON.

Ejjew nassistu installah 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 kont TacoTranslate tiegħek, proġett ta' traduzzjoni, u ċ-ċwievet API assoċjati. Oħloq kont hawn. Huwa b'xejn, u ma jeħtieġlekx iżżid karta ta' kredit.

Fil-UI tal-applikazzjoni TacoTranslate, oħloq proġett, u ħu direzzjoni lejn it-tab tal-API keys tiegħu. Oħloq ċavetta waħda read u ċavetta waħda read/write. Se nħażżuhom bħala varjabbli ambjentali. Iċ-ċavetta read hija dak li nsejħulu public u ċ-ċavetta read/write hija secret. Per eżempju, tistaʼ iżżidhom f’fajl .env fir-root tal-proġett tiegħek.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Kun żgur li qatt ma tiskatta’ ċ-ċavetta sigrieta read/write API għall-ambjenti tal-produzzjoni tal-klijent.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Il-kodiċi tal-lokal standard għat-tieħid b'rikonoxximent. F’dan l-eżempju, se nissettjawh għal en għall-Ingliż.
• TACOTRANSLATE_ORIGIN: Il-“folder” fejn se jinżammu l-korda tiegħek, bħal l-URL tas-sit web tiegħek. Ikteb aktar dwar il-begħdid hawn.

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

Pass 3: Twaqqif ta’ TacoTranslate

Biex tintegra TacoTranslate mal-applikazzjoni tiegħek, tkun trid toħloq client 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;

Aħna se nkunu qed niddefinixxu b'mod awtomatiku TACOTRANSLATE_API_KEY u TACOTRANSLATE_PROJECT_LOCALE dalwaqt.

Il-ħolqien tal-klijent f'file separat jagħmilha faċli li jerġa' jintuża aktar tard. getLocales huwa biss funzjoni ta' utility b'xi ħażin imħaddem ġewwa. Issa, oħloq file 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 turi li dan huwa komponent tal-klijent.

Bil-fornitur tal-kuntest issa lest biex jintuża, toħloq fajl bl-isem /app/[locale]/layout.tsx, il-layout radikali fl-applikazzjoni tagħna. Nota li dan il-path 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 innota hawn hija li qed nużaw il-parametru Dynamic Route [locale] tagħna biex niġbdu t-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 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 tgħid lil Next.js biex jerġa’ jibni l-paġna wara 60 sekonda, u żomm it-traduzzjonijiet tiegħek aġġornati.

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

TacoTranslate jappoġġa r-rendering fuq in-naħa tal-server. Dan itejjeb ħafna l-esperjenza tal-utent billi juri kontenut tradott immedjatament, minflok flash ta' kontenut mhux tradott fl-ewwel. Barra minn hekk, nistgħu ninsew il-mistoqsijiet tan-netwerk fuq il-klijent, għax diġà għandna t-traduzzjonijiet li għandna bżonn għall-paġna li l-utent qed jara.

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

Immodifika ċ-ċekk isProduction biex ikun adattat għas-setup tiegħek. Jekk true, TacoTranslate se joħroġ iċ-ċavetta API pubblika. Jekk ninsabu f'ambjent lokali, tat-test, jew ta 'staging (isProduction is false), aħna nużaw iċ-ċavetta sigrieta read/write API biex niżguraw li stringi ġodda jintbagħtu għat-traduzzjoni.

Biex niżguraw li r-routing u r-redirect jaħdmu kif mistenni, se jkollna noħolqu fajl imsejjaħ /middleware.ts. Bl-użu ta’ Middleware, nistgħu nirrikorru 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 tistabbilixxi l-matcher skont id dokumentazzjoni tal-Next.js Middleware.

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

Pass 5: Ibiegħ u ipprova!

Lestna! L-applikazzjoni React tiegħek issa se tiġi tradotta awtomatikament meta żżid kwalunkwe stringa fi Translate komponent. Nota li biss l-ambjenti b’permessi read/write fuq il-API key se jkunu jistgħu joħolqu stringi ġodda biex 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, iżżid stringi ġodda qabel taċċendi għax-xogħol. Dan se jipprevjeni lil ħadd milli jisraq il-API key sigur tiegħek, u potenzjalment jiżdied il-proġett tat-traduzzjoni tiegħek billi jiġu miżjuda stringi ġodda u mhux relatati.

Kun żgur li tiċċekkja l-eżempju sħiħ fuq il-profil tagħna ta’ GitHub. Hemmhekk, ser issib ukoll eżempju ta’ kif tagħmel dan billi tuża Pages Router! Jekk tiffaċċja xi problemi, tinsiex tikkuntattjana, u inkunu ferm kuntenti ngħinuk.

TacoTranslate jippermettilek lokalizzazzjoni awtomatika tal-applikazzjonijiet React tiegħek b’mod mgħaġġel għal u minn kwalunkwe lingwa. Ibda illum!