Kako implementirati internacionalizacijo v Next.js aplikaciji, ki uporablja App Router

Ker se svet vse bolj globalizira, je za spletne razvijalce vse pomembneje graditi aplikacije, ki ustrezajo uporabnikom iz različnih držav in kultur. Eden ključnih načinov za to je internacionalizacija (i18n), ki vam omogoča prilagoditi aplikacijo različnim jezikom, valutam in formatom datumov.

V tem članku bomo raziskali, kako dodati internacionalizacijo v vašo React Next.js aplikacijo z upodabljanjem na strežniku. TL;DR: Oglejte si celoten primer tukaj.

Ta vodnik je namenjen Next.js aplikacijam, ki uporabljajo App Router.
Če uporabljate Pages Router, si oglejte ta vodnik namesto tega.

Korak 1: Namestite i18n knjižnico

Da bi v vaši Next.js aplikaciji uvedli internacionalizacijo, bomo najprej izbrali i18n knjižnico. Obstaja več priljubljenih knjižnic, vključno z next-intl. V tem primeru pa bomo uporabili TacoTranslate.

TacoTranslate samodejno prevede vaše nize v katerikoli jezik z uporabo najsodobnejše umetne inteligence in vas osvobodi zamudnega upravljanja datotek JSON.

Namestimo ga z uporabo npm v vašem terminalu:

npm install tacotranslate

Korak 2: Ustvarite brezplačen račun za TacoTranslate

Zdaj, ko imate modul nameščen, je čas, da ustvarite svoj TacoTranslate račun, prevajalski projekt in pripadajoče API ključe. Ustvarite račun tukaj. Brezplačno je in ne zahteva vnosa kreditne kartice.

V uporabniškem vmesniku aplikacije TacoTranslate ustvarite projekt in odprite zavihek API ključev. Ustvarite en read ključ in en read/write ključ. Shranili jih bomo kot okoljske spremenljivke. read ključ je tisti, ki mu pravimo public, read/write ključ pa je secret. Na primer, lahko jih dodate v datoteko .env v korenu vašega projekta.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Nikoli ne razkrijte skrivnega read/write API ključa v produkcijskih odjemalskih okoljih.

Dodali bomo še dve okoljski spremenljivki: TACOTRANSLATE_DEFAULT_LOCALE in TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Privzeta koda jezika, ki se uporabi kot rezervna. V tem primeru jo bomo nastavili na en za angleščino.
• TACOTRANSLATE_ORIGIN: “mapa”, kjer bodo shranjeni vaši nizi, na primer URL vaše spletne strani. Preberite več o originah tukaj.

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

Korak 3: Nastavitev TacoTranslate

Za integracijo TacoTranslate v vašo aplikacijo boste morali ustvariti odjemalca z uporabo prej navedenih API ključev. Na primer, ustvarite datoteko z imenom /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_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

Kmalu bomo samodejno določili TACOTRANSLATE_API_KEY in TACOTRANSLATE_PROJECT_LOCALE.

Ustvarjanje odjemalca v ločeni datoteki omogoča njegovo enostavno ponovno uporabo. getLocales je le pomožna funkcija z vgrajenim ravnanjem z napakami. Zdaj ustvarite datoteko z imenom /app/[locale]/tacotranslate.tsx, kjer bomo implementirali ponudnika TacoTranslate.

'use client';

