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

Da die Welt immer mehr globalisiert wird, ist es für Webentwickler zunehmend wichtiger, Anwendungen zu erstellen, die Nutzern aus verschiedenen Ländern und Kulturen gerecht werden können. Eine der wichtigsten Methoden, dies zu erreichen, ist die Internationalisierung (i18n), die es 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 Server-Side Rendering integrieren. TL;DR: Hier finden Sie das vollständige Beispiel.

Dieser Leitfaden ist für Next.js-Anwendungen, die den App Router verwenden.
Wenn Sie den Pages Router verwenden, sehen 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 aus. Es gibt mehrere beliebte Bibliotheken, darunter next-intl. In diesem Beispiel werden wir jedoch TacoTranslate verwenden.

TacoTranslate übersetzt Ihre Strings automatisch mit modernster KI in jede Sprache und befreit Sie von der mühsamen Verwaltung von JSON-Dateien.

Lassen Sie uns TacoTranslate mit npm in Ihrem Terminal installieren:

npm install tacotranslate

Schritt 2: Erstellen Sie ein kostenloses TacoTranslate-Konto

Jetzt, da Sie das Modul installiert haben, ist es 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.

Innerhalb der TacoTranslate-Anwendungsoberfläche erstellen Sie ein Projekt und navigieren zum Tab für API-Schlüssel. Erstellen Sie einen read Schlüssel und einen read/write Schlüssel. Wir speichern diese als Umgebungsvariablen. Der read Schlüssel wird als public bezeichnet und der read/write Schlüssel als secret. Zum Beispiel könnten Sie sie in einer .env Datei im Stammverzeichnis Ihres Projekts hinzufügen.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Stellen Sie sicher, dass der geheime read/write API-Schlüssel niemals in produktiven Client-Umgebungen verbreitet wird.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Der standardmäßige Fallback-Sprachcode. 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. Hier erfahren Sie mehr über Origins.

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 mit den zuvor erstellten API-Schlüsseln anlegen. Erstellen Sie beispielsweise eine Datei namens /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.

Die Erstellung des Clients in einer separaten Datei erleichtert die spätere Wiederverwendung. getLocales ist lediglich eine Hilfsfunktion mit integrierter Fehlerbehandlung. Erstellen Sie nun eine Datei mit dem Namen /app/[locale]/tacotranslate.tsx, in der wir den TacoTranslate Provider implementieren werden.

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

Beachten Sie 'use client';, das anzeigt, dass dies eine Client-Komponente ist.

Da der Kontext-Provider nun einsatzbereit ist, erstellen Sie eine Datei namens /app/[locale]/layout.tsx, das Root-Layout in unserer Anwendung. Beachten Sie, dass dieser Pfad einen Ordner verwendet, der Dynamic Routes nutzt, 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>
	);
}

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

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

Beachten Sie die revalidate Variable, die Next.js anweist, die Seite nach 60 Sekunden neu zu erstellen und Ihre Übersetzungen auf dem neuesten Stand zu halten.

Schritt 4: Implementierung des serverseitigen Renderings

TacoTranslate unterstützt Server-Side-Rendering. Dies verbessert die Benutzererfahrung erheblich, indem sofort übersetzte Inhalte angezeigt werden, anstatt zunächst einen kurzen Moment unübersetzter Inhalte zu zeigen. Außerdem können wir Netzwerkanfragen auf der Client-Seite überspringen, da wir bereits die Übersetzungen haben, die wir für die Seite benötigen, die der Benutzer gerade betrachtet.

Um das Server-Side Rendering einzurichten, erstellen oder ändern 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};
};

Passe die isProduction Prüfung an deine Umgebung an. Wenn true ist, zeigt TacoTranslate den öffentlichen API-Schlüssel an. Befinden wir uns in einer lokalen, Test- oder Staging-Umgebung (isProduction is false), verwenden wir den geheimen read/write API-Schlüssel, um sicherzustellen, dass 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 zu Seiten weiterleiten, 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 locale Cookie ändern, um die bevorzugte Sprache des Benutzers festzulegen. Bitte sehen Sie sich den vollständigen Beispielcode an, um Ideen zu erhalten, wie dies gemacht wird!

Schritt 5: Bereitstellen und testen!

Wir sind fertig! Ihre React-Anwendung wird nun automatisch übersetzt, sobald Sie beliebige Strings zu einer Translate Komponente hinzufügen. Beachten Sie, dass nur Umgebungen mit read/write Berechtigungen auf den API-Schlüssel in der Lage sein werden, neue Strings zur Übersetzung zu erstellen. Wir empfehlen, eine geschlossene und gesicherte Staging-Umgebung einzurichten, in der Sie Ihre Produktionsanwendung mit einem solchen API-Schlüssel testen können, indem Sie vor dem Livegang neue Strings hinzufügen. Dies verhindert, dass jemand Ihren geheimen API-Schlüssel stiehlt und möglicherweise Ihr Übersetzungsprojekt durch das Hinzufügen neuer, nicht zusammenhängender Strings unnötig aufbläht.

Stellen Sie sicher, dass Sie das vollständige Beispiel auf unserem GitHub-Profil ansehen. Dort finden Sie auch ein Beispiel, wie dies mit dem Pages Router funktioniert! Sollten Sie auf Probleme stoßen, können Sie sich jederzeit gerne an uns wenden, und wir helfen Ihnen gerne weiter.

TacoTranslate ermöglicht es Ihnen, Ihre React-Anwendungen schnell und automatisch in jede Sprache zu lokalisieren. Starten Sie noch heute!