Die beste Lösung für Internationalisierung (i18n) in Next.js-Apps

Wie es funktioniert

Da die Welt immer globalisierter wird, ist es für Webentwickler zunehmend wichtiger, Anwendungen zu erstellen, die Nutzer aus verschiedenen Ländern und Kulturen ansprechen 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 Tutorial zeigen wir, wie Sie Ihrem React Next.js-Anwendung Internationalisierung mit serverseitigem Rendering hinzufügen können. TL;DR: Hier finden Sie das vollständige Beispiel.

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

Schritt 1: Installieren Sie eine i18n-Bibliothek

Um die Internationalisierung in Ihrer Next.js-Anwendung umzusetzen, 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 Paket 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.

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 ist secret. Zum Beispiel könnten Sie sie in eine .env Datei im Stammverzeichnis Ihres Projekts einfügen.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Stellen Sie sicher, dass Sie den geheimen read/write API-Schlüssel niemals in Client-seitigen Produktionsumgebungen weitergeben.

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

module.exports = tacoTranslate;

Wir werden TACOTRANSLATE_API_KEY in Kürze automatisch definieren.

Die Erstellung des Clients in einer separaten Datei erleichtert die spätere Wiederverwendung. Nun fügen wir mit einer eigenen /pages/_app.tsx den TacoTranslate Provider hinzu.

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

Wenn Sie bereits benutzerdefinierte pageProps und _app.tsx haben, erweitern Sie bitte die Definition um die oben genannten Eigenschaften und den Code.

Schritt 4: Implementierung des Server-Side Renderings

TacoTranslate ermöglicht die serverseitige Darstellung Ihrer Übersetzungen. Dies verbessert die Benutzererfahrung erheblich, da sofort übersetzte Inhalte angezeigt werden, anstatt zuerst einen kurzen Blick auf nicht übersetzte Inhalte zu werfen. Außerdem können wir Netzwerk-Anfragen auf der Client-Seite vermeiden, da wir bereits alle benötigten Übersetzungen vorliegen haben.

Wir beginnen damit, /next.config.js zu erstellen oder zu bearbeiten.

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

Passen Sie die isProduction Überprüfung an Ihre 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.

Bis jetzt haben wir die Next.js-Anwendung nur mit einer Liste unterstützter Sprachen eingerichtet. Als Nächstes werden wir Übersetzungen für alle Ihre Seiten abrufen. Dazu verwenden Sie entweder getTacoTranslateStaticProps oder getTacoTranslateServerSideProps, je nach Ihren Anforderungen.

Diese Funktionen nehmen drei Argumente: Ein Next.js Static Props Context Objekt, die Konfiguration für TacoTranslate und optionale Next.js-Eigenschaften. Beachten Sie, dass revalidate bei getTacoTranslateStaticProps standardmäßig auf 60 gesetzt ist, damit Ihre Übersetzungen stets aktuell bleiben.

Um eine der Funktionen auf einer Seite zu verwenden, nehmen wir an, Sie haben eine Seiten-Datei wie /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!"/>;
}

Sie sollten nun in der Lage sein, die Translate Komponente zu verwenden, um Zeichenketten innerhalb all Ihrer React-Komponenten zu übersetzen.

import {Translate} from 'tacotranslate/react';

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

Schritt 5: Bereitstellen und testen!

Wir sind fertig! Ihre Next.js-Anwendung wird nun automatisch übersetzt, wenn Sie Zeichenketten zu einem Translate Komponent hinzufügen. Beachten Sie, dass nur Umgebungen mit read/write Berechtigungen auf dem API-Schlüssel neue Zeichenketten erstellen können, die übersetzt werden sollen. Wir empfehlen eine geschlossene und gesicherte Staging-Umgebung, in der Sie Ihre Produktionsanwendung mit einem solchen API-Schlüssel testen und vor dem Live-Gang neue Zeichenketten hinzufügen können. 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.

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 App 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!