Hogyan valósítsuk meg a nemzetköziesítést egy Next.js alkalmazásban, amely a App Router-t használja

Ahogy a világ egyre globalizáltabbá válik, egyre fontosabbá válik a webfejlesztők számára, hogy olyan alkalmazásokat építsenek, amelyek különböző országokból és kultúrákból származó felhasználókat is kiszolgálnak. Ennek egyik kulcsfontosságú módja az internacionalizáció (i18n), amely lehetővé teszi az alkalmazásod adaptálását különböző nyelvekre, pénznemekre és dátumformátumokra.

Ebben a cikkben megvizsgáljuk, hogyan adhatsz internacionalizációt a React Next.js alkalmazásodhoz, szerver oldali rendereléssel együtt. TL;DR: Teljes példa itt.

Ez az útmutató Next.js alkalmazások számára készült, amelyek a App Router-t használják.
Ha a Pages Router-t használod, akkor helyette ezt az útmutatót nézd meg.

1. lépés: Telepíts egy i18n könyvtárat

A Next.js alkalmazásodban az internacionalizáció (i18n) megvalósításához először ki fogunk választani egy i18n könyvtárat. Több népszerű könyvtár is elérhető, például a next-intl. Ebben a példában azonban a TacoTranslate használatára fogunk törekedni.

A TacoTranslate a legmodernebb MI segítségével automatikusan fordítja le a sztringjeidet bármely nyelvre, és megszabadít a JSON-fájlok unalmas kezelésétől.

Telepítsük a npm segítségével a terminálodban:

npm install tacotranslate

2. lépés: Hozz létre egy ingyenes TacoTranslate fiókot

Most, hogy telepítetted a modult, ideje létrehoznod a TacoTranslate fiókodat, egy fordítási projektet és a hozzá tartozó API-kulcsokat. Itt létrehozhatod a fiókot. Ingyenes, és nem szükséges hozzá bankkártyát megadni.

A TacoTranslate alkalmazás felületén hozz létre egy projektet, majd navigálj az API kulcsok fülre. Hozz létre egy read kulcsot és egy read/write kulcsot. Ezeket környezeti változókként fogjuk elmenteni. A read kulcsot nevezzük public kulcsnak, míg a read/write kulcs az secret. Például hozzáadhatod őket egy .env fájlhoz a projekted gyökérkönyvtárában.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Győződj meg róla, hogy a titkos read/write API kulcsot soha ne szivárogtasd ki kliens oldali éles környezetben.

Hozzáadunk még két környezeti változót is: TACOTRANSLATE_DEFAULT_LOCALE és TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Az alapértelmezett visszaesési helyi beállítás kódja. Ebben a példában az en-t állítjuk be, ami angol nyelvet jelent.
• TACOTRANSLATE_ORIGIN: Az a „mappa”, ahol a szövegeidet tárolni fogjuk, például a weboldalad URL-címe. Erről az originről itt olvashatsz többet.

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

3. lépés: TacoTranslate beállítása

Ahhoz, hogy integráld a TacoTranslate-et az alkalmazásodba, létre kell hoznod egy klienst a korábban létrehozott API-kulcsok felhasználásával. Például hozz létre egy fájlt /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;

Automatikusan definiálni fogjuk a TACOTRANSLATE_API_KEY és a TACOTRANSLATE_PROJECT_LOCALE értékeket hamarosan.

A kliens külön fájlban való létrehozása megkönnyíti a későbbi újrafelhasználást. getLocales csak egy segédfüggvény, némi beépített hibakezeléssel. Most hozz létre egy /app/[locale]/tacotranslate.tsx nevű fájlt, ahol megvalósítjuk a TacoTranslate providert.

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

Jegyezd meg a 'use client'; jelzést, amely azt mutatja, hogy ez egy kliens komponens.

Miután a context provider elkészült, hozz létre egy fájlt /app/[locale]/layout.tsx, amely az alkalmazásunk gyökér layout-ja. Vedd észre, hogy ez az útvonal egy olyan mappát használ, amely Dynamic Routes funkcióra épül, ahol a [locale] a dinamikus paraméter.

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

Az első dolog, amit érdemes megjegyezni, hogy a Dynamic Route paraméterünket, a [locale] használjuk az adott nyelv fordításainak lekérésére. Ezenkívül a generateStaticParams gondoskodik arról, hogy a projektedhez aktivált összes locale kód előre legyen renderelve.

Most építsük meg az első oldalunkat! Hozz létre egy fájlt /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!" />
	);
}

Figyeld meg a revalidate változót, amely megmondja a Next.js-nek, hogy 60 másodperc után újraépítse az oldalt, és naprakészen tartsa a fordításaidat.

4. lépés: Szerver oldali renderelés megvalósítása

A TacoTranslate támogatja a szerveroldali renderelést. Ez jelentősen javítja a felhasználói élményt azáltal, hogy azonnal megjeleníti a lefordított tartalmat ahelyett, hogy először egy pillanatra nem lefordított tartalom jelenne meg. Ezenkívül kihagyhatjuk a hálózati kéréseket az ügyféloldalon, mert már rendelkezünk a felhasználó által megtekintett oldalhoz szükséges fordításokkal.

A szerveroldali megjelenítés beállításához hozz létre vagy módosítsd a /next.config.js fájlt:

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

Módosítsd az isProduction ellenőrzést a saját beállításodhoz igazítva. Ha true, a TacoTranslate a nyilvános API kulcsot fogja használni. Ha helyi, teszt vagy staging környezetben vagyunk (isProduction is false), akkor a titkos read/write API kulcsot használjuk, hogy az új szövegek fordításra kerüljenek.

Annak érdekében, hogy a routing és az átirányítás a vártnak megfelelően működjön, létre kell hoznunk egy fájlt /middleware.ts. Middleware segítségével átirányíthatjuk a felhasználókat olyan oldalakra, amelyek az ő preferált nyelvükön jelennek meg.

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

Győződj meg róla, hogy a matcher beállítása megfelel a Next.js Middleware dokumentációjának.

A kliens oldalon megváltoztathatod a locale süti értékét, hogy módosítsd a felhasználó preferált nyelvét. Kérjük, nézd meg a teljes példakódot!

5. lépés: Telepítés és tesztelés!

Kész vagyunk! A React alkalmazásod mostantól automatikusan le lesz fordítva, amikor bármilyen szöveget hozzáadsz egy Translate komponenshez. Fontos megjegyezni, hogy csak azok a környezetek tudnak új, lefordítandó szövegeket létrehozni, amelyek rendelkeznek read/write jogosultsággal az API kulcson. Ajánljuk, hogy legyen egy zárt és biztonságos staging környezeted, ahol ezzel az API kulccsal tesztelheted az éles alkalmazásodat, és hozzáadhatod az új szövegeket, mielőtt élesítenéd. Ez megakadályozza, hogy bárki ellopja a titkos API kulcsodat, és ezzel esetleg felfújja a fordítási projektedet új, nem kapcsolódó szövegekkel.

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!