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

Ahogy a világ egyre inkább globalizálódik, egyre fontosabb lesz a webfejlesztők számára olyan alkalmazásokat létrehozni, amelyek különböző országokból és kultúrákból származó felhasználók igényeit szolgálják ki. Ennek egyik kulcsfontosságú módja az internacionalizáció (i18n), amely lehetővé teszi az alkalmazásod alkalmazkodását különböző nyelvekhez, valutákhoz és dátumformátumokhoz.

Ebben a bemutatóban megvizsgáljuk, hogyan adhatsz internacionalizációt a React Next.js alkalmazásodhoz szerveroldali rendereléssel. TL;DR: Nézd meg a teljes példát itt.

Ez az útmutató olyan Next.js alkalmazások számára készült, amelyek a Pages Router használatával működnek.
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

A Next.js alkalmazásod internacionalizálásához (i18n) először válasszunk egy i18n könyvtárat. Számos népszerű könyvtár létezik, köztük next-intl. Azonban ebben a példában a TacoTranslate-t fogjuk használni.

A TacoTranslate a legmodernebb 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álban npm használatával:

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. Ez ingyenes, és nem kell bankkártyát megadnod.

A TacoTranslate alkalmazás felhasználói felületén hozz létre egy projektet, és navigálj annak API-kulcsok lapjára. Hozz létre egy read kulcsot, és egy read/write kulcsot. Elmentjük őket környezeti változóként. A read kulcs az úgynevezett public, a read/write kulcs pedig az úgynevezett secret. Például hozzáadhatod őket egy .env fájlhoz a projekt gyökérkönyvtárában.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Győződj meg róla, hogy soha ne szivárogtasd ki a titkos read/write API-kulcsot a 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 tartalék (fallback) locale-kód. Ebben a példában angolhoz en-re állítjuk.
• TACOTRANSLATE_ORIGIN: Az a “mappa”, ahol a karakterláncaid lesznek tárolva, például a weboldalad URL-je. További információ az originokról.

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 klienst a korábban megadott API-kulcsok felhasználásával. Például hozz létre egy /tacotranslate-client.js nevű fájlt.

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;

Rövidesen automatikusan definiálni fogjuk a TACOTRANSLATE_API_KEY értékét.

A kliens létrehozása külön fájlban 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 vannak egyéni pageProps és _app.tsx, kérjük, bővítse 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 azáltal, hogy a fordított tartalmat azonnal megjeleníti, ahelyett, hogy először egy nem lefordított tartalom villanását látnánk. Ezenfelül elkerülhetjük 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 /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 a saját beállításaidhoz igazítva. Ha true, a TacoTranslate a publikus API kulcsot fogja használni. Ha 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 lefordí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ását. Ehhez a követelményektől függően vagy a getTacoTranslateStaticProps vagy a getTacoTranslateServerSideProps egyikét fogod használni.

Ezek a függvények három argumentumot vesznek: 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ében alapértelmezés szerint 60-ra van beállítva, így a fordításaid naprakészek maradnak.

Bármelyik függvény használatához egy oldalon tegyük fel, hogy van egy ilyen fájlod: /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 képesnek kell lenned használni a Translate komponenst az összes React-komponensedben található szövegek lefordításához.

import {Translate} from 'tacotranslate/react';

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

5. lépés: Telepítés és tesztelés!

Készen 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-kulcson read/write jogosultság szerepel, lesznek képesek új, lefordítandó szövegeket létrehozni. Azt javasoljuk, hogy legyen egy zárt, biztonságos staging környezeted, ahol egy ilyen API-kulccsal tesztelheted az éles alkalmazást, és új szövegeket adhatsz hozzá, mielőtt élesbe mész. Ez megakadályozza, hogy bárki 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: a teljes példát itt találod. Ott találsz egy példát arra is, hogyan kell ezt megvalósítani az App Router használatával! Ha bármilyen problémába ütközöl, bátran keress minket, és örömmel segítünk.

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