Hogyan valósítsuk meg a nemzetközivé tételt 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ókat is kiszolgálnak. Ennek egyik kulcsfontosságú módja az internacionalizáció (i18n), amely lehetővé teszi az alkalmazásod különböző nyelvekhez, valutákhoz és dátumformátumokhoz való igazítását.

Ebben a cikkben megvizsgáljuk, hogyan lehet internacionalizációt hozzáadni a React Next.js alkalmazásodhoz, a szerveroldali rendereléssel együtt. 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álja, nézze meg inkább ezt az útmutatót.

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

A Next.js alkalmazásod nemzetközivé tételéhez először egy i18n könyvtárat választunk. Több népszerű könyvtár is létezik, köztük a next-intl. Ebben a példában azonban a TacoTranslate használatára fogunk koncentrálni.

A TacoTranslate az élvonalbeli mesterséges intelligencia segítségével automatikusan lefordítja a sztringjeidet bármely nyelvre, és megszabadít a JSON fájlok fárasztó kezelésétől.

Telepítsük a npm használatával 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 hozzá bankkártyát megadnod.

A TacoTranslate alkalmazás felületén hozz létre egy projektet, majd navigálj az API kulcsok fülre. Készíts 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á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, vagyis angolra állítjuk.
• TACOTRANSLATE_ORIGIN: Az a „mappa”, ahol az adott szövegek tárolva lesznek, például a weboldalad URL-je. Olvass többet az origin-ökrő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 a TACOTRANSLATE_PROJECT_LOCALE értékeket.

A kliens létrehozása egy 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 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'; jelölé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ő, amit érdemes megjegyezni, hogy a Dynamic Route paraméterünket, a [locale] használjuk az adott nyelv fordításainak lekéréséhez. Ezen felül, a generateStaticParams biztosítja, hogy a projektedhez aktivált összes locale kód előre renderelve legyen.

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!" />
	);
}

Jegyezd meg a revalidate változót, amely megmondja a Next.js-nek, hogy 60 másodperc után újraépítse az oldalt, és naprakészen tartsa a fordításokat.

4. lépés: Szerveroldali 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 pillanatra megjelenne a le nem fordított tartalom. Ezenkívül elkerülhetjük a hálózati kéréseket a kliens oldalon, mert már rendelkezünk azokkal a fordításokkal, amelyekre a felhasználó által megtekintett oldalhoz szükség van.

A szerver oldali 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 publikus API kulcsot fogja használni. Ha egy helyi, teszt vagy staging környezetben vagyunk (isProduction is false), akkor a titkos read/write API kulcsot fogjuk használni, hogy az új szövegek biztosan el legyenek küldve fordításra.

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 /middleware.ts nevű fájlt. Middleware használatával át tudjuk irányítani 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 az matcher a Next.js Middleware dokumentációjának megfelelően legyen beállítva.

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 a read/write jogosultságokkal az API kulcson, tudnak új, lefordítandó szövegeket létrehozni. Javasoljuk, hogy legyen egy zárt és biztonságos staging környezeted, ahol tesztelheted a produkciós alkalmazásodat ilyen API kulccsal, és hozzáadhatsz új szövegeket a élesítés előtt. Ez megakadályozza, hogy bárki ellopja a titkos API kulcsodat, és potenciálisan felduzzaszthatná a fordítási projekted az új, nem kapcsolódó 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 kell ezt megtenni Pages Router-rel! Ha bármilyen problémába ütköznél, nyugodtan keress meg minket, és örömmel segítünk.

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