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

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

F’dan l-artiklu, se nesploraw kif iżżid l-internazzjonalizzazzjoni mal-applikazzjoni tiegħek ta' React Next.js, billi nużaw server side rendering. 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 dan il-gwida minflok.

Pass 1: Installa librerija i18n

Biex dan l-internazzjonalizzazzjoni tiġi implimentata fl-applikazzjoni Next.js tiegħek, l-ewwel se nagħżlu librerija i18n. Hemm diversi libreriji popolari, inkluż next-intl. Madankollu, fl-eżempju hawnhekk se nużaw TacoTranslate.

TacoTranslate tittraduċi awtomatikament il-strings tiegħek f'kull lingwa billi tuża AI avvanzata, u tħallik mingħajr il-ħidma tedjuża ta' ġestjoni ta' fajls JSON.

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

npm install tacotranslate

Pass 2: Oħloq kont b'xejn ma’ TacoTranslate

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

F'within l-UI tal-applikazzjoni TacoTranslate, oħloq proġett, u naviga għat-tab tal-API keys tiegħu. Oħloq waħda read key, u waħda read/write key. Se nħażnuhom bħala varjabbli ta' ambjent. Il-read key hija dak li ninsew bħala public u l-read/write key hija secret. Per eżempju, tista' żżidhom f'file .env fil-għerq tal-proġett tiegħek.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Kun żgur li qatt ma tgħaddi l-muftieħ sekret read/write tal-API għal ambjenti ta’ 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 default tal-lokalità fallback. F'dan l-eżempju, ser nissettjawh għal en għall-Ingliż.
• TACOTRANSLATE_ORIGIN: Il-“folder” fejn se jinħażnu l-kordi tiegħek, bħal URL tas-sit web tiegħek. Aqra iktar dwar l-origini hawn.

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

Pass 3: Setup ta' TacoTranslate

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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 niddefinixxu 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 hija biss funzjoni ta’ utilità b’xi ġestjoni tal-iżbalji mibnija ġewwa. Issa, toħ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>
	);
}

Notate 'use client'; li jindika li dan huwa komponent tal-klijent.

Bil-fornitur tal-kuntest issa lest biex jibda, oħloq fajl imsejjaħ /app/[locale]/layout.tsx, l-istruttura prinċipali fl-applikazzjoni tagħna. Innota li dan it-triq 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 hawnhekk hi li qed nużaw il-parametru Dynamic Route [locale] tagħna biex niksbu t-traduzzjonijiet għal dik il-lingwa. Barra minn hekk, generateStaticParams qed tiżgura li l-kodiċi kollha tal-lingwa li għamilt attiv għalihom il-proġett tiegħek jiġu ppre-rendjati.

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

Pass 4: Implimentazzjoni ta' server side rendering

TacoTranslate jappoġġja r-rendering fuq in-naħa tas-server. Dan ittejjeb ħafna l-esperjenza tal-utent billi juri kontenut tradott immedjatament, minflok flash 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 li għandna bżonn għal-paġna li l-utent qed jara.

Biex tissettja server side rendering, 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};
};

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-routering u r-redirects jaħdmu kif mistenni, se jkollna bżonn noħolqu fajl imsejjaħ /middleware.ts. Bl-użu ta’ Middleware, nistgħu nirrikorru lill-utenti għal paġni mressqa 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 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 l-eżempju kollu tal-kodiċi għal ideat dwar kif tagħmel dan!

Pass 5: Ibiegħ u ipprova!

Ġedna! L-applikazzjoni React tiegħek issa se tiġi tradotta awtomatikament meta żżid kwalunkwe strings ma’ komponent Translate. Innota li biss ambjenti b’permessi read/write fuq l-API key se jkunu jistgħu joħolqu strings ġodda biex jiġu tradotti. Nissuġġerixxu li jkollok ambjent ta’ staging magħluq u sigur fejn tista’ tittestja l-applikazzjoni ta’ produzzjoni tiegħek b’API key bħal dak, żid strings ġodda qabel tmur ħajja. Dan se jipprevjeni lil ħadd milli jisraq l-API key sigriet tiegħek, u potenzjalment jeħel il-proġett tat-traduzzjoni tiegħek billi żżid strings ġodda, mhux relatati.

Kun żgur li tiċċekkja l-eżempju sħiħ fuq il-profil tagħna fuq GitHub. Hemmhekk, se ssib ukoll eżempju ta’ kif tagħmel dan billi tuża Pages Router ! Jekk tispiċċa bi problemi, tħossok liberu li tikkuntattjana, u nkunu kuntenti ħafna li ngħinuk.

TacoTranslate jippermettilek li lokalizza awtomatikament l-applikazzjonijiet React tiegħek malajr għal u minn kwalunkwe lingwa. Ibda illum!