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

Ahogy a világ egyre inkább globalizálódik, a webfejlesztők számára egyre fontosabb, hogy olyan alkalmazásokat építsenek, amelyek képesek kiszolgálni különböző országokból és kultúrákból származó felhasználókat. Ennek egyik kulcsfontosságú módja a nemzetköziesítés (i18n), amely lehetővé teszi, hogy alkalmazásodat különböző nyelvekre, pénznemekre és dátumformátumokra igazítsd.

Ebben a bemutatóban megvizsgáljuk, hogyan adhatunk nemzetköziesítést a React Next.js alkalmazásunkhoz 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ával futnak.
Ha a App Router használatában van, kérjük, tekintse 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 válasszunk egy i18n könyvtárat. 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át mutatjuk be.

A TacoTranslate a legkorszerűbb 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 a 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ájuk tartozó API-kulcsokat. Regisztrálj itt. Ez ingyenes, és nem kell hitelkártyát megadnod.

A TacoTranslate alkalmazás felületén hozz létre egy projektet, és navigálj az API-kulcsok fülére. Hozz létre egy read kulcsot, és egy read/write kulcsot. Elmentjük őket környezeti változókként. A read kulcs az, amit publicnak nevezünk, a read/write kulcs pedig secret. Például hozzáadhatod őket egy .env fájlhoz a projekted gyökérkönyvtárába.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Ügyelj rá, hogy soha ne szivárogtasd ki a titkos read/write API-kulcsot a kliensoldali éles környezetekbe.

Emellett hozzáadunk még két környezeti változót: TACOTRANSLATE_DEFAULT_LOCALE és TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Az alapértelmezett tartalék (fallback) locale-kód. Ebben a példában az angolhoz a en értéket állítjuk be.
• TACOTRANSLATE_ORIGIN: Az „mappa”, ahol a szövegeid lesznek tárolva, például a weboldalad URL-je. További információk 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 integrálásához az alkalmazásodba létre kell hoznod egy klienst a korábban megadott 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-t.

A kliens külön fájlba helyezése megkönnyíti a későbbi újrahasználatát. Most, amikor egy egyedi /pages/_app.tsx fájlt használunk, 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 vannak egyéni pageProps és _app.tsx, kérjük, egészítsd ki a definíciót a fenti tulajdonságokkal és kóddal.

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

TacoTranslate lehetővé teszi a fordítások szerveroldali renderelését. Ez nagymértékben javítja a felhasználói élményt, mivel a lefordított tartalom azonnal megjelenik, ahelyett, hogy először egy rövid, nem lefordított tartalomfelvillanást látnánk. Ezenfelül kihagyhatjuk a kliensoldali hálózati kéréseket, mert már rendelkezünk minden szükséges fordítással.

Kezdjük azzal, hogy létrehozzuk vagy módosítjuk a /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 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 az új szövegek biztosan 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és az lesz, hogy lekérjük az összes oldal fordításait. Ehhez igényeid szerint vagy a getTacoTranslateStaticProps vagy a getTacoTranslateServerSideProps használatát kell választanod.

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. Megjegyzés: a revalidate a getTacoTranslateStaticProps esetén 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, tételezzü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, hogy lefordítsd a szövegeket minden React-komponensedben.

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-kulcsra vonatkozóan read/write jogosultságok vannak, képesek új, lefordítandó szövegeket létrehozni. Javasoljuk, hogy legyen egy zárt és biztonságos staging környezeted, ahol ilyen API-kulccsal tesztelheted az éles alkalmazásodat, és új szövegeket adhatsz hozzá még az éles üzembe helyezés előtt. Ez megakadályozza, hogy bárki ellopja a titkos API-kulcsodat, és hogy új, nem kapcsolódó szövegek hozzáadásával esetleg felduzzadjon a fordítási projekted.

Ne felejtsd el megnézni a teljes példát a GitHub-profilunkon. Ott szintén találsz egy példát arra, hogyan kell ezt megvalósítani a App Router használatával! Ha bármilyen problémába ütközöl, nyugodtan fordulj hozzánk, és örömmel segítünk.

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