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 készítsenek, amelyek képesek kiszolgálni a különböző országokból és kultúrákból származó felhasználókat. Ennek egyik kulcsfontosságú módja az internacionalizá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 internacionalizációt a React Next.js alkalmazásodhoz, szerver oldali rendereléssel. TL;DR: A teljes példát itt találod.

Ez az útmutató a 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, akkor ezt az útmutatót nézd meg helyette.

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

A Next.js alkalmazásodban az internacionalizáció (i18n) megvalósításához először ki fogunk választani egy i18n könyvtárat. Több népszerű könyvtár is létezik, többek között a next-intl. Ebben a példában azonban a TacoTranslate könyvtárat fogjuk használni.

A TacoTranslate a legújabb 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 használatával a terminálban:

npm install tacotranslate

2. lépés: Hozz 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. Hozz létre fiókot itt. Ez 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 kulcsnak, 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 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 visszaesési locale kód. Ebben a példában az en-re állítjuk, ami angolt jelent.
• 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 originökről itt.

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

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

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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ékeket.

Ha az ügyfelet külön fájlban hozza létre, az később könnyen használható. getLocales csak egy segédprogram, beépített hibakezeléssel. Most hozzon létre egy nevű fájlt /app/[locale]/tacotranslate.tsx, ahol megvalósítjuk a TacoTranslate szolgáltató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>
	);
}

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

Most, hogy a kontextus szolgáltató készen áll, hozzon létre egy fájlt /app/[locale]/layout.tsx, amely alkalmazásunk gyökér elrendezése. Vegye figyelembe, hogy ez az útvonal egy mappát használ Dynamic Routes, 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. Ezenkívül a generateStaticParams gondoskodik arról, hogy az összes, a projektedhez aktivált lokálkód elő 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 a lapot 60 másodperc után újraépítse, és így naprakészen tartsa 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 felvillanó, le nem fordított tartalmat mutatna. Ezenkívül kihagyhatjuk a hálózati kéréseket a kliens oldalon, mivel 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 az isProduction ellenőrzést a saját környezetedhez igazítva. 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 használjuk, hogy biztosítsuk az új szövegek lefordításra küldését.

Annak biztosítására, 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 /middleware.ts nevű fájlt. 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ónak.

A kliens oldalon módosíthatod a locale sütit, hogy megváltoztasd 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 read/write jogosultságokkal az API kulcson, tudnak új szövegeket létrehozni fordításra. Ajánlott egy zárt és biztonságos staging környezet kialakítása, ahol tesztelheted az éles alkalmazásodat egy ilyen API kulccsal, mielőtt élesbe mész, új szövegeket hozzáadva. Ez megakadályozza, hogy bárki ellopja a titkos API kulcsodat, és potenciálisan felduzzaszthassa a fordítási projektedet új, idegen szövegek hozzáadásával.

Mindig nézd meg a teljes példát a GitHub profilunkon. Ott találsz egy példát arra is, hogyan lehet ezt megvalósítani a Pages Router használatával! Ha bármilyen problémába ütközöl, bátran keress meg minket, és örömmel segítünk.

A TacoTranslate lehetővé teszi, hogy React alkalmazásaidat automatikusan lokalizáld gyorsan bármely nyelvre és onnan. Kezdd el még ma!