Übersetzen Sie Ihre Next.js and Page Router mit Intlayer | Internationalisierung (i18n)

Was ist Intlayer?

Intlayer ist eine innovative, Open-Source-Internationalisierungsbibliothek (i18n), die entwickelt wurde, um die mehrsprachige Unterstützung in modernen Webanwendungen zu vereinfachen. Intlayer integriert sich nahtlos in das neueste Next.js-Framework, einschließlich seines traditionellen Page Routers.

Mit Intlayer können Sie:

• Übersetzungen einfach verwalten durch deklarative Wörterbücher auf Komponentenebene.
• Metadaten, Routen und Inhalte dynamisch lokalisieren.
• TypeScript-Unterstützung sicherstellen mit automatisch generierten Typen, die die Autovervollständigung und Fehlererkennung verbessern.
• Von erweiterten Funktionen profitieren, wie dynamischer Spracherkennung und -umschaltung.

Intlayer ist kompatibel mit Next.js 12, 13, 14 und 15. Wenn Sie den Next.js App Router verwenden, lesen Sie bitte die App Router Anleitung. Für Next.js 15 folgen Sie dieser Anleitung.

Schritt-für-Schritt-Anleitung zur Einrichtung von Intlayer in einer Next.js-Anwendung mit Page Router

Schritt 1: Abhängigkeiten installieren

Installieren Sie die notwendigen Pakete mit Ihrem bevorzugten Paketmanager:

npm install intlayer next-intlayernpx intlayer init

• intlayer

  Das Kernpaket, das Internationalisierungswerkzeuge für Konfigurationsmanagement, Übersetzung, Inhaltsdeklaration, Transpilierung und CLI-Befehle bereitstellt.

• next-intlayer

  Das Paket, das Intlayer mit Next.js integriert. Es stellt Kontextanbieter und Hooks für die Internationalisierung in Next.js bereit. Zusätzlich enthält es das Next.js-Plugin zur Integration von Intlayer mit Webpack oder Turbopack sowie Middleware zur Erkennung der bevorzugten Sprache des Benutzers, zur Verwaltung von Cookies und zur Handhabung von URL-Weiterleitungen.

Schritt 2: Konfigurieren Sie Ihr Projekt

Erstellen Sie eine Konfigurationsdatei, um die von Ihrer Anwendung unterstützten Sprachen zu definieren:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Fügen Sie hier Ihre weiteren Sprachversionen hinzu
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Über diese Konfigurationsdatei können Sie lokalisierte URLs, Middleware-Weiterleitungen, Cookie-Namen, den Speicherort und die Erweiterung Ihrer Inhaltsdeklarationen einrichten, Intlayer-Logs in der Konsole deaktivieren und vieles mehr. Für eine vollständige Liste der verfügbaren Parameter siehe die Konfigurationsdokumentation.

Schritt 3: Integrieren Sie Intlayer in die Next.js-Konfiguration

Ändern Sie Ihre Next.js-Konfiguration, um Intlayer zu integrieren:

