Next.js-Internationalisierung: Vollständiger i18n-Leitfaden mit next-intl

Über 75 % der Internetnutzer bevorzugen das Surfen in ihrer Muttersprache, und Unternehmen, die lokalisieren, verzeichnen 70 % höhere Konversionsraten in nicht-englischen Märkten. Next.js bietet in Kombination mit next-intl ein robustes Internationalisierungs-Framework, das Routing, Übersetzungen, Formatierung und SEO über eine beliebige Anzahl von Standorten hinweg verwaltet.

Wichtige Erkenntnisse

– next-intl lässt sich nahtlos in Next.js App Router und Serverkomponenten integrieren – Das Routing mit lokalem Präfix sorgt dafür, dass englische URLs sauber bleiben, während Präfixe für andere Sprachen hinzugefügt werden – Serverkomponenten laden Übersetzungen ohne clientseitigen JavaScript-Bundle-Overhead

• Richtige Hreflang-Tags und mehrsprachige Sitemaps sind für internationales SEO unerlässlich

---

Projekt-Setup

Installieren Sie next-intl und organisieren Sie Ihr Projekt mit einem i18n-Verzeichnis, das Routing.ts, Navigation.ts und Request.ts enthält. Platzieren Sie Ihre App unter [locale] im App Router. Speichern Sie JSON-Übersetzungsdateien in einem Nachrichtenverzeichnis im Projektstammverzeichnis.

Routing-Konfiguration

Definieren Sie das Routing mit defineRouting() und geben Sie dabei Ihr Locales-Array, Ihr Standard-Locale und Ihre Locale-Präfix-Strategie an. Bei der „nach Bedarf“-Strategie wird das Präfix für das Standardgebietsschema (Englisch) weggelassen, während für andere die Präfixe /es/, /fr/, /ar/ hinzugefügt werden.

Erstellen Sie Navigations-Wrapper mit createNavigation(routing), um länderspezifische Link-, useRouter-, usePathname- und Umleitungsfunktionen zu erhalten. Verwenden Sie diese anstelle der nativen Navigation von Next.j in Ihrer gesamten App.

Middleware-Setup

Erstellen Sie in Next.js 16 eine Proxy.ts-Datei (die das ältere Middleware.ts-Muster ersetzt). Exportieren Sie eine von createMiddleware(routing) erstellte Proxy-Funktion. Konfigurieren Sie den Matcher so, dass er API-Routen, statische Dateien und _next-Pfade ausschließt.

---

Übersetzungsdateien

JSON-Struktur (verschachtelt, nicht flach)

Verwenden Sie verschachtelte Schlüssel, die nach Namespace organisiert sind. Verwenden Sie niemals flache, durch Punkte getrennte Schlüssel wie „home.title“ – sie beeinträchtigen die Auflösung des Next-Intl-Namespace. Strukturübersetzungen als:

• allgemein: Gemeinsame Begriffe (Schaltflächen, Beschriftungen, Ladezustände)
• nav: Navigationselemente
• home: Inhalt der Startseite
• about: Über den Seiteninhalt
• admin.common: Gemeinsame Admin-Bedingungen
• admin.products: Produktverwaltungsseite

Serverkomponenten

Verwenden Sie getTranslations("namespace") in asynchronen Serverkomponenten. Dadurch werden Übersetzungen ohne Auswirkungen auf das Client-Bundle auf den Server geladen. Rufen Sie t("key") für String-Übersetzungen und t.rich("key", {bold: (chunks) => ... }) für Rich Text auf.

Client-Komponenten

Verwenden Sie den Hook „useTranslations(“namespace“) in Client-Komponenten, die mit „use client“ gekennzeichnet sind. Der Hook stellt die gleiche t()-Funktion bereit. Nur die Übersetzungen für den aktiven Namespace sind im Client-Bundle enthalten.

---

RTL-Unterstützung (von rechts nach links).

Legen Sie für Arabisch, Hebräisch, Urdu und andere RTL-Sprachen dir="rtl" für das HTML-Element basierend auf dem aktuellen Gebietsschema fest. Überprüfen Sie im Gebietsschema-Layout, ob sich das Gebietsschema in Ihrem rtlLocales-Array befindet, und legen Sie die Richtung entsprechend fest.

Verwenden Sie die logischen CSS-Eigenschaften von Tailwind (ps, pe, ms, me anstelle von pl, pr, ml, mr) für Layouts, die automatisch im RTL-Modus umgedreht werden. Laden Sie geeignete Schriftarten für RTL-Skripte (z. B. Noto Sans Arabic für Arabisch und Urdu).

---

SEO: Metadaten und Hreflang

Dynamische Metadaten

Jede Seite muss „generateMetadata()“ (niemals statische Export-Const-Metadaten) für länderspezifische Titel, Beschreibungen und Hreflang-Alternativen verwenden. Erstellen Sie ein Alternates.Languages-Objekt, das jedes Gebietsschema seinem URL-Pfad zuordnet, sowie einen x-default-Eintrag, der auf die englische Version verweist.

Mehrsprachige Sitemap

Generieren Sie Sitemap-Einträge für jede Seite in jedem Gebietsschema. Jeder Eintrag sollte „alternates.Languages“ enthalten, das alle Gebietsschemavarianten zuordnet. Dies ermöglicht es Suchmaschinen, in jedem Markt die richtige Sprachversion bereitzustellen.

