Hogyan valósítható meg a nemzetköziesítés (i18n) egy Next.js alkalmazásban, amely a App Router használatával működik

Ahogy a világ egyre inkább globalizálódik, egyre fontosabbá válik, 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álnak. Az egyik kulcsfontosságú mód ennek elérésére a nemzetköziesítés (i18n), amely lehetővé teszi, hogy az alkalmazásodat különböző nyelvekhez, pénznemekhez és dátumformátumokhoz igazítsd.

Ebben a cikkben azt vizsgáljuk meg, hogyan lehet nemzetköziesítést (i18n) hozzáadni a React Next.js alkalmazásodhoz szerveroldali rendereléssel. TL;DR: A teljes példát itt találod.

Ez az útmutató a Next.js alkalmazásokhoz készült, amelyek a App Router használatával készültek.
Ha a Pages Router használatában vagy, lásd helyette ezt az útmutatót.

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. Több népszerű könyvtár is létezik, többek között next-intl. Ebben a példában azonban a TacoTranslate használatát mutatjuk be.

A TacoTranslate csúcstechnológiás MI-t használva 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 a npm segítségével:

npm install tacotranslate

2. lépés: Hozzon 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. Regisztrálj itt. Ingyenes, és nem kell megadnod hitelkártyaadatokat.

A TacoTranslate alkalmazás felhasználói felületén hozz létre egy projektet, majd navigálj az API-kulcsok fülére. Hozz létre egy read kulcsot és egy read/write kulcsot. Elmentjük őket környezeti változókként. A read kulcsot nevezzük public-nak, a read/write kulcsot pedig secret-nek. Például hozzáadhatod őket a projekt gyökerében lévő .env fájlhoz.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Ügyelj rá, hogy a titkos read/write API-kulcsot soha ne szivárogtasd ki kliensoldali éles környezetekbe.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Az alapértelmezett tartalék (fallback) locale kódja. Ebben a példában az angolhoz en-et állítjuk be.
• TACOTRANSLATE_ORIGIN: A „mappa”, ahová a sztringjeid lesznek tárolva, például a weboldalad URL-je. Itt olvashatsz bővebben az originokról.

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

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

A TacoTranslate alkalmazásba történő integrálásához létre kell hoznod egy klienst a korábban megadott API-kulcsok felhasználásával. Például hozz létre egy fájlt a következő névvel: /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 definiáljuk TACOTRANSLATE_API_KEY és TACOTRANSLATE_PROJECT_LOCALE.

A kliens külön fájlba helyezése megkönnyíti annak későbbi újrahasználatát. 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>
	);
}

Ügyelj a 'use client'; jelölésre, amely azt jelzi, hogy ez egy klienskomponens.

Miután a kontextus-szolgáltató most már készen áll, hozd létre a /app/[locale]/layout.tsx nevű fájlt, amely az alkalmazásunk gyökér-elrendezése. Megjegyzés: ez az útvonal olyan mappát tartalmaz, amely a Dynamic Routes funkciót használja, ahol [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ünk, [locale], segítségével kérjük le az adott nyelv fordításait. Ezen felül a generateStaticParams gondoskodik arról, hogy a projektedben aktivált összes locale-kód előre renderelve legyen.

Most építsük meg az első oldalunkat! Hozz létre egy fájlt, amelynek a neve /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ásodpercenként építse újra az oldalt, és tartsa naprakészen a fordításaidat.

4. lépés: 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 azáltal, hogy a fordított tartalmat azonnal megjeleníti, ahelyett, hogy először egy felvillanó, lefordítatlan tartalmat mutatna. Ezenkívül mellőzhetjük az ügyféloldali hálózati kéréseket, mert már megvannak a megtekintett oldalhoz szükséges fordítások.

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 a beállításaidnak megfelelően. Ha true, a TacoTranslate láthatóvá teszi 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 sztringek biztosan el legyenek küldve fordításra.

Annak biztosításához, hogy az útválasztás és az átirányítás a várt módon működjön, létre kell hoznunk egy /middleware.ts nevű fájlt. A Middleware segítségével átirányíthatjuk a felhasználókat olyan oldalakra, amelyek a 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 módosíthatod a locale sütit, hogy megváltoztasd, melyik a felhasználó preferált nyelve. Tekintsd meg a teljes példakódot, ha ötleteket szeretnél arról, hogyan valósítsd ezt meg!

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. Felhívjuk a figyelmedet, hogy csak azok a környezetek tudnak új, lefordítandó szövegeket létrehozni, ahol az API-kulcs rendelkezik read/write jogosultsággal. Ajánljuk, hogy legyen egy zárt és biztonságos staging környezeted, ahol ilyen API-kulccsal tesztelheted az éles alkalmazásodat, és új szövegeket adhatsz hozzá, mielőtt élesbe kerülnél. 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ö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!