import { withIntlayer } from "next-intlayer/server";/** @type {import('next').NextConfig} */const nextConfig = {  // Ihre bestehende Next.js-Konfiguration};export default withIntlayer(nextConfig);

Das withIntlayer() Next.js-Plugin wird verwendet, um Intlayer mit Next.js zu integrieren. Es sorgt für den Aufbau der Inhaltsdeklarationsdateien und überwacht diese im Entwicklungsmodus. Es definiert Intlayer-Umgebungsvariablen innerhalb der Webpack oder Turbopack-Umgebungen. Zusätzlich stellt es Aliase bereit, um die Leistung zu optimieren, und gewährleistet die Kompatibilität mit Server-Komponenten.

Schritt 4: Middleware für die Lokalerkennung konfigurieren

Richten Sie Middleware ein, um die bevorzugte Sprache des Benutzers automatisch zu erkennen und zu verarbeiten:

export { intlayerProxy as middleware } from "next-intlayer/middleware";

export const config = {
  matcher:
    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
};

Passen Sie den Parameter matcher an, um die Routen Ihrer Anwendung abzudecken. Weitere Details finden Sie in der Next.js-Dokumentation zur Konfiguration des Matchers.

Schritt 5: Definieren Sie dynamische Locale-Routen

Implementieren Sie dynamisches Routing, um lokalisierte Inhalte basierend auf der Locale des Benutzers bereitzustellen.

1. Erstellen Sie locale-spezifische Seiten:

   Benennen Sie Ihre Hauptseiten-Datei um, um das dynamische Segment [locale] einzuschließen.

   bash

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   mv src/pages/index.tsx src/pages/[locale]/index.tsx

2. Aktualisieren Sie _app.tsx, um die Lokalisierung zu unterstützen:

   Ändern Sie Ihre _app.tsx, um Intlayer-Provider einzubinden.

   src/pages/_app.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import type { FC } from "react";import type { AppProps } from "next/app";import { IntlayerClientProvider } from "next-intlayer";const App = FC<AppProps>({ Component, pageProps }) => {  const { locale } = pageProps;  return (    <IntlayerClientProvider locale={locale}>      <Component {...pageProps} />    </IntlayerClientProvider>  );}export default MyApp;

3. Einrichten von getStaticPaths und getStaticProps:

   Definieren Sie in Ihrer [locale]/index.tsx die Pfade und Props, um verschiedene Sprachen zu unterstützen.

   src/pages/[locale]/index.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import type { FC } from "react";import type { GetStaticPaths, GetStaticProps } from "next";import { type Locales, getConfiguration } from "intlayer";const HomePage: FC = () => <div>{/* Ihr Inhalt hier */}</div>;export const getStaticPaths: GetStaticPaths = () => {  const { internationalization } = getConfiguration();  const { locales } = internationalization;  const paths = locales.map((locale) => ({    params: { locale },  }));  return { paths, fallback: false };};export const getStaticProps: GetStaticProps = ({ params }) => {  const locale = params?.locale as string;  return {    props: {      locale,    },  };};export default HomePage;

getStaticPaths und getStaticProps stellen sicher, dass Ihre Anwendung die notwendigen Seiten für alle Sprachen im Next.js Page Router vorab erstellt. Dieser Ansatz reduziert die Laufzeitberechnung und führt zu einer verbesserten Benutzererfahrung. Für weitere Details lesen Sie bitte die Next.js-Dokumentation zu getStaticPaths und getStaticProps.

Schritt 6: Deklarieren Sie Ihre Inhalte

Erstellen und verwalten Sie Ihre Inhaltsdeklarationen, um Übersetzungen zu speichern.

import { t, type Dictionary } from "intlayer";

const homeContent = {
  key: "home",
  content: {
    title: t({
      de: "Willkommen auf meiner Webseite",
      en: "Welcome to My Website",
      fr: "Bienvenue sur mon site Web",
      es: "Bienvenido a mi sitio web",
    }),
    description: t({
      de: "Beginnen Sie, indem Sie diese Seite bearbeiten.",
      en: "Get started by editing this page.",
      fr: "Commencez par éditer cette page.",
      es: "Comience por editar esta página.",
    }),
  },
} satisfies Dictionary;

export default homeContent;

Für weitere Informationen zur Inhaltsdeklaration siehe die Anleitung zur Inhaltsdeklaration.

Schritt 7: Inhalte in Ihrem Code verwenden

Greifen Sie in Ihrer gesamten Anwendung auf Ihre Inhaltswörterbücher zu, um übersetzte Inhalte anzuzeigen.

import type { FC } from "react";
import { useIntlayer } from "next-intlayer";
import { ComponentExample } from "@components/ComponentExample";

const HomePage: FC = () => {
  const content = useIntlayer("home");

  return (
    <div>
      <h1>{content.title}</h1>
      <p>{content.description}</p>
      <ComponentExample />
      {/* Zusätzliche Komponenten */}
    </div>
  );
};

// ... Rest des Codes, einschließlich getStaticPaths und getStaticProps

export default HomePage;

Wenn Sie Übersetzungen in string-Attributen verwenden (z. B. alt, title, href, aria-label), rufen Sie

den Wert der Funktion wie folgt auf:

html

Inhalt kopieren

Code kopieren

Kopieren Sie den Code in die Zwischenablage

<img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

Um mehr über den useIntlayer Hook zu erfahren, lesen Sie die Dokumentation.

(Optional) Schritt 8: Internationalisierung Ihrer Metadaten

Falls Sie Ihre Metadaten, wie z.B. den Titel Ihrer Seite, internationalisieren möchten, können Sie die von Next.js Page Router bereitgestellte Funktion getStaticProps verwenden. Innerhalb dieser Funktion können Sie den Inhalt mit der Funktion getIntlayer abrufen, um Ihre Metadaten zu übersetzen.

import { type Dictionary, t } from "intlayer";
import { type Metadata } from "next";

const metadataContent = {
  key: "page-metadata",
  content: {
    title: t({
      en: "Create Next App",
      fr: "Créer une application Next.js",
      es: "Crear una aplicación Next.js",
    }),
    description: t({
      en: "Generated by create next app",
      fr: "Généré par create next app",
      es: "Generado por create next app",
    }),
  },
} satisfies Dictionary<Metadata>;

export default metadataContent;

import { GetStaticPaths, GetStaticProps } from "next";
import { getIntlayer, getMultilingualUrls } from "intlayer";
import { useIntlayer } from "next-intlayer";
import Head from "next/head";
import type { FC } from "react";

interface HomePageProps {
  locale: string;
  metadata: {
    title: string;
    description: string;
  };
  multilingualUrls: Record<string, string>;
}

const HomePage: FC<HomePageProps> = ({
  metadata,
  multilingualUrls,
  locale,
}) => {
  const content = useIntlayer("page");

  return (
    <div>
      <Head>
        <title>{metadata.title}</title>
        <meta name="description" content={metadata.description} />
        {/* Generiere hreflang-Tags für SEO */}
        {Object.entries(multilingualUrls).map(([lang, url]) => (
          <link key={lang} rel="alternate" hrefLang={lang} href={url} />
        ))}
        <link rel="canonical" href={multilingualUrls[locale]} />
      </Head>

      {/* Seiteninhalt */}
      <main>{/* Ihr Seiteninhalt hier */}</main>
    </div>
  );
};

export const getStaticProps: GetStaticProps<HomePageProps> = async ({
  params,
}) => {
  const locale = params?.locale as string;

  const metadata = getIntlayer("page-metadata", locale);

  /**
   * Generiert ein Objekt, das alle URLs für jede Locale enthält.
   *
   * Beispiel:
   * ```ts
   *  getMultilingualUrls('/about');
   *
   *  // Gibt zurück
   *  // {
   *  //   en: '/about',
   *  //   fr: '/fr/about',
   *  //   es: '/es/about',
   *  // }
   * ```
   */
  const multilingualUrls = getMultilingualUrls("/");

  return {
    props: {
      locale,
      metadata,
      multilingualUrls,
    },
  };
};

export default HomePage;

// ... Rest des Codes einschließlich getStaticPaths

Beachten Sie, dass die getIntlayer-Funktion, die aus next-intlayer importiert wird, Ihren Inhalt in einem IntlayerNode kapselt, was die Integration mit dem visuellen Editor ermöglicht. Im Gegensatz dazu gibt die aus intlayer importierte getIntlayer-Funktion Ihren Inhalt direkt ohne zusätzliche Eigenschaften zurück.

Alternativ können Sie die Funktion getTranslation verwenden, um Ihre Metadaten zu deklarieren. Es wird jedoch empfohlen, Inhaltsdeklarationsdateien zu verwenden, um die Übersetzung Ihrer Metadaten zu automatisieren und den Inhalt irgendwann zu externalisieren.

import { GetStaticPaths, GetStaticProps } from "next";
import {
  type IConfigLocales,
  getTranslation,
  getMultilingualUrls,
} from "intlayer";
import { useIntlayer } from "next-intlayer";
import Head from "next/head";
import type { FC } from "react";

interface HomePageProps {
  locale: string;
  metadata: {
    title: string;
    description: string;
  };
  multilingualUrls: Record<string, string>;
}

const HomePage: FC<HomePageProps> = ({ metadata, multilingualUrls, locale }) => {
  const content = useIntlayer("page");

  return (
    <div>
      <Head>
        <title>{metadata.title}</title>
        <meta name="description" content={metadata.description} />
        {/* Generiere hreflang-Tags für SEO */}
        {Object.entries(multilingualUrls).map(([lang, url]) => (
          <link
            key={lang}
            rel="alternate"
            hrefLang={lang}
            href={url}
          />
        ))}
        <link rel="canonical" href={multilingualUrls[locale]} />
      </Head>

      {/* Seiteninhalt */}
      <main>
        {/* Ihr Seiteninhalt hier */}
      </main>
    </div>
  );
};

export const getStaticProps: GetStaticProps<HomePageProps> = async ({
  params
}) => {
  const locale = params?.locale as string;
  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);

  const metadata = {
    title: t<string>({
      en: "My title",
      fr: "Mon titre",
      es: "Mi título",
    }),
    description: t({
      en: "My description",
      fr: "Ma description",
      es: "Mi descripción",
    }),
  };

  const multilingualUrls = getMultilingualUrls("/");

  return {
    props: {
      locale,
      metadata,
      multilingualUrls,
    },
  };
};

