Hoe implementeer je internationalisatie in een Next.js-applicatie die de App Router gebruikt

Naarmate de wereld verder globaliseert, wordt het voor webontwikkelaars steeds belangrijker om toepassingen te bouwen die tegemoetkomen aan gebruikers uit verschillende landen en culturen. Een van de belangrijkste manieren om dit te bereiken is internationalisatie (i18n), waarmee je je applicatie kunt aanpassen aan verschillende talen, valuta en datumformaten.

In dit artikel bekijken we hoe je internationalisatie toevoegt aan je React Next.js-applicatie, met server-side rendering. TL;DR: Bekijk hier het volledige voorbeeld.

Deze handleiding is voor Next.js-toepassingen die de App Router gebruiken.
Als u de Pages Router gebruikt, raadpleeg dan in plaats daarvan deze handleiding.

Stap 1: Installeer een i18n-bibliotheek

Om internationalisatie in uw Next.js-applicatie te implementeren, kiezen we eerst een i18n-bibliotheek. Er zijn verschillende populaire bibliotheken, waaronder next-intl. In dit voorbeeld zullen we echter TacoTranslate.

TacoTranslate vertaalt uw strings automatisch naar elke taal met behulp van geavanceerde AI en neemt u het vervelende beheer van JSON-bestanden uit handen.

Laten we het installeren met npm in uw terminal:

npm install tacotranslate

Stap 2: Maak een gratis TacoTranslate-account aan

Nadat je de module hebt geïnstalleerd, is het tijd om je TacoTranslate-account, een vertaalproject en de bijbehorende API-sleutels aan te maken. Maak hier een account aan. Het is gratis en vereist geen creditcardgegevens.

Maak in de TacoTranslate-applicatie-UI een project aan en navigeer naar het tabblad API-sleutels. Maak één read sleutel en één read/write sleutel aan. We slaan ze op als omgevingsvariabelen. De read sleutel is wat wij public noemen en de read/write sleutel is secret. Je kunt ze bijvoorbeeld toevoegen aan een .env bestand in de root van je project.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Zorg ervoor dat je de geheime read/write API-sleutel nooit blootstelt in client-side productieomgevingen.

We voegen ook nog twee omgevingsvariabelen toe: TACOTRANSLATE_DEFAULT_LOCALE en TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: De standaard fallback-localecode. In dit voorbeeld stellen we deze in op en voor Engels.
• TACOTRANSLATE_ORIGIN: De “map” waarin je strings worden opgeslagen, zoals de URL van je website. Lees hier meer over origins.

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

Stap 3: TacoTranslate instellen

Om TacoTranslate in je applicatie te integreren, moet je een client aanmaken met behulp van de eerder genoemde API-sleutels. Maak bijvoorbeeld een bestand aan met de naam /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;

We zullen binnenkort automatisch TACOTRANSLATE_API_KEY en TACOTRANSLATE_PROJECT_LOCALE definiëren.

Het aanmaken van de client in een apart bestand maakt het gemakkelijk om deze later opnieuw te gebruiken. getLocales is gewoon een hulpfunctie met wat ingebouwde foutafhandeling. Maak nu een bestand met de naam /app/[locale]/tacotranslate.tsx, waarin we de TacoTranslate provider zullen implementeren.

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

Let op de 'use client'; die aangeeft dat dit een clientcomponent is.

Nu de contextprovider klaar is om te gebruiken, maak een bestand met de naam /app/[locale]/layout.tsx, de root-layout van onze applicatie. Let op dat dit pad een map heeft die gebruikmaakt van Dynamic Routes, waarbij [locale] de dynamische parameter is.

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

Het eerste dat je hier moet weten is dat we onze Dynamic Route parameter [locale] gebruiken om vertalingen voor die taal op te halen. Daarnaast zorgt generateStaticParams ervoor dat alle taalcodes die je voor je project hebt geactiveerd vooraf worden gerenderd.

Laten we nu onze eerste pagina bouwen! Maak een bestand met de naam /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!" />
	);
}

Let op de revalidate variabele die Next.js vertelt de pagina na 60 seconden opnieuw te bouwen, en je vertalingen up-to-date te houden.

Stap 4: Server-side rendering implementeren

TacoTranslate ondersteunt server-side rendering. Dit verbetert de gebruikerservaring aanzienlijk doordat vertaalde inhoud direct wordt weergegeven, in plaats van eerst een korte flits van onvertaalde inhoud. Daarnaast kunnen we netwerkverzoeken vanuit de client overslaan, omdat we al de vertalingen hebben die we nodig hebben voor de pagina die de gebruiker bekijkt.

Om server-side rendering in te stellen, maak of wijzig /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};
};

Pas de isProduction check aan zodat deze bij je configuratie past. Als true, zal TacoTranslate de publieke API-sleutel tonen. Als we in een lokale, test- of stagingomgeving zijn (isProduction is false), gebruiken we de geheime read/write API-sleutel om ervoor te zorgen dat nieuwe strings voor vertaling worden verzonden.

Om ervoor te zorgen dat routering en omleidingen naar behoren werken, moeten we een bestand aanmaken met de naam /middleware.ts. Met behulp van Middleware, kunnen we gebruikers omleiden naar pagina's die in hun voorkeurstaal worden weergegeven.

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

Zorg ervoor dat je de matcher instelt in overeenstemming met de Next.js Middleware-documentatie.

Aan de clientzijde kun je het locale cookie aanpassen om de voorkeurstaal van de gebruiker te wijzigen. Zie de complete voorbeeldcode voor ideeën over hoe je dit kunt doen!

Stap 5: Uitrollen en testen!

We zijn klaar! Je React-applicatie wordt nu automatisch vertaald wanneer je strings toevoegt aan een Translate component. Let op: alleen omgevingen met read/write machtigingen op de API-sleutel kunnen nieuwe strings aanmaken die vertaald moeten worden. We raden aan een gesloten en beveiligde stagingomgeving te hebben waar je je productie-applicatie kunt testen met zo'n API-sleutel, en daarbij nieuwe strings toe te voegen voordat je live gaat. Dit voorkomt dat iemand je geheime API-sleutel steelt en mogelijk je vertaalproject opblaast door nieuwe, niet-verwante strings toe te voegen.

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!