import React, {type ReactNode} from 'react';
import {
	type TranslationContextProperties,
	TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';

export default function TacoTranslate({
	locale,
	origin,
	localizations,
	children,
}: TranslationContextProperties & {
	readonly children: ReactNode;
}) {
	return (
		<ImportedTacoTranslate
			client={tacoTranslateClient}
			locale={locale}
			origin={origin}
			localizations={localizations}
		>
			{children}
		</ImportedTacoTranslate>
	);
}

Upoštevajte 'use client';, kar označuje, da gre za komponento na odjemalcu.

Zdaj, ko je kontekstni provider pripravljen za uporabo, ustvarite datoteko z imenom /app/[locale]/layout.tsx, korenski layout v naši aplikaciji. Upoštevajte, da ta pot vsebuje mapo, ki uporablja Dynamic Routes, kjer je [locale] dinamični parameter.

import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';

export async function generateStaticParams() {
	const locales = await tacoTranslateClient.getLocales();
	return locales.map((locale) => ({locale}));
}

type RootLayoutParameters = {
	readonly params: Promise<{locale: Locale}>;
	readonly children: ReactNode;
};

export default async function RootLayout({params, children}: RootLayoutParameters) {
	const {locale} = await params;
	const origin = process.env.TACOTRANSLATE_ORIGIN;
	const localizations = await tacoTranslateClient.getLocalizations({
		locale,
		origins: [origin /* , other origins to fetch */],
	});

	return (
		<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
			<body>
				<TacoTranslate
					locale={locale}
					origin={origin}
					localizations={localizations}
				>
					{children}
				</TacoTranslate>
			</body>
		</html>
	);
}

Prva stvar, ki jo je treba poudariti, je, da uporabljamo naš parameter Dynamic Route [locale] za pridobivanje prevodov za ta jezik. Poleg tega generateStaticParams zagotavlja, da so vnaprej renderirane vse kode jezikov, ki ste jih aktivirali za svoj projekt.

Zdaj pa zgradimo našo prvo stran! Ustvarite datoteko z imenom /app/[locale]/page.tsx.

import React from 'react';
import {Translate} from 'tacotranslate/react';

export const revalidate = 60;
export default async function Page() {
	return (
		<Translate string="Hello, world!" />
	);
}

Upoštevajte spremenljivko revalidate, ki Next.jsu pove, naj stran ponovno zgradi po 60 sekundah in ohranja vaše prevode posodobljene.

Korak 4: Implementacija renderiranja na strežniški strani

TacoTranslate podpira renderiranje na strežniku. To občutno izboljša uporabniško izkušnjo, saj takoj prikaže prevedeno vsebino, namesto da bi se najprej prikazala neprevedena vsebina. Poleg tega se lahko izognemo omrežnim zahtevam na odjemalcu, saj že imamo prevode, potrebne za stran, ki si jo uporabnik ogleduje.

Za nastavitev upodabljanja na strežniški strani ustvarite ali spremenite /next.config.js:

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = await withTacoTranslate(
		{},
		{
			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'),
		}
	);

	// NOTE: Remove i18n from config when using the app router
	return {...config, i18n: undefined};
};

Prilagodite preverjanje isProduction glede na vašo nastavitev. Če je true, bo TacoTranslate prikazal javni API ključ. Če smo v lokalnem, testnem ali predprodukcijskem okolju (isProduction is false), bomo uporabili skrivni API ključ read/write, da zagotovimo, da so novi nizi poslani v prevod.

Da usmerjanje in preusmerjanje delujeta kot pričakovano, bomo morali ustvariti datoteko z imenom /middleware.ts. Z uporabo Middleware, lahko uporabnike preusmerimo na strani v njihovem želenem jeziku.

import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';

export const config = {
	matcher: ['/((?!api|_next|favicon.ico).*)'],
};

export async function middleware(request: NextRequest) {
	return tacoTranslateMiddleware(tacoTranslate, request);
}

Poskrbite, da boste matcher nastavili v skladu z dokumentacijo Next.js Middleware.

Na odjemalcu lahko spremenite piškotek locale, s čimer nastavite uporabnikov prednostni jezik. Za ideje, kako to narediti, si oglejte celoten primer kode!

Korak 5: Namestite in preizkusite!

Končali smo! Vaša React aplikacija bo zdaj samodejno prevedena, ko dodate katerikoli niz v komponento Translate. Upoštevajte, da bodo nove nize za prevod lahko ustvarila le okolja, ki imajo pri API ključu dovoljenja read/write. Priporočamo, da imate zaprto in zavarovano testno (staging) okolje, kjer lahko s takim API ključem preizkusite svojo produkcijsko aplikacijo in dodajate nove nize, preden greste v živo. To bo preprečilo, da bi kdo ukradel vaš skrivni API ključ in s tem morebiti napihnil vaš prevajalski projekt z dodajanjem novih, nepovezanih nizov.

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 Pages 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!