A legjobb megoldás a Next.js alkalmazások nemzetköziesítéséhez (i18n)

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ülönböző országokból és kultúrákból érkező felhasználókat is kiszolgálnak. Ennek egyik kulcsfontosságú módja a nemzetköziesítés (i18n), amely lehetővé teszi, hogy alkalmazásodat különböző nyelvekhez, pénznemekhez és dátumformátumokhoz igazítsd.

Ebben az útmutatóban bemutatjuk, hogyan adhatod hozzá a nemzetköziesítést a React Next.js alkalmazásodhoz szerveroldali rendereléssel. TL;DR: Lásd a teljes példát itt.

Ez az útmutató azoknak a Next.js alkalmazásoknak szól, amelyek a Pages Router használatával készültek.
Ha a App Router használatával dolgozik, kérjük, tekintse meg ehelyett ezt az útmutatót.

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

Ahhoz, hogy a Next.js alkalmazásodban megvalósítsuk a nemzetközivé tételt (i18n), először válasszunk egy i18n könyvtárat. Számos népszerű könyvtár létezik, többek között next-intl. Azonban ebben a példában a TacoTranslate lesz a használt.

A TacoTranslate a legkorszerűbb mesterséges intelligencia 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 azt 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 kapcsolódó API-kulcsokat. Hozz létre fiókot itt. Ingyenes, és nem kell bankkártyát megadnod.

A TacoTranslate alkalmazás felhasználói felületén hozz létre egy projektet, majd nyisd meg az API-kulcsok fület. Hozz létre egy read kulcsot és egy read/write kulcsot. Ezeket környezeti változókként fogjuk elmenteni. A read kulcsot nevezzük public-nak, a read/write kulcs pedig 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

Ügyelj rá, hogy a titkos read/write API-kulcsot soha ne szivárogtasd ki a kliensoldali éles környezetbe.

Emellett két további környezeti változót is hozzáadunk: TACOTRANSLATE_DEFAULT_LOCALE és TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Az alapértelmezett tartalék (fallback) helyi beállítás kódja. Ebben a példában az angolhoz en-t állítjuk be.
• TACOTRANSLATE_ORIGIN: A „mappa”, ahol a sztringjeid lesznek tárolva, például a weboldalad URL-je. További információ az originökről itt.

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ásába létre kell hoznia egy klienst a korábban kapott API-kulcsok felhasználásával. Például hozzon létre egy fájlt /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;

Hamarosan automatikusan definiáljuk a TACOTRANSLATE_API_KEY.

A kliens létrehozása egy külön fájlban megkönnyíti a későbbi ismételt használatá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 saját 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, mivel a lefordított tartalmat azonnal megjeleníti, ahelyett, hogy először egy pillanatra nem lefordított tartalom villanna fel. Ezenfelül kihagyhatjuk a kliensoldali hálózati kéréseket, mert már rendelkezünk minden 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ítsa az isProduction ellenőrzést az Ön beállításainak megfelelően. 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 az új szövegek biztosan elküldésre kerüljenek 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ésként lekérjük az összes oldal fordítását. Ehhez az igényeidnek megfelelően vagy a getTacoTranslateStaticProps vagy a getTacoTranslateServerSideProps függvényt 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. Jegyezd meg, hogy a revalidate a getTacoTranslateStaticProps esetén alapértelmezés szerint 60-ra van állítva, így a fordítások naprakészek maradnak.

Bármelyik függvény használatához egy oldalon tegyük fel, hogy van egy ilyen oldalfá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 használhatja a Translate komponenst az összes React-komponensében 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ész vagyunk! A Next.js alkalmazásod mostantól automatikusan le lesz fordítva, amikor bármilyen szöveget hozzáadsz egy Translate komponenshez. Felhívjuk a figyelmet, hogy csak azok a környezetek lesznek képesek új, lefordítandó sztringeket 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 ilyen API-kulccsal tesztelheted az éles alkalmazást, és új sztringeket adhatsz hozzá az élesítés előtt. 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ó sztringek 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!