export default HomePage;

// ... Rest des Codes einschließlich getStaticPaths

Erfahren Sie mehr über die Optimierung von Metadaten in der offiziellen Next.js-Dokumentation.

(Optional) Schritt 9: Ändern Sie die Sprache Ihres Inhalts

Um die Sprache Ihres Inhalts in Next.js zu ändern, wird empfohlen, die Link-Komponente zu verwenden, um Benutzer zur entsprechenden lokalisierten Seite weiterzuleiten. Die Link-Komponente ermöglicht das Vorladen der Seite, was hilft, ein vollständiges Neuladen der Seite zu vermeiden.

import {
  Locales,
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
} from "intlayer";
import { useLocalePageRouter } from "next-intlayer";
import { type FC } from "react";
import Link from "next/link";

const LocaleSwitcher: FC = () => {
  const { locale, pathWithoutLocale, availableLocales } = useLocalePageRouter();

  return (
    <div>
      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
      <div id="localePopover" popover="auto">
        {availableLocales.map((localeItem) => (
          <Link
            href={getLocalizedUrl(pathWithoutLocale, localeItem)}
            hrefLang={localeItem}
            key={localeItem}
            aria-current={locale === localeItem ? "page" : undefined}
            onClick={() => setLocale(localeItem)}
          >
            <span>
              {/* Gebietsschema - z.B. FR */}
              {localeItem}
            </span>
            <span>
              {/* Sprache im eigenen Gebietsschema - z.B. Français */}
              {getLocaleName(localeItem, locale)}
            </span>
            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
              {/* Sprache in der aktuellen Locale - z.B. Francés mit aktueller Locale auf Locales.SPANISH gesetzt */}
              {getLocaleName(localeItem)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* Sprache auf Englisch - z.B. French */}
              {getLocaleName(localeItem, Locales.ENGLISH)}
            </span>
          </Link>
        ))}
      </div>
    </div>
  );
};

