Hogyan valósítsuk meg az internacionalizációt (i18n) egy Next.js alkalmazásban, amely a App Router-t használ?

Ahogy a világ egyre inkább globalizálódik, egyre fontosabb, hogy a webfejlesztők olyan alkalmazásokat építsenek, amelyek különböző országokból és kultúrákból érkező felhasználókat is kiszolgálják. Ennek egyik kulcsfontosságú módja a nemzetközivé tétel (i18n), amely lehetővé teszi az alkalmazásod adaptálását különböző nyelvekhez, valutákhoz és dátumformátumokhoz.

Ebben a cikkben azt mutatjuk be, hogyan adhatsz nemzetközivé tételt a React Next.js alkalmazásodhoz szerveroldali rendereléssel. TL;DR: Tekintsd meg a teljes példát itt.

Ez az útmutató Next.js-alkalmazásokhoz készült, amelyek a App Router-t használják.
Ha a Pages Router-t használod, nézd meg inkább ezt az útmutatót.

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

A Next.js alkalmazásod nemzetközivé tételéhez először ki kell választanunk 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-et fogjuk használni.

A TacoTranslate a legkorszerűbb 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 az npm segítségével a terminálodban:

npm install tacotranslate

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

Miután 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 hitelkártyát megadnod.

Az 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. Környezeti változóként fogjuk elmenteni őket. A read kulcs az, amit public néven hívunk, a read/write kulcs pedig secret. Például hozzáadhatod őket a projekt gyökérkönyvtárában található .env fájlhoz.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Ügyeljen arra, hogy soha ne szivárogtassa ki a titkos read/write API-kulcsot a kliensoldali éles környezetekbe.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Az alapértelmezett tartalék (fallback) locale kódja. Ebben a példában en-re állítjuk, azaz angolra.
• TACOTRANSLATE_ORIGIN: Az a „mappa”, ahová a stringjeid lesznek tárolva, például a webhelyed URL-je. Bővebben az originokról itt.

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

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

A TacoTranslate alkalmazásba való integrálásához létre kell hoznod egy klienst a korábban említett API-kulcsok használatával. Például hozz létre egy fájlt, amelynek neve /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;

Hamarosan automatikusan beállítjuk a TACOTRANSLATE_API_KEY és a TACOTRANSLATE_PROJECT_LOCALE értékét.

A kliens külön fájlban történő létrehozása megkönnyíti a későbbi újrafelhasználását. getLocales mindössze 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 providerét.

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

Vedd figyelembe a 'use client'; megjelölést, ami azt jelzi, hogy ez egy kliens komponens.

Miután a kontextus szolgáltató most már készen áll, hozd létre a /app/[locale]/layout.tsx nevű fájlt — ez az alkalmazásunk gyökér-elrendezése. Megjegyzés: ez az útvonal egy olyan mappát tartalmaz, amely a Dynamic Routes használatával működik, 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 az adott nyelv fordításainak lekérésére. Ezenkívül a generateStaticParams biztosítja, hogy a projektedben aktivált összes locale-kód előre legyen renderelve.

Most építsük meg 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!" />
	);
}

Vedd figyelembe a revalidate változót, amely arra utasítja a Next.js-t, hogy 60 másodperc után újraépítse az oldalt, és naprakészen tartsa a fordításaidat.

4. lépés: A szerveroldali renderelés megvalósítása

A TacoTranslate támogatja a szerveroldali renderelést. Ez nagymértékben javítja a felhasználói élményt, mivel a fordított tartalmat azonnal megjeleníti, ahelyett, hogy először egy le nem fordított tartalom jelenne meg. Ezen felül elkerülhetjük a kliensoldali hálózati kéréseket, mert már rendelkezünk a felhasználó által megtekintett oldalhoz szükséges fordításokkal.

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

Állítsd be az isProduction ellenőrzést a beállításaidnak megfelelően. 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 az új szövegek biztosan fordításra kerüljenek.

Annak érdekében, hogy az útválasztás és az átirányítás az elvártaknak megfelelően működjön, 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 megfelel a Next.js Middleware dokumentációjának.

A kliensoldalon módosíthatod a locale cookie-t, hogy megváltoztasd a felhasználó preferált nyelvét. Kérlek, nézd meg a a teljes példakódot ötletekért, hogyan kell ezt megtenni!

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

Készen vagyunk! A React-alkalmazásod mostantól automatikusan le lesz fordítva, amikor bármilyen szöveget hozzáadsz egy Translate komponenshez. Ne feledd, hogy csak azok a környezetek, amelyeknél az API-kulcs rendelkezik read/write jogosultsággal, tudnak új, lefordítandó szövegeket létrehozni. Javasoljuk, hogy legyen egy zárt és biztonságos staging környezeted, ahol egy ilyen API-kulccsal tesztelheted az éles alkalmazásodat, és új szövegeket adhatsz hozzá az éles indulás előtt. Ez megakadályozza, hogy bárki bárki ellopja a titkos API-kulcsodat, és esetleg 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!