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

Ahogy a világ egyre globalizáltabbá válik, egyre fontosabb, hogy a webfejlesztők olyan alkalmazásokat készítsenek, amelyek különböző országokból és kultúrákból érkező felhasználók igényeit is kielégítik. Ennek egyik kulcsfontosságú módja az internacionalizáció (i18n), amely lehetővé teszi alkalmazásod igazítását különböző nyelvekhez, pénznemekhez és dátumformátumokhoz.

Ebben a cikkben bemutatjuk, hogyan adhatunk internacionalizációt a React Next.js alkalmazásunkhoz szerveroldali rendereléssel. TL;DR: Itt találod a teljes példát.

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 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 egy i18n könyvtárat választunk. Számos népszerű könyvtár létezik, többek között next-intl. Ebben a példában azonban a TacoTranslate használatára fogunk támaszkodni.

A TacoTranslate a legmodernebb 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álodban az 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 az ehhez tartozó API-kulcsokat. Itt hozhatsz létre fiókot. Ez ingyenes, és nem kell bankkártyát megadnod.

A 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. Ezeket környezeti változókként mentjük. A read kulcs az ún. public, a read/write kulcs pedig az ún. secret. 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

Ügyelj rá, hogy a titkos read/write API-kulcsot soha ne szivárgasd 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 (fallback) nyelvi kód. Ebben a példában az angolhoz a en-t állítjuk be.
• TACOTRANSLATE_ORIGIN: A „mappa”, ahová a sztringjeid kerülnek — 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

Ahhoz, hogy integráld a TacoTranslate-et az alkalmazásodba, létre kell hoznod egy klienst a korábban megadott API-kulcsokkal. 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 értékeit.

A kliens külön fájlba helyezése megkönnyíti a későbbi újrafelhasználást. getLocales csupán 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 szolgáltatójá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'; kifejezést; ez azt jelzi, hogy ez egy klienskomponens.

Most, hogy a kontextus-szolgáltató készen áll, hozz létre egy /app/[locale]/layout.tsx nevű fájlt, amely az alkalmazásunk gyökérelrendezése. Megjegyzés: ez az útvonal egy olyan mappát tartalmaz, amely a Dynamic Routes funkciót használ, 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]-t használjuk annak a nyelvnek a fordításainak lekérésére. Ezen felül a generateStaticParams gondoskodik arról, 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

TacoTranslate támogatja a szerveroldali renderelést. Ez jelentősen javítja a felhasználói élményt azáltal, hogy a lefordított tartalmat azonnal megjeleníti, ahelyett, hogy először egy rövid, nem lefordított tartalom villanását látnánk. Emellett kihagyhatjuk 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 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ítsa a isProduction ellenőrzését a beállításainak megfelelően. Ha true, a TacoTranslate a nyilvános API-kulcsot fogja megjeleníteni. 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 el legyenek küldve fordításra.

Annak biztosítása érdekében, hogy a routing é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 használatával á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 kliensoldalon módosíthatod a locale sütit, hogy megváltoztasd, melyik nyelvet részesíti előnyben a felhasználó. Kérlek, nézd meg a teljes példakódot, hogy ötleteket kapj arra, hogyan kell 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 stringet adsz hozzá egy Translate komponenshez. Ne feledd, hogy csak azok a környezetek tudnak új, lefordítandó stringeket létrehozni, amelyek az API-kulcson rendelkeznek 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 stringeket adhatsz hozzá az élesítés előtt. Ez megakadályozza, hogy bárki bárki ellopja a titkos API-kulcsodat, és esetleg felfújja a fordítási projektedet új, nem kapcsolódó stringek 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!