Eine alternative Möglichkeit ist die Verwendung der setLocale-Funktion, die vom useLocale-Hook bereitgestellt wird. Diese Funktion erlaubt kein Vorladen der Seite und lädt die Seite neu.

In diesem Fall wird ohne Weiterleitung mittels router.push nur Ihr serverseitiger Code die Sprache des Inhalts ändern.

"use client";import { useRouter } from "next/navigation";import { useLocale } from "next-intlayer";import { getLocalizedUrl } from "intlayer";// ... Rest des Codesconst router = useRouter();const { setLocale } = useLocale({  onLocaleChange: (locale) => {    router.push(getLocalizedUrl(pathWithoutLocale, locale));  },});return (  <button onClick={() => setLocale(Locales.FRENCH)}>    Wechsel zu Französisch  </button>);

Die useLocalePageRouter API ist dieselbe wie useLocale. Um mehr über den useLocale Hook zu erfahren, siehe die Dokumentation.

Dokumentationsverweise:

• getLocaleName Hook
• getLocalizedUrl Hook
• getHTMLTextDir Hook
• hrefLang Attribut
• lang Attribut
• dir Attribut
• aria-current Attribut

(Optional) Schritt 10: Erstellen einer lokalisierten Link-Komponente

Um sicherzustellen, dass die Navigation Ihrer Anwendung die aktuelle Locale berücksichtigt, können Sie eine benutzerdefinierte Link-Komponente erstellen. Diese Komponente fügt automatisch interne URLs mit der aktuellen Sprache als Präfix hinzu. Zum Beispiel wird ein französischsprachiger Benutzer, der auf einen Link zur "Über uns"-Seite klickt, zu /fr/about statt zu /about weitergeleitet.

