Hoe je internationalisatie implementeert in een Next.js‑applicatie die de Pages Router gebruikt

Naarmate de wereld steeds meer globaliseert, wordt het voor webontwikkelaars steeds belangrijker om applicaties te bouwen die gebruikers uit verschillende landen en culturen kunnen bedienen. 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 deze tutorial leggen we uit hoe je internationalisatie toevoegt aan je React Next.js-applicatie, inclusief server-side rendering. TL;DR: Zie het volledige voorbeeld hier.

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

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.

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

Laten we het installeren met 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 niet dat je een creditcard toevoegt.

Open de TacoTranslate-applicatie-UI, maak een project aan en ga 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 we public noemen 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 de geheime read/write API-sleutel nooit lekt naar 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, bijvoorbeeld 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 uw applicatie te integreren, moet u een client aanmaken met de eerder genoemde API-sleutels. Maak bijvoorbeeld een bestand genaamd /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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

We zullen binnenkort automatisch TACOTRANSLATE_API_KEY definiëren.

Het aanmaken van de client in een apart bestand maakt het later gemakkelijker om deze opnieuw te gebruiken. Nu voegen we, met een aangepast /pages/_app.tsx, de TacoTranslate provider toe.

import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

type PageProperties = {
	origin: Origin;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, locales, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

Als je al aangepaste pageProps en _app.tsx hebt, breid dan de definitie uit met de bovengenoemde eigenschappen en code.

Stap 4: Implementatie van server-side rendering

TacoTranslate ondersteunt server-side rendering van je vertalingen. Dit verbetert de gebruikerservaring aanzienlijk door vertaalde inhoud meteen weer te geven, in plaats van eerst een korte flits van onvertaalde inhoud. Bovendien kunnen we netwerkverzoeken aan de client overslaan, omdat we al over alle benodigde vertalingen beschikken.

We beginnen met het aanmaken of aanpassen van /next.config.js.

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		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'),
	});
};

Pas de isProduction controle aan zodat deze bij je configuratie past. Als true, toont TacoTranslate de openbare API-sleutel. 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.

Tot nu toe hebben we de Next.js-applicatie alleen ingesteld met een lijst van ondersteunde talen. Het volgende dat we gaan doen is vertalingen voor al je pagina's ophalen. Hiervoor gebruik je ofwel getTacoTranslateStaticProps of getTacoTranslateServerSideProps op basis van je vereisten.

Deze functies nemen drie argumenten: een Next.js Static Props Context object, configuratie voor TacoTranslate, en optionele Next.js-eigenschappen. Let op dat revalidate op getTacoTranslateStaticProps standaard is ingesteld op 60, zodat je vertalingen up-to-date blijven.

Om een van beide functies in een pagina te gebruiken, laten we aannemen dat je een paginabestand hebt zoals /pages/hello-world.tsx.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

export default function Page() {
	return <Translate string="Hello, world!"/>;
}

Je zou nu de Translate component moeten kunnen gebruiken om strings binnen al je React-componenten te vertalen.

import {Translate} from 'tacotranslate/react';

function Component() {
	return <Translate string="Hello, world!"/>
}

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 dat alleen omgevingen met read/write permissies op de API-sleutel nieuwe strings kunnen aanmaken die vertaald moeten worden. We raden aan een gesloten en beveiligde staging-omgeving te hebben waar je je productieapplicatie kunt testen met zo'n API-sleutel, en daar nieuwe strings toe te voegen voordat je live gaat. Dit voorkomt dat iemand iemand je geheime API-sleutel steelt, en mogelijk je vertaalproject opblaast door nieuwe, niet-gerelateerde strings toe te voegen.

Zorg ervoor dat je het volledige voorbeeld bekijkt op ons GitHub-profiel. Daar vind je ook een voorbeeld van hoe je dit kunt doen met behulp van de App Router! Als je problemen tegenkomt, neem dan gerust contact met ons op, we helpen je graag.

TacoTranslate maakt het mogelijk om je React-applicaties automatisch te lokaliseren naar en vanuit meer dan 75 talen. Begin vandaag nog!