Kif wieħed japplika l-internazzjonalizzazzjoni f’applicazzjoni Next.js li qed tuża App Router

Hekk kif id-dinja qed issir aktar globalizzata, huwa 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-modi ewlenin biex dan jintlaħaq huwa permezz tal-internazzjonalizzazzjoni (i18n), li tippermettilek taġġusta l-applikazzjoni tiegħek għal lingwi, muniti, u formati ta’ data differenti.

TL;DR: Ara l-eżempju sħiħ hawn.

Dan il-gwida huwa 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 i18n

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

TacoTranslate jittraduċi aġilment il-kordi tiegħek għal kwalunkwe lingwa billi juża AI avvanzata, u jħallik mingħajr il-ġestjoni tedjanti tal-fajls JSON.

Ejjew naħdmuha bl-installazzjoni billi nużaw npm fit-terminal tiegħek:

npm install tacotranslate

Pass 2: Oħloq kont ħieles ta’ 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ġx li żżid karti ta' kreditu.

Binnen l-UI tal-applikazzjoni TacoTranslate, oħloq proġett, u imbagħad aqleb għal tab tal-keys API tiegħu. Oħloq wieħed read key, u wieħed read/write key. Se ninżluhom bħala varjabbli tal-ambjent. Il-key read hija dak li nsejħu public, u l-key read/write hija secret. Per eżempju, tista’ żż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 tħarrek il-miftuħ sigriet read/write API lejn l-ambjenti ta’ produzzjoni fuq in-naħa tal-klijent.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Il-kodiċi ta’ fallback tal-lokal default. F'dan l-eżempju, se nissettjawh għal en għall-Ingliż.
• TACOTRANSLATE_ORIGIN: Il-“folder” fejn se jinħażnu l-kordi tiegħek, bħal l-URL tas-sit web tiegħek. Aqra aktar dwar il-bidu hawn.

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

Pass 3: Twaqqif ta’ TacoTranslate

Biex tintegra TacoTranslate mal-applikazzjoni tiegħek, se jkun meħtieġ toħloq client billi tuża l-muftieħ tal-API li għadna kif għamilna t-tħejjija tagħhom 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 awtomatikament qed niddefinixxu TACOTRANSLATE_API_KEY u TACOTRANSLATE_PROJECT_LOCALE dalwaqt.

Il-ħolqien tal-klijent f’fajl separatut jagħmilha faċli li jintuża mill-ġdid aktar tard. getLocales hija biss funzjoni ta' utilità b'xi ġestjoni tal-iżbalji integrata. Issa, iġġenera 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>
	);
}

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

Bil-fornitur tal-kuntest issa lest biex jintuża, oħloq fajl li jismu /app/[locale]/layout.tsx, il-layout radikali fl-applikazzjoni tagħna. Noti 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 hawn hu li qed nużaw il-parametru Dynamic Route [locale] biex niksbu t-traduzzjonijiet għal dik il-lingwa. Barra minn hekk, generateStaticParams qed jassigura li l-kodiċi kollha tal-lokalitajiet li attivajt għall-proġett tiegħek jintwerew qabel il-ħin.

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 terġa' tibni l-paġna wara 60 sekonda, u żżomm it-traduzzjonijiet tiegħek aġġornati.

Pass 4: Implimentazzjoni ta’ server side rendering

TacoTranslate jappoġġja server side rendering. Dan ittejjeb ħafna l-esperjenza tal-utent billi juri kontenut tradott immedjatament, minflok flaġ ta' kontenut mhux tradott fil-bidu. Barra minn hekk, nistgħu nevitaw talbiet tan-netwerk fuq il-klijent, għaliex diġà għandna t-traduzzjonijiet li għandna bżonn għall-paġna li qed jara l-utent.

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

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-riedirezzjonament jaħdmu kif mistenni, ser ikollna bżonn noħolqu fajl imsejjaħ /middleware.ts. Bi użu ta’ Middleware, nistgħu niredirezzjonaw 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ħejji matcher skont id-dokumentazzjoni ta’ 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 komplet tal-kodiċi għal ideat dwar kif tagħmel dan!

Step 5: Iddeplowa u ipprova!

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

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

TacoTranslate jippermettilek li tlocalizza awtomatikament l-applikazzjonijiet React tiegħek malajr lejn u minn kwalunkwe lingwa. Ibda llum!