Erste Schritte mit der Internationalisierung (i18n) mit Intlayer und Next.js 14 mit App Router

Was ist Intlayer?

Intlayer ist eine innovative, Open-Source-Internationalisierungsbibliothek (i18n), die entwickelt wurde, um die Unterstützung mehrerer Sprachen in modernen Webanwendungen zu vereinfachen. Intlayer integriert sich nahtlos in das neueste Next.js 14-Framework, einschließlich seines leistungsstarken App Routers. Es ist optimiert für die Arbeit mit Serverkomponenten für effizientes Rendering und vollständig kompatibel mit Turbopack (ab Next.js >= 15).

Mit Intlayer können Sie:

• Übersetzungen einfach verwalten mit deklarativen Wörterbüchern auf Komponentenebene.
• Metadaten, Routen und Inhalte dynamisch lokalisieren.
• Übersetzungen sowohl in clientseitigen als auch in serverseitigen Komponenten nutzen.
• 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 Page Router verwenden, können Sie diese Anleitung konsultieren. Für Next.js 15 mit oder ohne Turbopack, siehe diese Anleitung.

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

Schritt 1: Abhängigkeiten installieren

Installieren Sie die erforderlichen Pakete mit npm:

npm install intlayer next-intlayer

• intlayer

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

• next-intlayer

  Das Paket, das Intlayer mit Next.js integriert. Es bietet Kontextanbieter und Hooks für die Internationalisierung in Next.js. 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, Verwaltung von Cookies und URL-Weiterleitung.

Schritt 2: Projekt konfigurieren

Erstellen Sie eine Konfigurationsdatei, um die Sprachen Ihrer Anwendung zu konfigurieren:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Ihre weiteren Sprachen    ],    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, das Deaktivieren von Intlayer-Protokollen in der Konsole und mehr einrichten. Eine vollständige Liste der verfügbaren Parameter finden Sie in der Konfigurationsdokumentation.

Schritt 3: Intlayer in Ihrer Next.js-Konfiguration integrieren

Konfigurieren Sie Ihre Next.js-Einstellungen, um Intlayer zu verwenden:

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

Das withIntlayer() Next.js-Plugin wird verwendet, um Intlayer mit Next.js zu integrieren. Es stellt sicher, dass Inhaltsdeklarationsdateien erstellt und im Entwicklungsmodus überwacht werden. Es definiert Intlayer-Umgebungsvariablen innerhalb der Webpack- oder Turbopack-Umgebungen. Zusätzlich bietet es Aliase zur Leistungsoptimierung und stellt die Kompatibilität mit Serverkomponenten sicher.

Schritt 4: Middleware für die Spracherkennung konfigurieren

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

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

Die intlayerMiddleware wird verwendet, um die bevorzugte Sprache des Benutzers zu erkennen und ihn zur entsprechenden URL weiterzuleiten, wie in der Konfiguration angegeben. Zusätzlich ermöglicht sie das Speichern der bevorzugten Sprache des Benutzers in einem Cookie.

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

Schritt 5: Dynamische Sprachrouten definieren

Entfernen Sie alles aus RootLayout und ersetzen Sie es durch den folgenden Code:

import type { PropsWithChildren, FC } from "react";import "./globals.css";const RootLayout: FC<PropsWithChildren> = ({ children }) => children;export default RootLayout;

Das RootLayout-Komponente leer zu halten, ermöglicht es, die lang- und dir-Attribute für das <html>-Tag festzulegen.

Um dynamisches Routing zu implementieren, geben Sie den Pfad für die Sprache an, indem Sie ein neues Layout in Ihrem [locale]-Verzeichnis hinzufügen:

import type { Next14LayoutIntlayer } from "next-intlayer";import { Inter } from "next/font/google";import { getHTMLTextDir } from "intlayer";const inter = Inter({ subsets: ["latin"] });const LocaleLayout: Next14LayoutIntlayer = ({  children,  params: { locale },}) => (  <html lang={locale} dir={getHTMLTextDir(locale)}>    <body className={inter.className}>{children}</body>  </html>);export default LocaleLayout;

Das [locale]-Pfadsegment wird verwendet, um die Sprache zu definieren. Beispiel: /en-US/about bezieht sich auf en-US und /fr/about auf fr.

Dann implementieren Sie die Funktion generateStaticParams in Ihrem Anwendungs-Layout.

export { generateStaticParams } from "next-intlayer"; // Zeile einfügenconst LocaleLayout: Next14LayoutIntlayer = ({  children,  params: { locale },}) => {  /*... Rest des Codes*/};export default LocaleLayout;

generateStaticParams stellt sicher, dass Ihre Anwendung die erforderlichen Seiten für alle Sprachen vorab erstellt, wodurch die Laufzeitberechnung reduziert und die Benutzererfahrung verbessert wird. Weitere Details finden Sie in der Next.js-Dokumentation zu generateStaticParams.

Schritt 6: Inhalte deklarieren

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