Content-Language-Meta-Tag

Legen Sie das Content-Language-Meta-Tag in Ihrem Gebietsschema-Layout fest, um Suchmaschinen und KI-Crawlern dabei zu helfen, die Seitensprache zu identifizieren. Dies ist besonders wichtig für Bing und neue KI-Suchmaschinen.

---

Übersetzungsworkflow

1. Bearbeiten Sie en.json als einzige Quelle der Wahrheit für alle übersetzbaren Zeichenfolgen
2. Übersetzungsskript ausführen, um neue Schlüssel an alle Gebietsschemadateien weiterzugeben (mithilfe der Google Translate API oder DeepL für erste Entwürfe)
3. Überprüfen Sie Übersetzungen mit Muttersprachlern auf Qualität und kulturelle Angemessenheit
4. **Testen Sie RTL-Sprachen gründlich – überprüfen Sie das Umdrehen des Layouts, die Textausrichtung und die Formulareingaben
5. Überprüfen Sie SEO mit Hreflang-Validierungstools und der internationalen Ausrichtung der Google Search Console

Umgang mit großen Übersetzungsdateien

Organisieren Sie JSON-Dateien für Anwendungen mit mehr als 5.000 Übersetzungsschlüsseln nach Namespace, um die Wartbarkeit zu verbessern. next-intl lädt nur die für die aktuelle Seite benötigten Namespaces und sorgt so für eine optimale Leistung.

---

Leistungsüberlegungen

• Server-Rendering: Übersetzungen werden auf dem Server geladen. Es wird keine JSON-Übersetzung an den Client gesendet, es sei denn, die Komponente ist eine Clientkomponente.
• Namespace-Aufteilung: Pro Seite werden nur aktive Namespaces geladen, nicht die gesamte Übersetzungsdatei.
• Statische Generierung: Seiten, die getTranslations() verwenden, können zur Erstellungszeit für alle Gebietsschemas statisch generiert werden.
• Bundle-Größe: Client-Komponenten enthalten nur ihre Namespace-Übersetzungen. Eine Seite, die useTranslations("home") verwendet, liefert nur den Namespace „home“.

---

Häufige Fallstricke

1. Flachschlüssel: Die Verwendung von „home.title“ als Schlüssel anstelle von verschachteltem \\\\\\\\{ „home“: { „title“: „…“ \\\\\\\\} } unterbricht die Namespace-Auflösung
2. Fehlende Übersetzungen: Stellen Sie immer ein Fallback-Verhalten bereit – next-intl zeigt den Schlüsselnamen an, wenn eine Übersetzung fehlt, aber für Benutzer sieht dies fehlerhaft aus
3. Hartcodierte Zeichenfolgen: Überprüfen Sie Ihre Codebasis auf Zeichenfolgen außerhalb des Übersetzungssystems
4. Datums-/Zahlenformatierung: Verwenden Sie next-intl-Formatierer anstelle von toLocaleDateString() für ein konsistentes Verhalten
5. Statische Metadaten: Die Verwendung von „export const metadata“ anstelle von „generateMetadata()“ verhindert länderspezifische Titel und Beschreibungen

---

Häufig gestellte Fragen

F: Wie viele Gebietsschemata kann next-intl verarbeiten?

Es gibt keine praktische Grenze. Anwendungen mit mehr als 11 Gebietsschemata und mehr als 7.000 Übersetzungsschlüsseln laufen ohne Leistungsprobleme. Serverseitiges Rendering bedeutet, dass Übersetzungen die Client-Bundles nicht aufblähen.

F: Beeinflusst i18n die Seitenladeleistung?

Bei Serverkomponenten erfolgt das Laden der Übersetzung auf dem Server. Die Auswirkungen auf die Leistung sind vernachlässigbar. Clientkomponenten enthalten nur ihre Namespace-Übersetzungen, normalerweise einige KB.

F: Wie gehen wir mit dynamischen Datenbankinhalten in mehreren Sprachen um?

Statischer UI-Text verwendet JSON-Dateien. Datenbankinhalte (Blogbeiträge, Produktbeschreibungen) erfordern das Speichern von Übersetzungen in speziellen Spalten oder Tabellen oder die Verwendung eines CMS mit integriertem Übersetzungsworkflow. Einige Teams verwenden einen Hybrid: JSON für die Benutzeroberfläche, Datenbank für Inhalte.

F: Was ist mit der Zahlen- und Datumsformatierung?

next-intl bietet useFormatter() für die länderspezifische Formatierung von Zahlen, Währungen, Datumsangaben und relativen Zeiten. Die gesamte Formatierung folgt dem Intl-Standard und berücksichtigt automatisch die Gebietsschemakonventionen.

---

Was kommt als nächstes?

Internationalisierung ist eine Investition, die sich in jedem nicht-englischen Markt auszahlt. Beginnen Sie mit Ihren Regionen mit dem höchsten Wert und erweitern Sie von dort aus.

Contact ECOSIRE for i18n implementation help, or explore our Odoo implementation services for multilingual ERP deployment.

---

Herausgegeben von ECOSIRE – unterstützt Unternehmen bei der Skalierung mit Unternehmenssoftwarelösungen.