A legjobb megoldás az internacionalizációhoz (i18n) Next.js alkalmazásokban

Hogyan működik

Ahogy a világ egyre globalizáltabbá válik, egyre fontosabbá válik a webfejlesztők számára, hogy olyan alkalmazásokat készítsenek, amelyek különböző országokból és kultúrákból származó felhasználókat is kiszolgálnak. Ennek egyik kulcsfontosságú módja az internacionalizáció (i18n), amely lehetővé teszi, hogy alkalmazásodat különböző nyelvekhez, valutákhoz és dátumformátumokhoz igazítsd.

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

Ez az útmutató a Pages Router 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

Az internacionalizáció (i18n) megvalósításához a Next.js alkalmazásodban először ki kell választanunk egy i18n könyvtárat. Számos népszerű könyvtár létezik, többek között a next-intl. Azonban ebben a példában a TacoTranslate használatát fogjuk bemutatni.

A TacoTranslate a legkorszerűbb AI segítségével automatikusan lefordítja a sztringjeidet bármely nyelvre, és megszabadít a JSON fájlok fárasztó kezelésétől.

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

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. Hozz létre egy fiókot itt. Ingyenes, és nem kell hitelkártyát megadnod hozzá.

A TacoTranslate alkalmazás felületén hozz létre egy projektet, majd navigálj az API kulcsok fülre. Hozz létre egy read kulcsot és egy read/write kulcsot. Ezeket környezeti változóként fogjuk elmenteni. A read kulcsot hívjuk public kulcsnak, míg a read/write kulcs a secret. Például hozzáadhatod őket egy .env fájlhoz a projekted gyökérkönyvtárában.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Ügyelj arra, hogy a titkos read/write API-kulcs soha ne szivárogjon ki a 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 helyi beállítás kódja. Ebben a példában en-re állítjuk, ami az angol nyelvet jelenti.
• TACOTRANSLATE_ORIGIN: Az a „mappa”, ahol a szövegeid tárolva lesznek, például a weboldalad URL-címe. Erről az eredetekről itt olvashatsz bővebben.

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 megszerzett API kulcsok segítségével. 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;

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

A kliens létrehozása egy külön fájlban megkönnyíti későbbi újrafelhasználását. Most, 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 egyedi pageProps és _app.tsx, kérjük, bővítse a definíciót a fent említett tulajdonságokkal és kóddal.

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

A TacoTranslate lehetővé teszi a fordítások szerver oldali renderelését. Ez jelentősen javítja a felhasználói élményt azáltal, hogy azonnal megjeleníti a lefordított tartalmat ahelyett, hogy először egy lefordítatlan tartalom villanjon fel. Ezen felül elkerülhetjük a hálózati kéréseket az ügyfél oldalán, mert már rendelkezésünkre áll az összes szükséges fordítás.

Azzal kezdjük, hogy létrehozzuk vagy módosítjuk a /next.config.js fájlt.

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 beállításaidnak megfelelően. Ha true, a TacoTranslate a nyilvános API kulcsot fogja használni. Ha helyi, teszt vagy staging környezetben vagyunk (isProduction is false), akkor a titkos read/write API kulcsot használjuk, hogy az új szövegek biztosan el legyenek küldve fordításra.

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 a fordításokat az összes oldaladhoz. Ehhez a igényeid szerint az getTacoTranslateStaticProps vagy az getTacoTranslateServerSideProps függvényt 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, valamint opcionális Next.js tulajdonságokat. Vegyük észre, hogy a revalidate alapértelmezett értéke a getTacoTranslateStaticProps esetén 60, hogy a fordítások naprakészek maradjanak.

Ha bármelyik függvényt egy oldalon használni szeretnéd, tegyük fel, hogy van egy oldal fá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!"/>;
}

Most már képesnek kell lennie arra, hogy használja a Translate komponenst a szövegek fordítására az összes React komponensében.

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 Next.js alkalmazásod mostantól automatikusan lefordításra kerül, amikor bármilyen szöveget hozzáadsz egy Translate komponenshez. Fontos megjegyezni, hogy csak azok a környezetek, amelyek rendelkeznek read/write jogosultságokkal az API kulcson, képesek új fordítandó szövegeket létrehozni. Javasoljuk, hogy legyen egy zárt és biztonságos staging környezeted, ahol az API kulccsal tesztelheted a termelési alkalmazásodat, és új szövegeket adhatsz hozzá, mielőtt élesbe lépnél. Ez megakadályozza, hogy bárki ellopja a titkos API kulcsodat, és esetlegesen felfújja a fordítási projektedet új, nem releváns 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 is arra, hogyan lehet ezt megvalósítani a App Router használatával! Ha bármilyen problémába ütközöl, bátran lépj velünk kapcsolatba, és örömmel segítünk.

A TacoTranslate lehetővé teszi, hogy React alkalmazásaidat gyorsan és automatikusan lokalizáld bármely nyelvre és onnan. Kezdd el még ma!