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

Ahogy a világ egyre inkább globalizálódik, egyre fontosabbá válik a webfejlesztők számára, hogy olyan alkalmazásokat készítsenek, amelyek különböző országokból és kultúrákból érkező felhasználókat is képesek kiszolgálni. Ennek egyik kulcsfontosságú eszköze az internacionalizáció (i18n), amely lehetővé teszi az alkalmazás különböző nyelvekhez, pénznemekhez és dátumformátumokhoz történő igazítását.

Ebben a cikkben bemutatjuk, hogyan adhatsz internacionalizációt a React Next.js alkalmazásodhoz szerveroldali rendereléssel. TL;DR: Teljes példát itt találod.

Ez az útmutató azoknak a Next.js alkalmazásoknak szól, amelyek a App Router használatával működnek.
Ha a Pages Router használatával dolgozol, inkább ezt az útmutatót nézd meg.

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

Ahhoz, hogy nemzetközivé tegyük a Next.js alkalmazásodat, először válasszunk egy i18n könyvtárat. Számos népszerű könyvtár létezik, köztük next-intl. Ebben a példában azonban a TacoTranslate-t fogjuk használni.

A TacoTranslate csúcstechnológiás mesterséges intelligencia segítségével automatikusan lefordítja a szövegeidet bármely nyelvre, és megszabadít a JSON-fájlok fárasztó kezelésétől.

Telepítsük a terminálban npm használatával:

npm install tacotranslate

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

Most, hogy telepítetted a modult, ideje létrehozni a TacoTranslate-fiókodat, egy fordítási projektet és a hozzá tartozó API-kulcsokat. Regisztrálj itt. Ingyenes, és nem kell bankkártyát megadnod.

A TacoTranslate alkalmazás felhasználói felületén hozzon létre egy projektet, majd lépjen az API-kulcsok fülre. Hozzon létre egy read kulcsot és egy read/write kulcsot. Elmentjük őket környezeti változókként. A read kulcs az, amit public néven hívunk, a read/write kulcs pedig secret. Például hozzáadhatja őket a projekt gyökerében található .env fájlhoz.

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 a kliensoldali éles környezetbe.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Az alapértelmezett tartalék (fallback) locale-kód. Ebben a példában az angolhoz en-t állítjuk be.
• TACOTRANSLATE_ORIGIN: Az a „mappa”, ahol a szövegeid lesznek tárolva, például a weboldalad URL-je. További információ az originokról itt.

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

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

Ahhoz, hogy integráld a TacoTranslate-et az alkalmazásodba, létre kell hoznod egy klienst a korábban megadott API-kulcsok felhasználásával. Például hozz létre egy /tacotranslate-client.js nevű fájlt.

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;

Hamarosan automatikusan beállítjuk a TACOTRANSLATE_API_KEY és a TACOTRANSLATE_PROJECT_LOCALE változókat.

A kliens külön fájlban történő létrehozása megkönnyíti annak későbbi újrafelhasználását. A getLocales csupán 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>
	);
}

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

Miután a kontextus-szolgáltató most már készen áll, hozz létre egy /app/[locale]/layout.tsx nevű fájlt, amely az alkalmazásunk gyökér-elrendezése. Figyeld meg, hogy ez az útvonal egy olyan mappát használ, amely Dynamic Routes, 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]-t használjuk annak a nyelvnek a fordításainak lekérésére. Emellett a generateStaticParams biztosítja, hogy a projektedhez aktivált összes locale kód előre renderelve legyen.

Most építsük fel az első oldalunkat! Hozz létre egy /app/[locale]/page.tsx nevű fájlt.

import React from 'react';
import {Translate} from 'tacotranslate/react';

export const revalidate = 60;
export default async function Page() {
	return (
		<Translate string="Hello, world!" />
	);
}

Jegyezd 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ásokat.

4. lépés: Szerveroldali 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, mert a fordított tartalmat azonnal megjeleníti, ahelyett, hogy először a le nem fordított tartalom villanna fel. Emellett megspórolhatjuk a kliensoldali hálózati kéréseket, mivel már rendelkezünk a megtekintett oldalhoz szükséges fordításokkal.

A szerveroldali renderelés beállításához hozza létre vagy módosítsa a /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};
};

Módosítsd a isProduction ellenőrzést, hogy megfeleljen a beállításaidnak. Ha true, a TacoTranslate megjeleníti a nyilvános API-kulcsot. Ha helyi, teszt vagy staging környezetben vagyunk (isProduction is false), a titkos read/write API-kulcsot fogjuk használni, hogy biztosítsuk, hogy az új stringek fordításra kerüljenek.

Az útválasztás és az átirányítás a várt módon történő működésének biztosítása érdekében létre kell hoznunk egy /middleware.ts nevű fájlt. A Middleware használatával átirányíthatjuk a felhasználókat az általuk preferált nyelven megjelenített oldalakra.

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 megfeleljen a Next.js Middleware dokumentációjának.

A kliensoldalon megváltoztathatod a locale cookie értékét, hogy beállítsd, melyik nyelvet részesíti előnyben a felhasználó. Kérlek, tekintsd meg a teljes példakódot, hogy ötleteket kapj arra, hogyan lehet ezt megtenni!

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. Figyelem, csak azok a környezetek, amelyeknél az API-kulcshoz read/write jogosultság tartozik, tudnak új, lefordítandó szövegeket létrehozni. Ajánlott egy zárt, biztonságos staging környezetet fenntartani, ahol ilyen API-kulccsal tesztelheted az éles alkalmazásodat, és az élesítés előtt hozzáadhatod az új szövegeket. Ez megakadályozza, hogy bárki ellopja a titkos API-kulcsodat, és potenciálisan felduzzassza a fordítási projektedet új, nem kapcsolódó szövegek hozzáadásával.

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!