Hogyan valósítsuk meg a nemzetközivé tételt 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 építsenek, amelyek különböző országokból és kultúrákból származó felhasználók igényeit képesek kielégíteni. Ennek egyik kulcsfontosságú módja az internacionalizáció (i18n), amely lehetővé teszi, hogy alkalmazásodat különböző nyelvekre, pénznemekre és dátumformátumokra szabjad.

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

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

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

Ahhoz, hogy nemzetköziesítést valósítsunk meg a Next.js alkalmazásodban, először válasszunk egy i18n könyvtárat. Számos népszerű könyvtár létezik, többek között a next-intl. Ebben a példában azonban a TacoTranslate használatára fogunk támaszkodni.

A TacoTranslate automatikusan lefordítja a szövegeidet bármilyen nyelvre a legmodernebb mesterséges intelligencia segítségével, és megszabadít a JSON fájlok bonyolult kezelésétől.

Telepítsük az 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, itt az ideje, hogy létrehozd a TacoTranslate fiókodat, egy fordítási projektet, és a hozzá tartozó API kulcsokat. Hozz létre fiókot itt. Ingyenes, és nem kell hitelká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óként fogjuk menteni. A read kulcsot nevezzük public-nak, míg a read/write kulcs az secret kulcs. Például hozzáadhatod őket egy .env fájlhoz a projekt 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árgasd ki a kliens oldali éles környezetekbe.

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 az en értéket adjuk meg angol nyelvhez.
• TACOTRANSLATE_ORIGIN: Az a „mappa”, ahol a szövegeid tárolva lesznek, például a webhelyed URL-je. További információk az eredet helyekről itt.

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

3. lépés: 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 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 definiálni fogjuk a TACOTRANSLATE_API_KEY és a TACOTRANSLATE_PROJECT_LOCALE változókat.

A kliens létrehozása külön fájlban megkönnyíti a későbbi újrahasználatot. 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 arra utal, 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 az Dynamic Route paraméterünket, a [locale] elemet használjuk arra, hogy lekérjük az adott nyelvhez tartozó fordításokat. Ezenkívül a generateStaticParams biztosítja, hogy a projektedhez aktivált összes nyelvkód előre le 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 tartsa naprakészen a fordításaidat.

4. lépés: A 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. Emellett 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 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 a 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), 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 az átirányítás a vártnak megfelelően működjön, létre kell hoznunk egy fájlt /middleware.ts. 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);
}

Ügyelj arra, hogy a matcher 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, 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. Ne feledd, hogy csak azok a környezetek, amelyek rendelkeznek a read/write jogosultságokkal az API kulcson, képesek új fordítandó szövegek létrehozására. Javasoljuk, hogy legyen egy zárt és biztonságos staging környezeted, ahol ilyen API kulccsal tesztelheted az éles alkalmazásodat, új szövegeket hozzáadva még az éles indulás előtt. Ez megakadályozza, hogy bárki ellopja a titkos API kulcsodat, és lehetséges, hogy a fordítási projekted feleslegesen nagyra növekedjen ú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!