Hoe internationalisering te implementeren in een Next.js-applicatie die gebruikmaakt van de App Router

Naarmate de wereld meer geglobaliseerd wordt, wordt het steeds belangrijker voor webontwikkelaars om applicaties te bouwen die kunnen inspelen op gebruikers uit verschillende landen en culturen. Een van de belangrijkste manieren om dit te bereiken is via internationalisatie (i18n), waarmee je je applicatie kunt aanpassen aan verschillende talen, valuta’s en datumformaten.

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

Deze gids is voor Next.js-applicaties die gebruikmaken van de App Router.
Als je de Pages Router gebruikt, bekijk dan in plaats daarvan deze gids.

Stap 1: Installeer een i18n-bibliotheek

Om internationalisatie in je 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 gebruiken.

TacoTranslate vertaalt je strings automatisch naar elke taal met behulp van geavanceerde AI, en bevrijdt je van het saaie beheer van JSON-bestanden.

Laten we het installeren met behulp van npm in je terminal:

npm install tacotranslate

Stap 2: Maak een gratis TacoTranslate-account aan

Nu 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 creditcard.

Binnen de TacoTranslate applicatie-UI, maak een project aan en navigeer naar het tabblad met API-sleutels. Maak één read sleutel en één read/write sleutel aan. We zullen ze opslaan als omgevingsvariabelen. De read sleutel noemen we public en de read/write sleutel is secret. Bijvoorbeeld, je kunt ze 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 nooit de geheime read/write API-sleutel lekt naar productieomgevingen aan de clientzijde.

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

• TACOTRANSLATE_DEFAULT_LOCALE: De standaard fallback-taalcode. In dit voorbeeld stellen we deze in op en voor Engels.
• TACOTRANSLATE_ORIGIN: De “map” waar je je strings opslaat, 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 met 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 later gemakkelijk om opnieuw te gebruiken. getLocales is slechts een hulpfunctie met ingebouwde foutafhandeling. Maak nu een bestand aan met de naam /app/[locale]/tacotranslate.tsx, waar 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 client component is.

Met de contextprovider nu klaar voor gebruik, maak een bestand met de naam /app/[locale]/layout.tsx, de hoofdlayout in onze applicatie. Let op dat dit pad een map bevat 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 wat hier opvalt is dat we onze Dynamic Route parameter [locale] gebruiken om vertalingen voor die taal op te halen. Daarnaast zorgt generateStaticParams ervoor dat alle locale codes die je voor je project hebt geactiveerd van tevoren worden gepre-renderd.

Laten we nu onze eerste pagina maken! Maak een bestand aan 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 om de pagina na 60 seconden opnieuw op te bouwen, en je vertalingen up-to-date te houden.

Stap 4: Implementatie van server side rendering

TacoTranslate ondersteunt server-side rendering. Dit verbetert de gebruikerservaring aanzienlijk door direct vertaalde inhoud te tonen, in plaats van eerst een flits van niet-vertaalde inhoud. Bovendien kunnen we netwerkverzoeken aan de clientzijde 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 controle aan zodat deze bij jouw setup past. Als true is, toont TacoTranslate de publieke API-sleutel. Als we ons in een lokale, test- of stagingomgeving bevinden (isProduction is false), gebruiken we de geheime read/write API-sleutel om ervoor te zorgen dat nieuwe strings worden verzonden voor vertaling.

Om te garanderen dat routing en omleiding werken zoals verwacht, moeten we een bestand aanmaken genaamd /middleware.ts. Met behulp van Middleware kunnen we gebruikers naar pagina's leiden 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 volgens de Next.js Middleware documentatie.

Aan de clientzijde kun je de locale cookie wijzigen om de voorkeurstaal van de gebruiker aan te passen. Bekijk de volledige voorbeeldcode voor ideeën over hoe je dit kunt doen!

Stap 5: Implementeren en testen!

We zijn klaar! Je React-applicatie wordt nu automatisch vertaald wanneer je nieuwe teksten toevoegt aan een Translate component. Houd er rekening mee dat alleen omgevingen met read/write rechten op de API-sleutel nieuwe teksten kunnen aanmaken om vertaald te worden. We raden aan om een gesloten en beveiligde staging-omgeving te hebben waar je je productie-applicatie kunt testen met zo’n API-sleutel, en nieuwe teksten kunt toevoegen voordat je live gaat. Dit voorkomt dat iemand je geheime API-sleutel steelt en mogelijk je vertaalproject opblaast door nieuwe, niet-gerelateerde teksten toe te voegen.

Zorg ervoor dat je het complete voorbeeld bekijkt op ons GitHub-profiel. Daar vind je ook een voorbeeld van hoe je dit kunt doen met de Pages Router! Als je problemen tegenkomt, aarzel dan niet om contact op te nemen, we helpen je graag verder.

TacoTranslate stelt je in staat om je React-toepassingen automatisch snel te lokaliseren naar en vanuit elke taal. Begin vandaag nog!