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

Ker svet postaja vedno bolj globaliziran, je za spletne razvijalce vse pomembneje, da ustvarjajo aplikacije, ki lahko zadostijo uporabnikom iz različnih držav in kultur. Ena ključnih poti za dosego tega je internacionalizacija (i18n), ki vam omogoča prilagoditev aplikacije različnim jezikom, valutam in formatom datumov.

V tem članku bomo raziskali, kako dodati internacionalizacijo vaši React Next.js aplikaciji, s pomočjo strežniške strani (server side rendering). TL;DR: Oglejte si celoten primer tukaj.

Ta vodič je za Next.js aplikacije, 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 nadležnega upravljanja JSON datotek.

Namestimo ga z uporabo npm v vašem terminalu:

npm install tacotranslate

2. korak: Ustvarite brezplačen račun TacoTranslate

Zdaj, ko ste namestili modul, je čas, da ustvarite svoj račun TacoTranslate, 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 pojdite na zavihek njegove 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

Prepričajte se, da nikoli ne razkrijete skrivnega ključa API read/write v produkcijskih okoljih na strani odjemalca.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Privzeta koda jezikovne nastavitve za primer nazaj. V tem primeru jo bomo nastavili na en za angleščino.
• TACOTRANSLATE_ORIGIN: "Mapa", kjer bodo shranjene vaše besedilne nize, na primer URL vaše spletne strani. Preberite več o nastavitvah "origin" 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 prej omenjenih 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 definirali TACOTRANSLATE_API_KEY in TACOTRANSLATE_PROJECT_LOCALE.

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

'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 pomeni, da je to komponenta za 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 opozoriti, je, da uporabljamo naš Dynamic Route parameter [locale] za pridobivanje prevodov za ta jezik. Poleg tega generateStaticParams zagotavlja, da so vsi jezikovni kodi, ki ste jih aktivirali za vaš projekt, vnaprej upodobljeni.

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

Opazite spremenljivko revalidate, ki sporoča Next.js, naj po 60 sekundah ponovno zgradi stran in tako ohrani vaše prevode ažurne.

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

TacoTranslate podpira renderiranje na strežniku. To močno izboljša uporabniško izkušnjo, saj takoj prikaže prevedeno vsebino, namesto da bi najprej pokazal utrinek nep prevedene vsebine. Poleg tega lahko preskočimo mrežne zahteve 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 pravilno delovanje usmerjanja in preusmerjanja, bomo morali ustvariti datoteko z imenom /middleware.ts. Z uporabo Middleware lahko uporabnike preusmerimo na strani, prikazane v njihovi priljubljeni jezikovni različici.

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, da prilagodite jezik, ki ga uporabnik preferira. 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 katere koli nize v komponento Translate. Upoštevajte, da bodo lahko le okolja z dovoljenji read/write za API ključ ustvarjala nove nize za prevajanje. Priporočamo, da imate zaprto in varno testno okolje, kjer lahko preizkusite svojo produkcijsko aplikacijo z takšnim API ključem, pri čemer dodajate nove nize pred zagonom v živo. To bo preprečilo, da bi kdo ukradel vaš skrivni API ključ in potencialno napihnil vaš prevajalski projekt z dodajanjem novih, nepovezanih nizov.

Ne pozabite pogledati celoten primer na našem GitHub profilu. Tam boste našli tudi primer, kako to storiti z uporabo Pages Router! Če naletite na kakršne koli težave, nas prosimo kontaktirajte, z veseljem vam bomo pomagali.

TacoTranslate vam omogoča, da svoje React aplikacije hitro samodejno lokalizirate v katerikoli jezik in iz njega. Začnite danes!