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

Hekk kif id-dinja ssaħħaħ il-globalizzazzjoni, issir dejjem aktar importanti għall-iżviluppaturi tal-web li jibnu applikazzjonijiet li jistgħu jindirizzaw lill-utenti minn pajjiżi u kulturi differenti. Wieħed mill-aktar modi 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-artiklu, se nesploraw kif iżżid l-internazzjonalizzazzjoni fl-applikazzjoni React Next.js tiegħek, 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 qed jużaw App Router.
Jekk qed tuża Pages Router, ara din il-gwida minflok.

Pass 1: Installaw librerija i18n

Biex nimpenjawru 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 l-strings tiegħek għal kwalunkwe lingwa billi juża AI avvanzata, u jħallik mingħajr il-ġestjoni tedjuża tal-fajls JSON.

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

npm install tacotranslate

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

Issa li għandek il-modulu installat, wasal iż-żmien li toħloq il-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 tal-kreditu.

Binnen l-UI tal-applikazzjoni TacoTranslate, ħoloq proġett, u naviga għat-tab tal-API keys tiegħu. Ħoloq waħda read key, u waħda read/write key. Aħna se nħasbuhom bħala varjabbli ta’ ambjent. Il-key read huwa dak li nsejħulu public u l-key read/write huwa secret. Per eżempju, tista’ żżidhom f'file .env fir-root tal-proġett tiegħek.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Kun żgur li qatt ma tiċċara ċ-ċavetta sigrieta read/write API lill-ambjenti ta’ produzzjoni fuq in-naħa tal-klijent.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Il-kodiċi default tal-lokali ta’ fallback. F’dan l-eżempju, se nissettjawh għal en għall-Ingliż.
• TACOTRANSLATE_ORIGIN: Il-“folder” fejn se jinżammu s-siltiet tiegħek, bħal pereżempju l-URL tas-sit web tiegħek. Aqra aktar dwar l-origini hawn.

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

Pass 3: Setup ta’ TacoTranslate

Biex tintegra TacoTranslate fl-applikazzjoni tiegħek, ikollok bżonn toħloq client billi tuża ċavetti tal-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 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'mekkaniżmu sempliċi ta' ġestjoni tal-iżbalji. Issa oħloq fajl imsejjaħ /app/[locale]/tacotranslate.tsx, fejn se nimplementaw il-provider 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 notevoli hawn hi li qed nużaw il-parametru tagħna Dynamic Route [locale] biex nieħdu t-traduzzjonijiet għal dik il-lingwa. Barra minn hekk, generateStaticParams qed tiżgura li l-kodiċijiet tal-lokal kollha li attivajt għall-proġett tiegħek jiġu pre-rendered.

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

TacoTranslate jappoġġja server side rendering. Dan jtejjeb b'mod kbir l-esperjenza tal-utent billi turi l-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ħall-paġna li qed jiċċekkjaha l-utent.

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};
};

Ipprova isProduction biex taqbel mas-settings tiegħek. Jekk true, TacoTranslate se juri l-API key pubblika. Jekk aħna f’ambjent lokali, ta’ test, jew ta’ staging (isProduction is false), se nużaw l-API key sigriet read/write biex niżguraw li l-kordi ġodda jintbagħtu għat-traduzzjoni.

Biex niżguraw li r-rotta u r-reindirizzar jaħdmu kif mistenni, ser ikollna bżonn noħolqu fajl imsejjaħ /middleware.ts. Billi nużaw Middleware, nistgħu nirriżoli utenti għal paġni ppreżentati bil-lingwa magħżula 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-Middleware ta’ Next.js.

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

Pass 5: Ibiegħ u ipprova!

Qed tlestna! L-applikazzjoni React tiegħek issa se tiġi tradotta awtomatikament meta żżid kwalunkwe strings ma’ komponent Translate. Innota li biss l-ambjenti b’permessi read/write fuq il-key tal-API se jkunu jistgħu joħolqu strings ġ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 strings ġodda qabel ma tmur live. Dan se jipprevjeni lil ħadd milli jġib il-key sigriet tiegħek tal-API, u potenzjalment jevita li l-proġett tat-traduzzjoni tiegħek jinqala’ b’strings ġodda u 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!