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

Ahogy a világ egyre inkább globalizálódik, 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 érkező felhasználók igényeit is ki tudják elégíteni. Egyik kulcsfontosságú módja ennek az internationalizáció (i18n), amely lehetővé teszi, hogy alkalmazásodat különböző nyelvekhez, valutákhoz és dátumformátumokhoz igazítsd.

Ebben a cikkben azt vizsgáljuk meg, hogyan adhatsz internationalizációt React Next.js alkalmazásodhoz, szerver oldali rendereléssel. TL;DR: A teljes példát itt találod.

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, nézd meg inkább ezt az útmutatót.

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

A nemzetköziesítés (i18n) megvalósításához a Next.js alkalmazásodban először választanunk kell egy i18n könyvtárat. Több népszerű könyvtár is létezik, beleértve a next-intl-t. Ebben a példában azonban a TacoTranslate használatával dolgozunk.

A TacoTranslate a legmodernebb MI segítségével automatikusan lefordítja a szövegeidet bármilyen nyelvre, és megszabadít a JSON állományok unalmas kezelésétől.

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

npm install tacotranslate

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

Most, hogy telepítetted a modult, itt az ideje, hogy létrehozd a TacoTranslate fiókodat, egy fordítási projektet és a hozzá tartozó API kulcsokat. Hozz létre itt egy fiókot. Ingyenes, és nem kell hozzá bankkártyát megadnod.

A TacoTranslate alkalmazás felhasználói 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-nak, míg a read/write kulcs a secret. Például hozzáadhatod őket egy .env fájlhoz a projekted gyökerében.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Ügyelj arra, hogy a titkos read/write API kulcsot soha ne szivárogtasd ki a kliens oldali é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 nyelvkód. Ebben a példában en-re állítjuk, ami az angol nyelvet jelenti.
• TACOTRANSLATE_ORIGIN: Az a „mappa”, ahol a szövegeid tárolva lesznek, például a webhelyed URL-je. További információ az origin-ekről itt.

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

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

A TacoTranslate integrálásához az alkalmazásodba létre kell hoznod egy klienset a korábban megszerzett API kulcsok segítségével. Például készíts 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;

Rövidesen automatikusan definiálni fogjuk a TACOTRANSLATE_API_KEY és TACOTRANSLATE_PROJECT_LOCALE változókat.

A kliens létrehozása külön fájlban megkönnyíti a későbbi újrafelhasználást. A getLocales csak egy segédfüggvény 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>
	);
}

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

Most, hogy a context provider készen áll, hozz létre egy fájlt /app/[locale]/layout.tsx, ami az alkalmazásunk gyökér layout-ja. Vedd észre, hogy ez az útvonal egy mappát használ, amely Dynamic Routes funkciót alkalmaz, 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ünket, a [locale] használjuk annak a nyelvnek a fordításainak lekéréséhez. Ezen felül a generateStaticParams gondoskodik arról, hogy az összes, a projekted számára aktivált helyi 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 fel az oldalt, és tartsa naprakészen a fordításaidat.

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

A TacoTranslate támogatja a szerver oldali 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 rövid időre megjelenne a nem lefordított tartalom. Ezenkívül kihagyhatjuk a hálózati kéréseket az ügyféloldalon, mert már megvannak a felhasználó által megtekintett oldalhoz szükséges fordítások.

A szerveroldali renderelés beállításához hozd 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ásaidnak megfelelően. 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 fogjuk használni annak biztosítására, hogy az új szövegek lefordításra kerüljenek.

Annak érdekében, hogy az útválasztás és átirányítás a vártnak megfelelően működjön, létre kell hoznunk egy /middleware.ts nevű fájlt. Middleware használatával át tudjuk irányítani 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);
}

Ügyelj rá, hogy a matcher beállítása megfeleljen a Next.js Middleware dokumentációnak.

A kliens oldalon megváltoztathatod a locale cookie-t, hogy módosítsd a felhasználó preferált nyelvét. Kérjük, tekintsd meg a teljes példa kódot!

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

Készen vagyunk! A React alkalmazásod mostantól automatikusan lefordításra kerül, amikor bármilyen szöveget hozzáadsz egy Translate komponenshez. Vedd figyelembe, hogy csak azok a környezetek, amelyek rendelkeznek az API kulcson read/write jogosultságokkal, képesek új, lefordítandó szövegeket létrehozni. Ajánljuk, hogy legyen egy zárt és biztonságos staging környezeted, ahol az ilyen API kulccsal tesztelheted az éles alkalmazásodat, és új szövegeket adhatsz hozzá a megjelenés előtt. Ez meggátolja, hogy bárki ellopja a titkos API kulcsodat, és potenciálisan felfújja 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!