import { t, type Dictionary } from "intlayer";const pageContent = {  key: "page",  content: {    getStarted: {      main: t({        en: "Get started by editing",        fr: "Commencez par éditer",        es: "Comience por editar",      }),      pageLink: "src/app/page.tsx",    },  },} satisfies Dictionary;export default pageContent;

Ihre Inhaltsdeklarationen können überall in Ihrer Anwendung definiert werden, solange sie im contentDir-Verzeichnis enthalten sind (standardmäßig ./src). Und die Inhaltsdeklarationsdateierweiterung übereinstimmt (standardmäßig .content.{ts,tsx,js,jsx,mjs,cjs}). Weitere Details finden Sie in der Inhaltsdeklarationsdokumentation.

Schritt 7: Inhalte in Ihrem Code verwenden

Greifen Sie in Ihrer gesamten Anwendung auf Ihre Inhaltswörterbücher zu:

import { ClientComponentExample } from "@components/ClientComponentExample";import { ServerComponentExample } from "@components/ServerComponentExample";import { type Next14PageIntlayer, IntlayerClientProvider } from "next-intlayer";import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";const Page: Next14PageIntlayer = ({ params: { locale } }) => {  const content = useIntlayer("page", locale);  return (    <>      <p>        {content.getStarted.main}        <code>{content.getStarted.pageLink}</code>      </p>      <IntlayerServerProvider locale={locale}>        <IntlayerClientProvider locale={locale}>          <ServerComponentExample />          <ClientComponentExample />        </IntlayerClientProvider>      </IntlayerServerProvider>    </>  );};export default Page;

• IntlayerClientProvider wird verwendet, um die Sprache für clientseitige Komponenten bereitzustellen. Es kann in jeder übergeordneten Komponente platziert werden, einschließlich des Layouts. Es wird jedoch empfohlen, es in einem Layout zu platzieren, da Next.js Layout-Code zwischen Seiten teilt, was effizienter ist. Durch die Verwendung von IntlayerClientProvider im Layout vermeiden Sie, dass es für jede Seite neu initialisiert wird, was die Leistung verbessert und einen konsistenten Lokalisierungskontext in Ihrer gesamten Anwendung gewährleistet.

• IntlayerServerProvider wird verwendet, um die Sprache für die serverseitigen Kinder bereitzustellen. Es kann nicht im Layout gesetzt werden.

  Layout und Seite können keinen gemeinsamen Serverkontext teilen, da das Serversystem auf einem pro-Anfrage-Datenspeicher basiert (über den React-Cache-Mechanismus), wodurch jeder „Kontext“ für verschiedene Segmente der Anwendung neu erstellt wird. Das Platzieren des Providers in einem gemeinsamen Layout würde diese Isolation aufheben und verhindern, dass die richtigen Serverkontextwerte an Ihre Serverkomponenten weitergegeben werden.

