A legjobb megoldás a nemzetközivé tételhez (i18n) Next.js alkalmazásokban

Hogyan működik

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épesek kiszolgálni a különböző országokból és kultúrákból érkező felhasználókat. Ennek egyik kulcsfontosságú módszere a lokalizáció (i18n), amely lehetővé teszi az alkalmazásod adaptálását különböző nyelvekhez, pénznemekhez és dátumformátumokhoz.

Ebben az útmutatóban megvizsgáljuk, hogyan adhatsz hozzá lokalizációt a React Next.js alkalmazásodhoz, szerver oldali rendereléssel. TL;DR: Teljes példát itt találsz.

Ez az útmutató a Pages Router-t használó Next.js alkalmazásokhoz készült.
Ha a App Router-t használja, kérjük, tekintse meg helyette ezt az útmutatót.

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

A nemzetköziesítés (i18n) megvalósításához Next.js alkalmazásodban először választunk egy i18n könyvtárat. Több népszerű könyvtár is létezik, többek között a next-intl. Azonban ebben a példában a TacoTranslate használatát vesszük alapul.

A TacoTranslate a legkorszerűbb mesterséges intelligencia segítségével automatikusan lefordítja a szövegeidet bármely nyelvre, emellett megszabadít a JSON fájlok unalmas 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. Hozz létre itt egy fiókot. Ez ingyenes, és nem szükséges bankkártya megadása.

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. Ezután menteni fogjuk őket környezeti változóként. 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 projekt gyökerében.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Győződj meg róla, hogy a titkos read/write API kulcsot soha ne szivárogtasd ki 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 visszaesési nyelvkód. Ebben a példában en-re, azaz angolra állítjuk.
• TACOTRANSLATE_ORIGIN: Az a „mappa”, ahol a szövegeid tárolva lesznek, például a weboldalad URL-je. További információ az eredetekről itt.

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

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

A TacoTranslate alkalmazással való integrálásához létre kell hoznia egy ügyfelet a korábbi API-kulcsok használatával. Hozzon létre például egy /tacotranslate-client.jsnevű 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.

Az ügyfél létrehozása külön fájlban megkönnyíti a későbbi újrafelhasználást. Most pedig egy egyedi /pages/_app.tsx használatával hozzáadjuk a TacoTranslate szolgáltató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 van saját egyedi pageProps és _app.tsx, kérjük, bővítse ki a definíciót a fent megadott tulajdonságokkal és kóddal.

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

A TacoTranslate lehetővé teszi a fordítások szerver oldali megjelenítését. Ez nagymértékben javítja a felhasználói élményt azáltal, hogy azonnal megjeleníti a lefordított tartalmat, ahelyett, hogy először egy nem lefordított tartalom pillanatra felvillanna. Emellett elkerülhetjük a hálózati kéréseket az ügyféloldalon, mivel már rendelkezünk az összes szükséges fordítással.

Az /next.config.js létrehozásával vagy módosításával kezdjük.

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ásodnak megfelelően. Ha true, a TacoTranslate a nyilvános API kulcsot fogja megjeleníteni. Ha helyi, teszt vagy staging környezetben vagyunk (isProduction is false), titkos read/write API kulcsot használunk, hogy biztosítsuk az új szövegek lefordításra való elküldését.

Eddig csak a Next.js alkalmazást állítottuk be a támogatott nyelvek listájával. A következő lépés, hogy lekérjük az összes oldal fordításait. Ehhez a következők egyikét fogod használni: getTacoTranslateStaticProps vagy getTacoTranslateServerSideProps, az igényeid szerint.

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

Ahhoz, hogy bármelyik függvényt használja egy oldalon, tegyük fel, hogy van egy oldal fájlja, például a /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!"/>;
}

Most már képesnek kell lenned arra, hogy használd a Translate komponenst a karakterláncok fordítására az összes React komponenseden belül.

import {Translate} from 'tacotranslate/react';

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

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

Kész is vagyunk! A Next.js alkalmazásod mostantól automatikusan le lesz fordítva, amikor bármilyen szöveget hozzáadsz egy Translate komponenshez. Fontos megjegyezni, hogy csak azok a környezetek, amelyek rendelkeznek read/write jogosultsággal az API kulcson, tudnak új fordítandó szövegeket létrehozni. Javasoljuk, hogy legyen egy zárt és biztonságos staging környezeted, ahol tesztelheted az éles alkalmazásodat egy ilyen API kulccsal, és új szövegeket adhatsz hozzá, mielőtt élőbe lépnél. Ez megakadályozza, hogy bárki ellopja a titkos API kulcsodat, és esetlegesen feleslegesen növelje a fordítási projekted méretét ú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 is arra, hogyan lehet ezt megvalósítani App Router használatával! Ha bármilyen problémába ütköznél, bátran keress minket, szívesen segítünk.

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