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

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-t használják.
Ha a App Router-t használja, 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ás nemzetközivé tétele érdekében először kiválasztunk egy i18n könyvtárat. Több népszerű könyvtár létezik, például next-intl. Azonban ebben a példában a TacoTranslate használatát mutatjuk be.

A TacoTranslate csúcstechnológiás mesterséges intelligencia segítségével automatikusan lefordítja a szövegeidet bármely nyelvre, és megszabadít a JSON fájlok körülményes kezelésétől.

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

npm install tacotranslate

2. lépés: Hozz 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 hitelkártyát megadnod.

A TacoTranslate alkalmazás felhasználói 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óként. A read kulcs a mi esetünkben a public, a read/write kulcs pedig a secret. Például hozzáadhatod őket egy .env fájlhoz a projekt gyökerében.

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ódja. Ebben a példában en-re állítjuk az angolhoz.
• TACOTRANSLATE_ORIGIN: A „mappa”, ahol a sztringjeid lesznek tárolva, 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: A TacoTranslate beállítása

A TacoTranslate alkalmazásba integrálásához létre kell hoznod egy klienst a korábban megadott API-kulcsok használatával. Például hozz létre egy fájlt, amelynek a neve /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;

A TACOTRANSLATE_API_KEY értékét hamarosan automatikusan meghatározzuk.

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

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 rendelkezik egyéni pageProps és _app.tsx, kérjük, egészítse ki a definíciót a fenti 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 nagymértékben javítja a felhasználói élményt azáltal, hogy a lefordított tartalmat azonnal megjeleníti, ahelyett, hogy először egy lefordítatlan tartalom villaná fel. Ezen felü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, 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és az lesz, hogy lekérjük az összes oldaladhoz tartozó fordításokat. Ehhez a követelményeknek megfelelően vagy getTacoTranslateStaticProps vagy getTacoTranslateServerSideProps 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. Megjegyzés: a revalidate a getTacoTranslateStaticProps esetén alapértelmezés szerint 60-ra van állítva, így a fordításaid naprakészek maradnak.

Ha bármelyik függvényt egy oldalon szeretnéd használni, tegyük fel, hogy van egy oldalfájlod, például /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 arra, hogy használd 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. Vedd figyelembe, hogy csak azok a környezetek tudnak új, lefordítandó szövegeket létrehozni, amelyeknél az API-kulcsnak read/write jogosultsága van. Ajánljuk, hogy legyen egy zárt és biztonságos staging környezeted, ahol az éles alkalmazásodat egy ilyen API-kulccsal tesztelheted, és hozzáadhatod az új szövegeket, mielőtt élesítenéd. Ez megakadályozza, hogy valaki ellopja a titkos API-kulcsodat, és hogy a fordítási projekted feleslegesen megnövekedjen új, nem kapcsolódó szövegek hozzáadásával.

Mindenképp nézd meg a teljes példát a GitHub-profilunkon. Ott találsz egy példát arra is, hogyan kell ezt megtenni az App Router használatával! Ha problémába ütköznél, nyugodtan keress minket, é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!