Dieses Verhalten ist aus mehreren Gründen nützlich:

• SEO und Benutzererfahrung: Lokalisierte URLs helfen Suchmaschinen, sprachspezifische Seiten korrekt zu indexieren, und bieten Benutzern Inhalte in ihrer bevorzugten Sprache.
• Konsistenz: Durch die Verwendung eines lokalisierten Links in Ihrer gesamten Anwendung stellen Sie sicher, dass die Navigation innerhalb der aktuellen Sprache bleibt und unerwartete Sprachwechsel vermieden werden.
• Wartbarkeit: Die Zentralisierung der Lokalisierungslogik in einer einzigen Komponente vereinfacht die Verwaltung der URLs und macht Ihren Code leichter wartbar und erweiterbar, wenn Ihre Anwendung wächst.

Nachfolgend die Implementierung einer lokalisierten Link-Komponente in TypeScript:

"use client";

import { getLocalizedUrl } from "intlayer";
import NextLink, { type LinkProps as NextLinkProps } from "next/link";
import { useLocale } from "next-intlayer";
import { forwardRef, PropsWithChildren, type ForwardedRef } from "react";

/**
 * Hilfsfunktion, um zu prüfen, ob eine gegebene URL extern ist.
 * Wenn die URL mit http:// oder https:// beginnt, wird sie als extern betrachtet.
 */
export const checkIsExternalLink = (href?: string): boolean =>
  /^https?:\/\//.test(href ?? "");

/**
 * Eine benutzerdefinierte Link-Komponente, die das href-Attribut basierend auf der aktuellen Locale anpasst.
 * Für interne Links wird `getLocalizedUrl` verwendet, um die URL mit der Locale zu versehen (z.B. /fr/about).
 * Dies stellt sicher, dass die Navigation im gleichen Locale-Kontext bleibt.
 */
export const Link = forwardRef<
  HTMLAnchorElement,
  PropsWithChildren<NextLinkProps>
>(({ href, children, ...props }, ref: ForwardedRef<HTMLAnchorElement>) => {
  const { locale } = useLocale();
  const isExternalLink = checkIsExternalLink(href.toString());

  // Wenn der Link intern ist und eine gültige href vorhanden ist, wird die lokalisierte URL abgerufen.
  const hrefI18n: NextLinkProps["href"] =
    href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;

  return (
    <NextLink href={hrefI18n} ref={ref} {...props}>
      {children}
    </NextLink>
  );
});

Link.displayName = "Link";

Funktionsweise

• Erkennung externer Links:
  Die Hilfsfunktion checkIsExternalLink bestimmt, ob eine URL extern ist. Externe Links bleiben unverändert, da sie nicht lokalisiert werden müssen.

• Abrufen der aktuellen Locale:
  Der useLocale Hook liefert die aktuelle Locale (z. B. fr für Französisch).

