A legjobb megoldás a nemzetköziesítéshez (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 készítsenek, amelyek képesek kiszolgálni különböző országokból és kultúrákból érkező felhasználókat. Ennek egyik kulcsfontosságú módja az internationalization (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 azt vizsgáljuk meg, hogyan adhatsz nemzetköziesítést a React Next.js alkalmazásodhoz, szerver oldali rendereléssel. TL;DR: Itt találod a teljes példát.

Ez az útmutató a Next.js alkalmazások számára készült, amelyek a Pages Router rendszert használják.
Ha a App Router-t használja, kérjük, nézze meg helyette ezt az útmutatót.

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

A Next.js alkalmazásod nemzetközivé tételéhez először választanunk kell 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 fogjuk bemutatni.

A TacoTranslate a legmodernebb mesterséges intelligencia segítségével automatikusan lefordítja a sztringjeidet bármilyen nyelvre, ezzel megszabadítva téged a JSON fájlok fáradságos kezelésétől.

Telepítsük a terminálodban 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étrehoznod a TacoTranslate fiókodat, egy fordítási projektet, és a hozzá tartozó API kulcsokat. Hozz létre fiókot itt. Ez ingyenes, és nem kell hozzá hitelkártyát megadnod.

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 menteni. A read kulcs az, amit public kulcsnak hívunk, míg a read/write kulcs a secret kulcs. Például ezeket hozzáadhatod egy .env fájlhoz a projekt gyökérkönyvtárában.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Mindig ügyelj arra, hogy a titkos read/write API kulcsot soha ne szivárogtasd ki a kliens oldali éles környezetbe.

Hozzá fogunk adni 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, azaz angolra.
• TACOTRANSLATE_ORIGIN: Az a „mappa”, ahol a sztringjeid tárolva lesznek, például a weboldalad URL-je. További információt az origin-ekről itt olvashatsz.

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 az előzőleg beszerzett API kulcsok felhasználásá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;

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, 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 szerveroldali renderelés megvalósítása

A TacoTranslate lehetővé teszi a fordítások szerver oldali renderelését. Ez nagyban javítja a felhasználói élményt azáltal, hogy a lefordított tartalmat azonnal megjeleníti, ahelyett, hogy először nem lefordított tartalom villanna fel. Ezen felül kihagyhatjuk a hálózati kéréseket a kliens oldalon, mert már rendelkezünk minden szükséges fordítással.

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 saját beállításodnak megfelelően. Ha true, a TacoTranslate a nyilvános API kulcsot használja. Ha helyi, teszt vagy staging környezetben vagyunk (isProduction is false), a titkos read/write API kulcsot használjuk, hogy az új stringek biztosan le legyenek fordítva.

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 használhatod az igényeid alapján: getTacoTranslateStaticProps vagy getTacoTranslateServerSideProps.

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

Ha bármelyik függvényt egy oldalon szeretné használni, tegyük fel, hogy van egy oldal fájlja, 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 a Translate komponenst használja 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é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 a read/write jogosultságokkal az API kulccsal, tudnak új, lefordítandó szövegeket létrehozni. Ajánljuk, 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á élesítés előtt. Ez megakadályozza, hogy bárki ellopja a titkos API kulcsodat, és esetlegesen felfújja a fordítási projektedet új, nem kapcsolódó szövegek hozzáadásával.

Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the App Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.

TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!