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 ansprechen können. Eine der wichtigsten Möglichkeiten, dies zu erreichen, ist die Internationalisierung (i18n), die es Ihnen ermöglicht, Ihre Anwendung an verschiedene Sprachen, Währungen und Datumsformate anzupassen.

In diesem Artikel zeigen wir Ihnen, wie Sie Internationalisierung in Ihre React Next.js-Anwendung mit Server-Side-Rendering integrieren. TL;DR: Das vollständige Beispiel finden Sie hier.

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 aus. Es gibt mehrere beliebte Bibliotheken, darunter next-intl. In diesem Beispiel werden wir jedoch TacoTranslate verwenden.

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

Lassen Sie uns das über npm in Ihrem Terminal installieren:

npm install tacotranslate

Schritt 2: Erstellen Sie ein kostenloses TacoTranslate-Konto

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

Erstellen Sie innerhalb der TacoTranslate-Anwendungsoberfläche ein Projekt und navigieren Sie zu dessen API-Schlüssel-Tab. 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 eine .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 an produktive Client-Seiten-Umgebungen weitergegeben wird.

Wir werden auch zwei weitere Umgebungsvariablen hinzufügen: TACOTRANSLATE_DEFAULT_LOCALE und TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Der standardmäßige Fallback-Locales-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: Einrichtung von TacoTranslate

Um TacoTranslate in Ihre Anwendung zu integrieren, müssen Sie einen Client mit den zuvor erstellten API-Schlüsseln erstellen. 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.

Das Erstellen des Clients in einer separaten Datei macht es einfach, ihn später erneut zu verwenden. getLocales ist lediglich eine Hilfsfunktion mit eingebauter Fehlerbehandlung. Erstelle nun eine Datei namens /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';, die darauf hinweist, 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 sorgt generateStaticParams dafür, dass alle für Ihr Projekt aktivierten Sprachcodes vorab gerendert werden.

Lass uns nun unsere erste Seite erstellen! 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 aktuell zu halten.

Schritt 4: Implementierung des Server-Side Rendering

TacoTranslate unterstützt serverseitiges Rendering. Dies verbessert die Benutzererfahrung erheblich, da der übersetzte Inhalt sofort angezeigt wird, anstatt zuerst einen kurzen Blitz von nicht übersetztem Inhalt zu zeigen. Zusätzlich können wir Netzwerk-Anfragen auf der Client-Seite vermeiden, da wir bereits die Übersetzungen für die Seite, die der Nutzer ansieht, vorliegen haben.

Um das 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};
};

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 Weiterleitung wie erwartet funktionieren, müssen wir eine Datei namens /middleware.ts erstellen. Mithilfe von Middleware können wir Benutzer auf 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 für Ideen an, wie Sie dies tun können!

Schritt 5: Bereitstellen und testen!

Wir sind fertig! Ihre React-Anwendung wird nun automatisch übersetzt, sobald Sie Zeichenketten zu einer Translate Komponente hinzufügen. Beachten Sie, dass nur Umgebungen mit read/write Berechtigungen für den API-Schlüssel neue zu übersetzende Zeichenketten erstellen können. Wir empfehlen, eine geschlossene und gesicherte Staging-Umgebung zu haben, in der Sie Ihre Produktionsanwendung mit einem solchen API-Schlüssel testen können, indem Sie neue Zeichenketten hinzufügen, bevor Sie live gehen. Dies verhindert, dass jemand Ihren geheimen API-Schlüssel stiehlt und möglicherweise Ihr Übersetzungsprojekt durch das Hinzufügen neuer, nicht verwandter Zeichenketten unnötig aufbläht.

Stellen Sie sicher, dass Sie das komplette Beispiel auf unserem GitHub-Profil ansehen. Dort finden Sie auch ein Beispiel, wie Sie dies mit dem Pages Router machen können! Wenn Sie Probleme haben, zögern Sie nicht, Kontakt aufzunehmen, und wir helfen Ihnen gern weiter.

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