Hogyan valósítsuk meg a nemzetközivé tételt egy Next.js alkalmazásban, amely a App Router-t használja

Ahogy a világ egyre globalizáltabbá válik, egyre fontosabbá válik, hogy a webfejlesztők olyan alkalmazásokat építsenek, amelyek képesek kiszolgálni a különböző országokból és kultúrákból érkező felhasználókat. Az egyik kulcsfontosságú módja ennek az elérésére az internacionalizáció (i18n), amely lehetővé teszi, hogy alkalmazásodat a 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 React Next.js alkalmazásodhoz szerver oldali rendereléssel. TL;DR: Lásd a teljes példát itt.

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

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

Ahhoz, hogy nemzetköziesítést valósítsunk meg a Next.js alkalmazásodban, először választanunk kell egy i18n könyvtárat. Számos népszerű könyvtár létezik, beleértve a next-intl-t is. 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ármilyen nyelvre, és megszabadít a JSON fájlok fárasztó kezelésétől.

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

npm install tacotranslate

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

Most, hogy telepítetted a modult, itt az ideje létrehoznod a TacoTranslate fiókodat, egy fordítási projektet és a hozzá tartozó API kulcsokat. Hozz létre fiókot itt. Ingyenes, és nem szükséges hozzá bankkártya megadása.

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 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 rá, 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 helyi kód. Ebben a példában en-re állítjuk az angol nyelvhez.
• TACOTRANSLATE_ORIGIN: Az a „mappa”, ahol a szövegeid tárolva lesznek, például a webhelyed URL-címe. További információk az originrő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 el kell készítened egy klienst a korábban kapott API kulcsok felhasználásával. Például hozz létre 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;

Automatikusan definiálni fogjuk a TACOTRANSLATE_API_KEY és a TACOTRANSLATE_PROJECT_LOCALE értékeket hamarosan.

A kliens létrehozása külön fájlban megkönnyíti későbbi újrafelhasználását. A getLocales egy egyszerű segédfüggvény beépített hibakezeléssel. Most hozz létre egy fájlt /app/[locale]/tacotranslate.tsx, 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>
	);
}

Jegyezd meg a 'use client'; jelzést, amely azt mutatja, hogy ez egy kliens oldali 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 itt érdemes megjegyezni, hogy a Dynamic Route paraméterünket, a [locale]-t használjuk a fordítások lekérésére az adott nyelvre. Ezen felül a generateStaticParams gondoskodik arról, hogy az összes, a projektedhez aktivált locale kód előre legyen renderelve.

Most építsük meg az első oldalunkat! Hozz létre egy fájlt /app/[locale]/page.tsx- néven.

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 é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 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 nem lefordított tartalom villanását mutatná. Emellett kihagyhatjuk a hálózati kéréseket az ügyféloldalon, mert már megvannak a szükséges fordítások az adott oldalhoz, amelyet a felhasználó éppen néz.

A szerver oldali renderelés beállításához hozz létre vagy módosítsd a következőt: /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 saját beállításodhoz 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), a titkos read/write API kulcsot fogjuk használni, hogy biztosítsuk az új szövegek fordításra történő elküldését.

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 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);
}

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

A kliens oldalon megváltoztathatod a locale sütit, hogy módosítsd a felhasználó preferált nyelvét. Kérlek, nézd meg a teljes példa kó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. Fontos megjegyezni, hogy csak azok a környezetek, amelyek rendelkeznek a read/write jogosultságokkal az API kulcson, tudnak új, fordítandó szövegeket létrehozni. Javasoljuk, hogy legyen egy zárt és biztonságos staging környezeted, ahol egy ilyen API kulccsal tesztelheted éles alkalmazásodat, és hozzáadhatsz új szövegeket még a nyilvánosságra hozás előtt. Ez megakadályozza, hogy bárki ellopja a titkos API kulcsodat, és potenciálisan felfújja a fordítási projektet új, nem kapcsolódó szövegek hozzáadásával.

Ne felejtsd el megnézni a teljes példát a GitHub profilunkon. Ott találsz egy példát arra is, hogyan kell ezt megoldani 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 segítségével React alkalmazásaidat gyorsan és automatikusan lokalizálhatod tetszőleges nyelvre és nyelvről. Kezdd el még ma!