• Lokalisierung der URL:
  Für interne Links (d. h. nicht-externe) wird getLocalizedUrl verwendet, um die URL automatisch mit der aktuellen Locale zu versehen. Das bedeutet, wenn Ihr Benutzer Französisch eingestellt hat, wird beim Übergeben von /about als href daraus /fr/about.

• Rückgabe des Links:
  Die Komponente gibt ein <a>-Element mit der lokalisierten URL zurück, wodurch sichergestellt wird, dass die Navigation konsistent mit der Locale erfolgt.

Durch die Integration dieser Link-Komponente in Ihre Anwendung gewährleisten Sie eine kohärente und sprachbewusste Benutzererfahrung und profitieren gleichzeitig von verbesserter SEO und Benutzerfreundlichkeit.

(Optional) Schritt 11: Optimieren Sie Ihre Bundle-Größe

Beim Einsatz von next-intlayer werden standardmäßig Wörterbücher in das Bundle jeder Seite aufgenommen. Um die Bundle-Größe zu optimieren, stellt Intlayer ein optionales SWC-Plugin bereit, das useIntlayer-Aufrufe mithilfe von Makros intelligent ersetzt. Dadurch werden Wörterbücher nur in die Bundles der Seiten aufgenommen, die sie tatsächlich verwenden.

Um diese Optimierung zu aktivieren, installieren Sie das Paket @intlayer/swc. Nach der Installation erkennt next-intlayer das Plugin automatisch und verwendet es:

npm install @intlayer/swc --save-dev

Hinweis: Diese Optimierung ist nur für Next.js 13 und höher verfügbar.

Hinweis: Dieses Paket wird standardmäßig nicht installiert, da SWC-Plugins in Next.js noch experimentell sind. Dies kann sich in Zukunft ändern.

TypeScript konfigurieren

Intlayer verwendet Modulaugmentation, um die Vorteile von TypeScript zu nutzen und Ihren Code robuster zu machen.

Stellen Sie sicher, dass Ihre TypeScript-Konfiguration die automatisch generierten Typen einschließt.

{  // ... Ihre bestehenden TypeScript-Konfigurationen  "include": [    // ... Ihre bestehenden TypeScript-Konfigurationen    ".intlayer/**/*.ts", // Einschluss der automatisch generierten Typen  ],}

Git-Konfiguration

Um Ihr Repository sauber zu halten und zu vermeiden, dass generierte Dateien committet werden, wird empfohlen, von Intlayer erstellte Dateien zu ignorieren.

Fügen Sie die folgenden Zeilen zu Ihrer .gitignore-Datei hinzu:

# Ignoriere die von Intlayer generierten Dateien.intlayer

VS Code Erweiterung

Um Ihre Entwicklungserfahrung mit Intlayer zu verbessern, können Sie die offizielle Intlayer VS Code Erweiterung installieren.

Installation aus dem VS Code Marketplace

Diese Erweiterung bietet:

• Autovervollständigung für Übersetzungsschlüssel.
• Echtzeit-Fehlererkennung für fehlende Übersetzungen.
• Inline-Vorschauen des übersetzten Inhalts.
• Schnellaktionen, um Übersetzungen einfach zu erstellen und zu aktualisieren.

Für weitere Details zur Verwendung der Erweiterung siehe die Intlayer VS Code Extension Dokumentation.

Zusätzliche Ressourcen

• Intlayer Dokumentation: GitHub Repository
• Wörterbuch-Anleitung: Wörterbuch
• Konfigurationsdokumentation: Konfigurationsanleitung

Indem Sie dieser Anleitung folgen, können Sie Intlayer effektiv in Ihre Next.js-Anwendung mit dem Page Router integrieren und so eine robuste und skalierbare Internationalisierungsunterstützung für Ihre Webprojekte ermöglichen.

Weiterführende Schritte

Um weiterzugehen, können Sie den visuellen Editor implementieren oder Ihre Inhalte mithilfe des CMS auslagern.