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

Da die Welt immer stärker globalisiert 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, wie Sie Internationalisierung in Ihre React Next.js-Anwendung mit Server-Side-Rendering integrieren können. TL;DR: Hier sehen 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: Installiere 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 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.

Lassen Sie uns das 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 Kreditkarte.

Erstellen Sie innerhalb der TacoTranslate-Anwendungsoberfläche ein Projekt und navigieren Sie 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 ist das, was wir public nennen, und der read/write Schlüssel ist 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 in Client-seitigen Produktionsumgebungen offengelegt wird.

Wir fügen auch 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, wie zum Beispiel die URL Ihrer Website. Hier erfahren Sie mehr über Origins.

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

Schritt 3: Einrichtung von TacoTranslate

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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.

Wenn Sie den Client in einer separaten Datei erstellen, können Sie ihn später problemlos wieder verwenden. getLocales handelt sich lediglich um eine Hilfsfunktion mit einer integrierten Fehlerbehandlung. Erstellen Sie nun eine Datei mit dem Namen /app/[locale]/tacotranslate.tsx, in der wir den TacoTranslate Anbieter 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';, 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 Sprachcodes, die Sie für Ihr Projekt aktiviert haben, vorgerendert werden.

Jetzt bauen wir unsere erste Seite! Erstellen Sie 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 erstellen und deine Übersetzungen auf dem neuesten Stand zu halten.

Schritt 4: Implementierung des Server-Side-Renderings

TacoTranslate unterstützt Server-Side-Rendering. Dies verbessert die Benutzererfahrung erheblich, da sofort übersetzte Inhalte angezeigt werden, anstatt zunächst einen kurzen Blitz von nicht übersetztem Inhalt zu zeigen. Außerdem können wir Netzwerkanfragen auf der Client-Seite vermeiden, weil 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};
};

Ändern Sie die isProduction Prüfung entsprechend Ihrer Konfiguration. Wenn true, zeigt TacoTranslate den öffentlichen API-Schlüssel an. Wenn wir uns in einer lokalen, Test- oder Staging-Umgebung (isProduction is falsebefinden, verwenden wir den geheimen read/write API-Schlüssel, um sicherzustellen, dass neue Zeichenfolgen zur Übersetzung gesendet werden.

Um sicherzustellen, dass Routing und Weiterleitungen wie erwartet funktionieren, müssen wir eine Datei namens /middleware.ts erstellen. Mit 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 der Client-Seite können Sie den locale Cookie ändern, um die bevorzugte Sprache des Benutzers festzulegen. Bitte sehen Sie sich den vollständigen Beispielcode an, um Ideen zu erhalten, wie das gemacht wird!

Schritt 5: Bereitstellen und testen!

Wir sind fertig! Ihre React-Anwendung wird jetzt automatisch übersetzt, wenn Sie beliebige Zeichenketten zu einer Translate Komponente hinzufügen. Beachten Sie, dass nur Umgebungen mit read/write Berechtigungen auf dem API-Schlüssel neue Zeichenketten zur Übersetzung 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 zusammenhängender Zeichenketten aufbläht.

Stellen Sie sicher, dass Sie sich das komplette Beispiel auf unserem GitHub-Profil ansehen. Dort finden Sie auch ein Beispiel dafür, wie Sie dies mit dem Pages Router machen können! Wenn Sie auf Probleme stoßen, können Sie sich gerne an uns wenden, und wir helfen Ihnen gerne weiter.

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