Hogyan valósítsuk meg az internacionalizációt egy Next.js alkalmazásban, amely a Pages Router-t használ?

Ahogy a világ egyre inkább globalizálódik, egyre fontosabbá válik, 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ókat is képesek kiszolgálni. Ennek egyik kulcsfontosságú módja az internacionalizáció (i18n), amely lehetővé teszi az alkalmazásod igazítását különböző nyelvekhez, pénznemekhez és dátumformátumokhoz.

Ebben az útmutatóban megvizsgáljuk, hogyan adhatod hozzá az internacionalizációt a React Next.js alkalmazásodhoz szerveroldali rendereléssel. TL;DR: A teljes példát itt találod.

Ez az útmutató azoknak a Next.js alkalmazásoknak szól, amelyek a Pages Router használatában vannak.
Ha a App Router használatában van, kérjük, tekintse 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 a next-intl. Ebben a példában azonban a TacoTranslate használatára fogunk támaszkodni.

TacoTranslate a legmodernebb MI-t használva automatikusan lefordítja a szövegeidet bármely nyelvre, és megszabadít a JSON-fájlok fáradságos kezelésétől.

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

npm install tacotranslate

2. lépés: Hozzon 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 a hozzá tartozó API-kulcsokat. Regisztrálj itt. Ingyenes, és nem kell hozzá bankkártyát megadnod.

A TacoTranslate alkalmazás felületén hozz létre egy projektet, és 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 kulcs a public, a read/write kulcs pedig a secret. Például hozzáadhatod őket a projekt gyökerében lévő .env fájlhoz.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Ügyelj rá, hogy soha ne szivárogtasd ki a titkos read/write API-kulcsot kliensoldali é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 visszaesési (fallback) locale-kód. Ebben a példában az angolhoz en-t állítjuk be.
• TACOTRANSLATE_ORIGIN: A „mappa”, ahová a strings-eket tárolni fogod, például a webhelyed URL-je. További információ az originokról itt.

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

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

A TacoTranslate alkalmazásodba történő integrálásához létre kell hoznod egy klienst a korábban megszerzett 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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Hamarosan automatikusan beállítjuk a TACOTRANSLATE_API_KEY értékét.

A kliens külön fájlban történő létrehozása megkönnyíti a későbbi újrafelhasználást. Most, egy egyedi /pages/_app.tsx használatával hozzáadjuk a TacoTranslate providert.

import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

type PageProperties = {
	origin: Origin;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, locales, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

Ha már van egyéni pageProps és _app.tsx, kérjük, egészítse ki a definíciót a fent említett tulajdonságokkal és kóddal.

4. lépés: Szerveroldali renderelés megvalósítása

A TacoTranslate lehetővé teszi a fordítások szerveroldali renderelését. Ez jelentősen javítja a felhasználói élményt, mivel a fordított tartalom azonnal megjelenik, ahelyett, hogy először egy nem lefordított tartalom villanjon fel. Emellett kihagyhatjuk a kliensoldali hálózati kéréseket, mert már rendelkezünk az összes szükséges fordítással.

Kezdjük azzal, hogy létrehozzuk vagy módosítjuk a következő fájlt: /next.config.js.

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		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'),
	});
};

Módosítsd az isProduction ellenőrzést, hogy megfeleljen a beállításaidnak. Ha true, a TacoTranslate megjeleníti a nyilvános API-kulcsot. Ha helyi, teszt vagy staging környezetben vagyunk (isProduction is false), a titkos read/write API-kulcsot fogjuk használni, hogy biztosítsuk, hogy az új szövegek fordításra kerüljenek.

Eddig csak a Next.js alkalmazást állítottuk be a támogatott nyelvek listájával. A következő lépésben lekérjük az összes oldalad fordítását. Ehhez az igényeidnek megfelelően a getTacoTranslateStaticProps vagy a getTacoTranslateServerSideProps valamelyikét fogod használni.

Ezek a függvények három argumentumot várnak: egy Next.js Static Props Context objektumot, a TacoTranslate konfigurációját és opcionális Next.js tulajdonságokat. Figyeld, hogy a revalidate a getTacoTranslateStaticProps esetében alapértelmezés szerint 60-ra van állítva, így a fordítások naprakészek maradnak.

Ha bármelyik függvényt egy oldalon szeretnéd használni, tegyük fel, hogy van egy olyan oldalfájlod, mint /pages/hello-world.tsx.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

export default function Page() {
	return <Translate string="Hello, world!"/>;
}

Mostantól használhatod a Translate komponenst az összes React-komponensedben található szövegek fordítására.

import {Translate} from 'tacotranslate/react';

function Component() {
	return <Translate string="Hello, world!"/>
}

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, amelyeknél az API-kulcs read/write jogosultsággal rendelkezik, lesznek képesek új, lefordítandó szövegeket létrehozni. Azt javasoljuk, hogy legyen egy zárt és védett staging környezeted, ahol ilyen API-kulccsal tesztelheted az éles alkalmazásodat, és új szövegeket adhatsz hozzá még az élesítés előtt. Ez megakadályozza, hogy bárki ellopja a titkos API-kulcsodat, és potenciálisan felduzzassza a fordítási projektedet ú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 megtenni App Router használatával! Ha bármilyen problémába ütköznél, nyugodtan keress minket, és szívesen segítünk.

A TacoTranslate lehetővé teszi, hogy React-alkalmazásaidat automatikusan, gyorsan lokalizáld több mint 75 nyelvre és onnan vissza. Kezdd el még ma!