Kako uvesti internacionalizacijo v Next.js aplikacijo, ki uporablja App Router

Ker je svet vse bolj globaliziran, je za spletne razvijalce vse pomembneje ustvarjati 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 s strežniškim upodabljanjem. TL;DR: Oglejte si celoten primer tukaj.

Ta vodič je za Next.js aplikacije, ki uporabljajo App Router.
Če uporabljate Pages Router, si namesto tega oglejte ta vodič.

Korak 1: Namestite knjižnico i18n

Za implementacijo internacionalizacije v vaši Next.js aplikaciji 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 dolgočasnega upravljanja z JSON datotekami.

Namestimo ga z uporabo npm v vašem terminalu:

npm install tacotranslate

Korak 2: Ustvarite brezplačen račun TacoTranslate

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. Je brezplačno in ne zahteva vnosa kreditne kartice.

V uporabniškem vmesniku aplikacije TacoTranslate ustvarite projekt in pojdite na zavihek API ključev. Ustvarite en read ključ in en read/write ključ. Shranjeni bodo kot okoljske spremenljivke. Ključ read imenujemo public, ključ read/write 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

Poskrbite, da skrivni read/write API ključ nikoli ne bo razkrit v produkcijskih okoljih na strani odjemalca.

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 izvorih tukaj.

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

Korak 3: Nastavitev TacoTranslate

Če želite integrirati TacoTranslate v svojo aplikacijo, boste morali ustvariti odjemalca, ki uporablja prej pridobljene API ključe. 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 definirali TACOTRANSLATE_API_KEY in TACOTRANSLATE_PROJECT_LOCALE.

Ustvarjanje odjemalca v ločeni datoteki olajša njegovo ponovno uporabo kasneje. getLocales je le pomožna funkcija z nekaj vgrajenimi mehanizmi za obravnavo napak. Zdaj ustvarite datoteko z imenom /app/[locale]/tacotranslate.tsx, v kateri 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>
	);
}

Opazite 'use client';, kar označuje, da gre za odjemalsko komponento.

Zdaj, ko je kontekstni provider pripravljen za uporabo, ustvarite datoteko z imenom /app/[locale]/layout.tsx, korenska postavitev 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 tukaj omeniti, je, da uporabljamo naš parameter Dynamic Route [locale] za pridobivanje prevodov za ta jezik. Poleg tega generateStaticParams poskrbi, da so vnaprej upodobljene vse jezikovne kode, ki ste jih aktivirali za svoj projekt.

Zdaj pa ustvarimo 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 pove Next.js, naj stran po 60 sekundah ponovno zgradi in tako ohranja vaše prevode ažurne.

Korak 4: Implementacija upodabljanja na strežniku

TacoTranslate podpira renderiranje na strežniku. To močno izboljša uporabniško izkušnjo, saj se prevedena vsebina prikaže takoj, namesto da bi se najprej pojavil kratek prikaz neprevedene vsebine. Poleg tega lahko na odjemalcu preskočimo mrežne zahteve, ker že imamo prevode, potrebne za stran, ki si jo uporabnik ogleduje.

Za nastavitev upodabljanja na strežniku, 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 read/write API ključ, da zagotovimo pošiljanje novih nizov v prevod.

Da zagotovimo, da usmerjanje in preusmeritve delujejo kot pričakovano, bomo morali ustvariti datoteko z imenom /middleware.ts. Z uporabo Middleware, lahko preusmerimo uporabnike na strani, prikazane 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);
}

Prepričajte se, da nastavite matcher v skladu z dokumentacijo Middleware v Next.js.

Na odjemalcu lahko spremenite piškotek locale, s čimer določite prednostni jezik uporabnika. Oglejte si celoten primer kode za ideje, kako to narediti!

Korak 5: Razmestite in preizkusite!

Končali smo! Vaša React aplikacija bo zdaj samodejno prevedena, ko dodate kakršne koli nize v komponento Translate. Upoštevajte, da bodo lahko nove nize za prevod ustvarjala le okolja, ki imajo na API ključu dovoljenja read/write. Priporočamo, da imate zaprto in zavarovano predprodukcijsko (staging) okolje, v katerem lahko preizkusite svojo produkcijsko aplikacijo z takšnim API ključem ter dodajate nove nize pred objavo. To bo preprečilo, da bi kdorkoli kdorkoli ukradel vaš skrivni API ključ in s tem potencialno 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!