"use client";import type { FC } from "react";import { useIntlayer } from "next-intlayer";const ClientComponentExample: FC = () => {  const content = useIntlayer("client-component-example"); // Erstellen Sie die zugehörige Inhaltsdeklaration  return (    <div>      <h2>{content.title} </h2>      <p>{content.content}</p>    </div>  );};

import type { FC } from "react";import { useIntlayer } from "next-intlayer/server";const ServerComponentExample: FC = () => {  const content = useIntlayer("server-component-example"); // Erstellen Sie die zugehörige Inhaltsdeklaration  return (    <div>      <h2>{content.title} </h2>      <p>{content.content}</p>    </div>  );};

Wenn Sie Ihre Inhalte in einem string-Attribut wie alt, title, href, aria-label usw. verwenden möchten, müssen Sie den Wert der Funktion aufrufen, wie:

jsx

<img src={content.image.src.value} alt={content.image.value} />

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

(Optional) Schritt 8: Internationalisierung Ihrer Metadaten

Falls Sie Ihre Metadaten wie den Titel Ihrer Seite internationalisieren möchten, können Sie die von Next.js bereitgestellte Funktion generateMetadata verwenden. Innerhalb der Funktion können Sie die Funktion getTranslation verwenden, um Ihre Metadaten zu übersetzen.

import {  type IConfigLocales,  getTranslation,  getMultilingualUrls,} from "intlayer";import type { Metadata } from "next";import type { LocalParams } from "next-intlayer";export const generateMetadata = ({  params: { locale },}: LocalParams): Metadata => {  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);  /**   * Generiert ein Objekt, das alle URLs für jede Sprache enthält.   *   * Beispiel:   * ```ts   *  getMultilingualUrls('/about');   *   *  // Gibt zurück   *  // {   *  //   en: '/about',   *  //   fr: '/fr/about',   *  //   es: '/es/about',   *  // }   * ```   */  const multilingualUrls = getMultilingualUrls("/");  return {    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",    }),    alternates: {      canonical: "/",      languages: { ...multilingualUrls, "x-default": "/" },    },    openGraph: {      url: multilingualUrls[locale],    },  };};// ... Rest des Codes

Erfahren Sie mehr über die Metadatenoptimierung in der offiziellen Next.js-Dokumentation.

(Optional) Schritt 9: Internationalisierung Ihrer sitemap.xml und robots.txt

Um Ihre sitemap.xml und robots.txt zu internationalisieren, können Sie die von Intlayer bereitgestellte Funktion getMultilingualUrls verwenden. Mit dieser Funktion können Sie mehrsprachige URLs für Ihre Sitemap generieren.

import { getMultilingualUrls } from "intlayer";import type { MetadataRoute } from "next";const sitemap = (): MetadataRoute.Sitemap => [  {    url: "https://example.com",    alternates: {      languages: getMultilingualUrls("https://example.com"),    },  },  {    url: "https://example.com/login",    alternates: {      languages: getMultilingualUrls("https://example.com/login"),    },  },  {    url: "https://example.com/register",    alternates: {      languages: getMultilingualUrls("https://example.com/register"),    },  },];export default sitemap;

import type { MetadataRoute } from "next";import { getMultilingualUrls } from "intlayer";const getAllMultilingualUrls = (urls: string[]) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);const robots = (): MetadataRoute.Robots => ({  rules: {    userAgent: "*",    allow: ["/"],    disallow: getAllMultilingualUrls(["/login", "/register"]),  },  host: "https://example.com",  sitemap: `https://example.com/sitemap.xml`,});export default robots;

Erfahren Sie mehr über die Sitemap-Optimierung in der offiziellen Next.js-Dokumentation. Erfahren Sie mehr über die Optimierung der robots.txt in der offiziellen Next.js-Dokumentation.

(Optional) Schritt 10: Ändern der Sprache Ihrer Inhalte

Um die Sprache Ihrer Inhalte zu ändern, können Sie die von der useLocale-Hook bereitgestellte Funktion setLocale verwenden. Mit dieser Funktion können Sie die Sprache der Anwendung festlegen und die Inhalte entsprechend aktualisieren.

"use client";import {  Locales,  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,} from "intlayer";import { useLocale } from "next-intlayer";import { type FC } from "react";import Link from "next/link";const LocaleSwitcher: FC = () => {  const { locale, pathWithoutLocale, availableLocales, setLocale } =    useLocale();  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={(e) => {              e.preventDefault();              setLocale(localeItem);            }}          >            <span>              {/* Sprache - z. B. FR */}              {localeItem}            </span>            <span>              {/* Sprache in ihrer eigenen Sprache - z. B. Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Sprache in der aktuellen Sprache - z. B. Francés mit aktueller Sprache 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>  );};

Dokumentationsreferenzen:

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

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

Um sicherzustellen, dass die Navigation Ihrer Anwendung die aktuelle Sprache berücksichtigt, können Sie eine benutzerdefinierte Link-Komponente erstellen. Diese Komponente fügt internen URLs automatisch die aktuelle Sprache voran. Zum Beispiel wird ein französischsprachiger Benutzer beim Klicken auf einen Link zur Seite "Über uns" 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 von URLs und macht Ihren Code einfacher zu warten und zu erweitern, wenn Ihre Anwendung wächst.

Nachfolgend finden Sie 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 überprü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 Sprache anpasst. * Für interne Links verwendet sie `getLocalizedUrl`, um die URL mit der Sprache zu versehen (z. B. /fr/about). * Dies stellt sicher, dass die Navigation innerhalb des gleichen Sprachkontexts 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 ein gültiges href angegeben ist, holen Sie die lokalisierte URL.  const hrefI18n: NextLinkProps["href"] =    href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;  return (    <NextLink href={hrefI18n} ref={ref} {...props}>      {children}    </NextLink>  );});Link.displayName = "Link";

Wie es funktioniert

• Erkennung externer Links:
  Die Hilfsfunktion checkIsExternalLink bestimmt, ob eine URL extern ist. Externe Links bleiben unverändert, da sie keine Lokalisierung benötigen.

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

• Lokalisierung der URL:
  Für interne Links (d. h. nicht extern) wird getLocalizedUrl verwendet, um die URL automatisch mit der aktuellen Sprache zu versehen. Das bedeutet, dass beim Benutzer in Französisch /about als href übergeben wird, was in /fr/about umgewandelt wird.

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

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

TypeScript konfigurieren

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

Stellen Sie sicher, dass Ihre TypeScript-Konfiguration die automatisch generierten Typen enthält.

{  // ... Ihre bestehenden TypeScript-Konfigurationen  "include": [    // ... Ihre bestehenden TypeScript-Konfigurationen    ".intlayer/**/*.ts", // Schließen Sie die automatisch generierten Typen ein  ],}

Git-Konfiguration

Es wird empfohlen, die von Intlayer generierten Dateien zu ignorieren. Dadurch vermeiden Sie, dass diese in Ihr Git-Repository aufgenommen werden.

Fügen Sie dazu die folgenden Anweisungen in Ihre .gitignore-Datei ein:

# Ignorieren Sie die von Intlayer generierten Dateien.intlayer

Weiterführende Schritte

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