So laden Sie Übersetzungen aus Dateien in Next.js (Pages Router) v16

Problem

Das direkte Hardcodieren von benutzerseitigen Strings in Komponenten erzeugt eine enge Kopplung zwischen Inhalt und Code. Jedes Mal, wenn sich der Text ändert, müssen Entwickler die Implementierungsdateien finden und ändern. Die Unterstützung für eine zweite Sprache erfordert das Auffinden jedes hardcodierten Strings und dessen Einbettung in bedingte Logik. Eine dritte Sprache erweitert diese Logik weiter. Dieser Ansatz macht Übersetzungs-Workflows abhängig von Code-Deployments und verhindert, dass nicht-technische Teammitglieder Inhalte unabhängig aktualisieren können.

Mit dem Wachstum der Anwendung wird die Verwaltung von Übersetzungen zunehmend schwieriger. Über Dutzende von Komponenten verstreute Strings sind schwer zu prüfen, zu duplizieren oder konsistent zu aktualisieren. Übersetzer können nicht parallel mit Entwicklern arbeiten, da sie Zugriff auf die Codebasis selbst benötigen.

Lösung

Speichern Sie alle benutzerseitigen Texte in externen Ressourcendateien, organisiert nach Sprache, mit einer JSON-Datei pro Locale. Jede Nachricht wird durch einen eindeutigen Schlüssel identifiziert und nicht durch ihren wörtlichen Text. Komponenten referenzieren diese Schlüssel anstelle von hardcodierten Strings.

Laden Sie die entsprechende Übersetzungsdatei basierend auf der von Next.js empfangenen Locale und übergeben Sie die Nachrichten an den Provider von react-intl. Die Anwendung kann dann Sprachen wechseln, indem sie eine andere Datei lädt, ohne den Komponenten-Code zu ändern. Dies entkoppelt Inhalt von der Implementierung und ermöglicht es Übersetzern, in Standard-JSON-Dateien zu arbeiten, während Entwickler auf stabile Nachrichtenschlüssel verweisen.

Schritte

1. Erstellen Sie Übersetzungsdateien, organisiert nach Locale

Legen Sie Übersetzungsnachrichten in JSON-Dateien ab, getrennt nach Locale. Jede Datei enthält Schlüssel-Wert-Paare, wobei Schlüssel stabile Identifikatoren sind und Werte die übersetzten Strings für diese Sprache sind.

{
"welcome": "Welcome back",
"greeting": "Hello, {name}",
"itemCount": "You have {count, plural, one {# item} other {# items}}"
}

Erstellen Sie eine Datei pro unterstützter Locale (zum Beispiel messages/en.json, messages/es.json, messages/fr.json) in einem messages-Verzeichnis im Projektstamm. Verwenden Sie dieselben Schlüssel in allen Dateien, damit react-intl die korrekte Übersetzung für die aktive Locale nachschlagen kann.

2. Nachrichten in getStaticProps laden

Lesen Sie die Übersetzungsdatei basierend auf der Locale, die von Next.js in getStaticProps empfangen wird. Dadurch wird sichergestellt, dass Nachrichten serverseitig verfügbar sind und als Props an die Seite übergeben werden.

import { GetStaticProps } from "next";

export const getStaticProps: GetStaticProps = async (context) => {
  const locale = context.locale || "en";
  const messages = (await import(`../messages/${locale}.json`)).default;

  return {
    props: {
      messages,
    },
  };
};

Der dynamische Import lädt nur die Datei für die aktuelle Locale. Next.js stellt den locale-Wert automatisch basierend auf der URL oder den Benutzerpräferenzen bereit.

3. Nachrichten an IntlProvider in _app übergeben

Umschließen Sie Ihre Root-Komponente mit IntlProvider und konfigurieren Sie ihn mit der aktuellen Locale des Benutzers und den entsprechenden übersetzten Nachrichten. Greifen Sie auf die Nachrichten über pageProps zu, damit jede Seite ihre eigenen Übersetzungen bereitstellen kann.

import { AppProps } from "next/app";
import { IntlProvider } from "react-intl";
import { useRouter } from "next/router";

export default function App({ Component, pageProps }: AppProps) {
  const { locale, defaultLocale } = useRouter();

  return (
    <IntlProvider
      locale={locale || "en"}
      defaultLocale={defaultLocale || "en"}
      messages={pageProps.messages}
    >
      <Component {...pageProps} />
    </IntlProvider>
  );
}

Der Provider stellt die Nachrichten allen Komponenten im Baum zur Verfügung. Jede Seite lädt ihre eigene Nachrichtendatei über getStaticProps, und _app empfängt diese Nachrichten über pageProps.

4. Nachrichten nach Schlüssel in Komponenten referenzieren

Verwenden Sie die FormattedMessage-Komponente oder den useIntl-Hook von react-intl, um übersetzten Text anzuzeigen. Referenzieren Sie Nachrichten über ihren Schlüssel, anstatt Strings fest zu codieren.

import { FormattedMessage, useIntl } from "react-intl";

export default function HomePage() {
  const intl = useIntl();
  const userName = "Alice";

  return (
    <div>
      <h1>
        <FormattedMessage id="welcome" />
      </h1>
      <p>
        <FormattedMessage id="greeting" values={{ name: userName }} />
      </p>
      <input placeholder={intl.formatMessage({ id: "searchPlaceholder" })} />
    </div>
  );
}

React-intl schlägt die übersetzte Nachricht unter der angegebenen ID nach und formatiert sie. Wenn eine Übersetzung fehlt, wird auf den defaultMessage zurückgegriffen, falls angegeben. Variablen, die im values-Prop übergeben werden, werden in den Nachrichtenstring interpoliert.