Wie man Internationalisierung in einer Next.js-Anwendung implementiert, die den App Router verwendet

Da die Welt immer globalisierter wird, ist es für Webentwickler zunehmend wichtig, Anwendungen zu erstellen, die Nutzer aus verschiedenen Ländern und Kulturen bedienen können. Eine der wichtigsten Möglichkeiten, dies zu erreichen, ist Internationalisierung (i18n), die es Ihnen ermöglicht, Ihre Anwendung an verschiedene Sprachen, Währungen und Datumsformate anzupassen.

In diesem Artikel zeigen wir, wie Sie Internationalisierung in Ihre React Next.js-Anwendung mit serverseitigem Rendering integrieren. TL;DR: Hier finden Sie das vollständige Beispiel.

Dieser Leitfaden richtet sich an Next.js-Anwendungen, die den App Router verwenden.
Wenn Sie den Pages Router verwenden, lesen Sie stattdessen diesen Leitfaden.

Schritt 1: Installieren Sie eine i18n-Bibliothek

Um Internationalisierung in Ihrer Next.js-Anwendung zu implementieren, wählen wir zunächst eine i18n-Bibliothek. Es gibt mehrere beliebte Bibliotheken, darunter next-intl. In diesem Beispiel verwenden wir jedoch TacoTranslate.

TacoTranslate übersetzt Ihre Strings automatisch mit modernster KI in jede Sprache und erspart Ihnen die mühsame Verwaltung von JSON-Dateien.

Installieren wir es mit npm in Ihrem Terminal:

npm install tacotranslate

Schritt 2: Erstellen Sie ein kostenloses TacoTranslate-Konto

Jetzt, da Sie das Modul installiert haben, ist es an der Zeit, Ihr TacoTranslate-Konto, ein Übersetzungsprojekt und die zugehörigen API-Schlüssel zu erstellen. Erstellen Sie hier ein Konto. Es ist kostenlos und erfordert keine Angabe einer Kreditkarte.

Öffne die TacoTranslate-Anwendungsoberfläche, erstelle ein Projekt und navigiere zur Registerkarte für API-Schlüssel. Erstelle einen read Schlüssel und einen read/write Schlüssel. Wir speichern sie als Umgebungsvariablen. Der read Schlüssel ist das, was wir public nennen, und der read/write Schlüssel ist secret. Du kannst sie zum Beispiel in einer .env Datei im Stammverzeichnis deines Projekts hinzufügen.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Stellen Sie unbedingt sicher, dass der geheime read/write API‑Schlüssel niemals in clientseitige Produktionsumgebungen offengelegt wird.

Wir fügen außerdem zwei weitere Umgebungsvariablen hinzu: TACOTRANSLATE_DEFAULT_LOCALE und TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Der standardmäßige Fallback-Locale-Code. In diesem Beispiel setzen wir ihn auf en für Englisch.
• TACOTRANSLATE_ORIGIN: Der „Ordner“, in dem Ihre Strings gespeichert werden, z. B. die URL Ihrer Website. Mehr über Origins erfahren Sie hier.

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

Schritt 3: TacoTranslate einrichten

Um TacoTranslate in Ihre Anwendung zu integrieren, müssen Sie einen Client erstellen, der die zuvor erstellten API‑Schlüssel verwendet. Erstellen Sie zum Beispiel eine Datei mit dem Namen /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;

Wir werden in Kürze automatisch TACOTRANSLATE_API_KEY und TACOTRANSLATE_PROJECT_LOCALE definieren.

Das Erstellen des Clients in einer separaten Datei macht es einfach, ihn später wiederzuverwenden. getLocales ist nur eine Hilfsfunktion mit eingebauter Fehlerbehandlung. Erstelle nun eine Datei mit dem Namen /app/[locale]/tacotranslate.tsx, in der wir den TacoTranslate Provider implementieren.

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

Beachte 'use client';, die darauf hinweist, dass es sich um eine Client-Komponente handelt.

Da der Kontext-Provider jetzt einsatzbereit ist, erstellen Sie eine Datei namens /app/[locale]/layout.tsx, das Root-Layout in unserer Anwendung. Beachten Sie, dass dieser Pfad einen Ordner enthält, der Dynamic Routes verwendet, wobei [locale] der dynamische Parameter ist.

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

Zunächst ist zu beachten, dass wir unseren Dynamic Route Parameter [locale] verwenden, um Übersetzungen für diese Sprache abzurufen. Zusätzlich stellt generateStaticParams sicher, dass alle Locale-Codes, die Sie für Ihr Projekt aktiviert haben, vorgeneriert werden.

Jetzt erstellen wir unsere erste Seite! Erstelle eine Datei mit dem Namen /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!" />
	);
}

Beachte die revalidate Variable, die Next.js anweist, die Seite nach 60 Sekunden neu zu bauen und deine Übersetzungen auf dem neuesten Stand zu halten.

Schritt 4: Implementierung des serverseitigen Renderings

TacoTranslate unterstützt serverseitiges Rendering. Das verbessert die Nutzererfahrung erheblich, da übersetzte Inhalte sofort angezeigt werden, anstatt dass zunächst kurz unübersetzte Inhalte erscheinen. Außerdem können wir Netzwerkaufrufe auf dem Client überspringen, weil wir bereits die für die aktuell vom Nutzer betrachtete Seite benötigten Übersetzungen haben.

Um Server-Side-Rendering einzurichten, erstellen oder bearbeiten Sie /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};
};

Ändere die Prüfung isProduction so, dass sie zu deiner Konfiguration passt. Wenn true, wird TacoTranslate den öffentlichen API-Schlüssel anzeigen. Befinden wir uns in einer lokalen, Test- oder Staging-Umgebung (isProduction is false), verwenden wir den geheimen read/write API-Schlüssel, damit neue Strings zur Übersetzung gesendet werden.

Um sicherzustellen, dass Routing und Weiterleitungen wie erwartet funktionieren, müssen wir eine Datei namens /middleware.ts erstellen. Mithilfe von Middleware können wir Benutzer auf Seiten umleiten, die in ihrer bevorzugten Sprache angezeigt werden.

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

Stellen Sie sicher, dass Sie den matcher gemäß der Next.js Middleware-Dokumentation einrichten.

Auf dem Client können Sie das Cookie locale ändern, um die bevorzugte Sprache des Nutzers festzulegen. Bitte sehen Sie sich den vollständigen Beispielcode an, um Ideen zu erhalten, wie Sie das tun können!

Schritt 5: Bereitstellen und testen!

Fertig! Ihre React-Anwendung wird nun automatisch übersetzt, wenn Sie beliebige Strings zu einer Translate Komponente hinzufügen. Beachten Sie, dass nur Umgebungen mit read/write Berechtigungen für den API-Schlüssel neue Strings erstellen können, die übersetzt werden sollen. Wir empfehlen, eine geschlossene und gesicherte Staging-Umgebung einzurichten, in der Sie Ihre Produktionsanwendung mit einem solchen API-Schlüssel testen und neue Strings hinzufügen können, bevor Sie live gehen. So verhindern Sie, dass jemand Ihren geheimen API-Schlüssel stiehlt und Ihr Übersetzungsprojekt möglicherweise durch das Hinzufügen neuer, nicht zusammenhängender Strings aufbläht.

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!