Kif timplimenta l-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ħal applikazzjonijiet Next.js li qed jużaw il-App Router.
Jekk qed tuża 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 ta' TacoTranslate

Issa li għandek il-modulu installat, wasal iż-żmien li toħloq kont fuq TacoTranslate, proġett ta’ traduzzjoni, u ċavetti API assoċjati. Oħloq kont hawn. Huwa b'xejn, u ma jeħtieġlekx żżid karta tal-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 tirrilaxxa l-ċavetta API sigrieta read/write fl-ambjenti ta' produzzjoni fuq in-naħa tal-klijent.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Il-kodiċi tal-lokalità tal-fallback predefinit. F'dan l-eżempju, se nissettjawh fuq en għall-Ingliż.
• TACOTRANSLATE_ORIGIN: Il-“folder” fejn se jinżammu l-strings tiegħek, bħal pereżempju l-URL tas-sit tiegħek. Aqra aktar dwar l-origini hawn.

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

Pass 3: It-twaqqif ta' TacoTranslate

Biex tintegra TacoTranslate fl-applikazzjoni tiegħek, se jkollok bżonn toħloq klijent li juża l-API keys li semmejna 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 niddedefinixxu awtomatikament 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 jindika 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 hi li qed nużaw il-parametru Dynamic Route [locale] biex nġibu t-traduzzjonijiet għal dik il-lingwa. Barra minn hekk, generateStaticParams qed tiżgura li l-kodiċi kollha tal-lingwi li għandek attivati għall-proġett tiegħek jiġu ppre-renderjati.

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 rendering fuq in‑naħa tas‑server. Dan jtejjeb b'mod sinifikanti l‑esperjenza tal‑utent billi juri l‑kontenut tradott immedjatament, minflok ma jidher l‑ewwel kontenut mhux tradott. Barra minn hekk, nistgħu nevitaw it‑talbiet tan‑network fuq il‑klijent, għax diġà għandna t‑traduzzjonijiet li neħtieġu għall‑paġna li l‑utent qed jara.

Biex tissettja renderizzar 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-reindirizzament jaħdmu kif mistenni, jkollna bżonn noħolqu fajl imsejjaħ /middleware.ts. Bl-użu ta' Middleware, nistgħu nirreindirizzaw l-utenti lejn 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' tibdel il-cookie locale biex tibdel x'inhi l-lingwa preferuta tal-utent. Ara il-kodiċi tal-eżempju sħiħ għal ideat dwar kif tagħmel dan!

Pass 5: Ippubblika u ittestja!

Għamilna! L-applikazzjoni React tiegħek issa se tiġi tradotta awtomatikament meta żżid kwalunkwe stringa f'komponent Translate. Nota li biss l-ambjenti li għandhom permessi read/write fuq iċ-ċavetta tal-API se jkunu jistgħu joħolqu stringi ġodda għall-traduzzjoni. Nirrakkomandaw li jkollok ambjent ta' staging magħluq u sigur fejn tkun tista' tittestja l-applikazzjoni tal-produzzjoni tiegħek b'iċ-ċavetta tal-API bħal dik, u żżid stringi ġodda qabel tmur live. Dan jipprevjeni li xi ħadd jisraq iċ-ċavetta tal-API sigrieta tiegħek, u potenzjalment jkabbar b'mod mhux mixtieq il-proġett tat-traduzzjoni tiegħek billi żżid stringi ġ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!