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

S svetom, ki postaja vedno bolj globaliziran, je za spletne razvijalce vse pomembneje, da ustvarjajo aplikacije, ki so prilagojene uporabnikom iz različnih držav in kultur. Eden ključnih načinov za uresničitev tega je prek internacionalizacije (i18n), ki omogoča prilagoditev vaše aplikacije različnim jezikom, valutam in datumskim formatom.

V tem članku bomo raziskali, kako v vašo React Next.js aplikacijo dodati internacionalizacijo z uporabo strežniškega upodabljanja (server side rendering). TL;DR: Tukaj si oglejte celoten primer.

Ta vodič je namenjen Next.js aplikacijam, ki uporabljajo App Router.
Če uporabljate Pages Router, si oglejte raje ta vodič.

Korak 1: Namestite i18n knjižnico

Za implementacijo internacionalizacije v vaši Next.js aplikaciji bomo najprej izbrali knjižnico i18n. 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 JSON datotek.

Namestimo ga preko npm v vašem terminalu:

npm install tacotranslate

Korak 2: Ustvarite brezplačen račun TacoTranslate

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

V uporabniškem vmesniku aplikacije TacoTranslate ustvarite projekt in pojdite na zavihek za API ključe. Ustvarite en read ključ in en read/write ključ. Shranili jih bomo kot okoljske spremenljivke. read ključ imenujemo public, medtem ko je read/write ključ 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 nikoli ne boste razkrili skrivnega ključa read/write API v produkcijskih okoljih na strani odjemalca.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Privzeta koda jezika, ki se uporabi, če ni na voljo druge. V tem primeru jo bomo nastavili na en za angleščino.
• TACOTRANSLATE_ORIGIN: »Mapa«, kjer bodo shranjene vaše besedilne 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

Za integracijo TacoTranslate z vašo aplikacijo boste morali ustvariti klienta z uporabo API ključev, omenjenih prej. 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 klienta v ločeni datoteki omogoča enostavno ponovno uporabo kasneje. getLocales je le pomožna funkcija z vgrajenim upravljanjem napak. 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>
	);
}

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

Ko je kontekstni ponudnik pripravljen za uporabo, ustvarite datoteko z imenom /app/[locale]/layout.tsx, glavno 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 opaziti, je, da uporabljamo naš parameter Dynamic Route [locale] za pridobivanje prevodov za ta jezik. Poleg tega generateStaticParams zagotavlja, da so vsi jezikovni kodi, ki ste jih aktivirali za vaš projekt, predhodno upodobljeni.

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!" />
	);
}

Opazite spremenljivko revalidate, ki sporoča Next.js, naj po 60 sekundah znova zgradi stran in posodobi vaše prevode.

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

TacoTranslate podpira strežniško upodabljanje. To močno izboljša uporabniško izkušnjo tako, da takoj prikaže prevedeno vsebino, namesto da bi se najprej prikazal utrinek neprevedene vsebine. Poleg tega se lahko izognemo mrežnim zahtevam na odjemalcu, ker že imamo prevode, ki jih potrebujemo za stran, ki jo uporabnik trenutno gleda.

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};
};

Spremenite preverjanje isProduction tako, da ustreza vaši nastavitvi. Če true, bo TacoTranslate prikazal javni ključ API. Če smo v lokalnem, preskusnem ali pripravljalnem okolju (isProduction is false), bomo uporabili skrivni ključ API read/write , da zagotovimo, da so novi nizi poslani v prevod.

Da zagotovimo, da usmerjanje in preusmeritev delujeta kot pričakovano, bomo morali ustvariti datoteko z imenom /middleware.ts. Z uporabo Middleware lahko preusmerimo uporabnike na strani, prikazane v njihovem izbranem 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 strani odjemalca lahko spremenite piškotek locale, da spremenite uporabnikov jezik, ki ga ima nastavljenega kot privzetega. Za ideje, kako to narediti, si oglejte celoten primer kode!

Korak 5: Objavi in preizkusi!

Končali smo! Vaša React aplikacija bo zdaj samodejno prevedena, ko dodate katerikoli niz v komponento Translate. Upoštevajte, da bodo lahko nove nize za prevod ustvarjala le okolja z dovoljenji read/write za API ključ. Priporočamo, da imate zaprto in varno staging okolje, kjer lahko preizkusite vašo produkcijsko aplikacijo z API ključem, kot je ta, ter dodajate nove nize pred objavo v živo. S tem boste preprečili, da bi kdorkoli ukradel vaš skrivni API ključ in 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!