Getting Started internationalizing (i18n) with Intlayer und Next.js 14 mit App Router

Was ist Intlayer?

Intlayer ist eine innovative, Open-Source-Bibliothek zur Internationalisierung (i18n), die entwickelt wurde, um die mehrsprachige Unterstützung in modernen Webanwendungen zu vereinfachen. Intlayer integriert sich nahtlos mit dem neuesten Next.js 14 Framework, einschließlich seines leistungsstarken App Routers. Es ist optimiert für die Arbeit mit Server Components für effizientes Rendern und vollständig kompatibel mit Turbopack (von Next.js >= 15).

Mit Intlayer können Sie:

• Übersetzungen einfach verwalten mithilfe deklarativer Wörterbücher auf Komponentenebene.
• Dynamisch Metadaten, Routen und Inhalte lokalisieren.
• Zugriff auf Übersetzungen in sowohl clientseitigen als auch serverseitigen Komponenten.
• TypeScript-Unterstützung sicherstellen mit automatisierten Typen, die die Autovervollständigung und Fehlersuche verbessern.
• Von erweiterten Funktionen profitieren, wie dynamischer Lokalisierungserkennung und -wechsel.

Intlayer ist kompatibel mit Next.js 12, 13, 14 und 15. Wenn Sie den Next.js Page Router verwenden, können Sie sich auf diesen Leitfaden beziehen. Für Next.js 15 mit oder ohne Turbopack, beziehen Sie sich auf diesen Leitfaden.

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 Werkzeuge zur Internationalisierung für die Konfigurationsverwaltung, Übersetzung, Inhaltsdeklaration, Transpilation und CLI-Befehle bereitstellt.

• next-intlayer

  Das Paket, das Intlayer mit Next.js integriert. Es stellt Kontextanbieter und Hooks für die Next.js-Internationalisierung bereit. Darüber hinaus enthält es das Next.js-Plugin zur Integration von Intlayer mit Webpack oder Turbopack, sowie Middleware zum Erkennen der bevorzugten Spracheinstellungen des Benutzers, zum Verwalten von Cookies und zum Handhaben von URL-Umleitungen.

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 anderen Lokalisierungen    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

Durch diese Konfigurationsdatei können Sie lokalisierte URLs, Middleware-Umleitungen, Cookie-Namen, den Speicherort und die Erweiterung Ihrer Inhaltsdeklarationen festlegen, Intlayer-Protokolle in der Konsole deaktivieren und mehr. Für eine vollständige Liste verfügbarer Parameter siehe die Konfigurationsdokumentation.

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

Konfigurieren Sie Ihr Next.js-Setup, 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 Inhalteerklärungsdateien erstellt werden und überwacht sie im Entwicklungsmodus. Es definiert Intlayer-Umgebungsvariablen innerhalb der Webpack oder Turbopack Umgebungen. Darüber hinaus bietet es Aliase zur Optimierung der Leistung und gewährleistet die Kompatibilität mit Serverkomponenten.

Schritt 4: Middleware zur Lokalisierungserkennung konfigurieren

Richten Sie Middleware ein, um die bevorzugte Spracheinstellung 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 Spracheinstellung des Benutzers zu erkennen und ihn zur entsprechenden URL weiterzuleiten, wie in der Konfiguration angegeben. Zusätzlich ermöglicht sie das Speichern der bevorzugten Spracheinstellung des Benutzers in einem Cookie.

Passen Sie den matcher-Parameter an, um die Routen Ihrer Anwendung abzugleichen. Für weitere Informationen siehe die Next.js-Dokumentation zur Konfiguration des Matchers.

Schritt 5: Dynamische Lokalerouten 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;

Durch das Leeren der RootLayout-Komponente können die lang und dir Attribute im <html> Tag festgelegt werden.

Um dynamisches Routing zu implementieren, geben Sie den Pfad für die Lokalisierung 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;

Der [locale]-Pfadsegment wird verwendet, um die Lokalisierung zu definieren. Beispiel: /en-US/about wird auf en-US verweisen und /fr/about auf fr.

Implementieren Sie dann die Funktion generateStaticParams in Ihrem Anwendungs-Layout.

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

generateStaticParams sorgt dafür, dass Ihre Anwendung die erforderlichen Seiten für alle Lokalisierungen vorab erstellt, um die Laufzeitberechnung zu minimieren und das Benutzererlebnis zu verbessern. Für weitere Details siehe die Next.js-Dokumentation zu generateStaticParams.

Schritt 6: Ihren Inhalt deklarieren

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

import { t, type DeclarationContent } 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 DeclarationContent;export default pageContent;

Ihre Inhaltsdeklarationen können überall in Ihrer Anwendung definiert werden, sofern sie in das contentDir-Verzeichnis (standardmäßig ./src) eingeschlossen sind. Außerdem muss die Erweiterung der Inhaltsdeklarationsdatei übereinstimmen (standardmäßig .content.{ts,tsx,js,jsx,mjs,cjs}). Für weitere Details siehe die Dokumentation zur Inhaltsdeklaration.

Schritt 7: Inhalt in Ihrem Code verwenden

Greifen Sie auf Ihre Inhaltswörterbücher in Ihrer gesamten Anwendung 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 Lokalisierung an clientseitige Komponenten bereitzustellen. Es kann in jeder übergeordneten Komponente platziert werden, einschließlich des Layouts. Es wird jedoch empfohlen, es in einem Layout zu verwenden, da Next.js Layoutcode über Seiten hinweg teilt, was es effizienter macht. Wenn Sie IntlayerClientProvider im Layout verwenden, vermeiden Sie eine erneute Initialisierung für jede Seite, was die Leistung verbessert und einen konsistenten Lokalisierungskontext in Ihrer Anwendung beibehält.

• IntlayerServerProvider wird verwendet, um die Lokalisierung an serverseitige Kinder bereitzustellen. Es kann nicht im Layout festgelegt werden.

  Layout und Seite können keinen gemeinsamen Serverkontext teilen, da das System für den Serverkontext auf einem pro-Anfrage-Datenlager (über den Cache von React-Mechanismus) basiert, wodurch jeder „Kontext“ für verschiedene Segmente der Anwendung neu erstellt wird. Das Platzieren des Providers in einem gemeinsamen Layout würde diese Isolation aufbrechen und die korrekte Weitergabe der Werte des Serverkontexts an Ihre Serverkomponenten verhindern.

"use client";import type { FC } from "react";import { useIntlayer } from "next-intlayer";const ClientComponentExample: FC = () => {  const content = useIntlayer("client-component-example"); // Verwandte Inhaltsdeklaration erstellen  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"); // Verwandte Inhaltsdeklaration erstellen  return (    <div>      <h2>{content.title} </h2>      <p>{content.content}</p>    </div>  );};

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

jsx

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

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

(Optional) Schritt 8: Internationalisierung Ihrer Metadaten

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

import {  type IConfigLocales,  getTranslationContent,  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>) =>    getTranslationContent(content, locale);  /**   * Generiert ein Objekt, das alle URLs für jede Lokalisierung 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 Optimierung der Metadaten 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. Diese Funktion ermöglicht es Ihnen, mehrsprachige URLs für Ihre Sitemap zu 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 Optimierung der Sitemap in der offiziellen Next.js-Dokumentation. Erfahren Sie mehr über die Optimierung von robots.txt in der offiziellen Next.js-Dokumentation.

(Optional) Schritt 10: Ändern der Sprache Ihres Inhalts

Um die Sprache Ihres Inhalts zu ändern, können Sie die von dem Hook useLocale bereitgestellte Funktion setLocale verwenden. Diese Funktion ermöglicht es Ihnen, die Sprache der Anwendung festzulegen und den Inhalt entsprechend zu aktualisieren.

"use client";import {  Locales,  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,} from "intlayer";import { useLocale } from "next-intlayer";import { type FC } from "react";const LocaleSwitcher: FC = () => {  const { locale, pathWithoutLocale, availableLocales, setLocale } =    useLocale();  return (    <ol>      {availableLocales.map((localeItem) => (        <li key={localeItem}>          <a            href={getLocalizedUrl(pathWithoutLocale, localeItem)}            hrefLang={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={(e) => {              e.preventDefault();              setLocale(localeItem);            }}          >            <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 Spracheinstellung auf Locales.SPANISH */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Sprache auf Englisch - z.B. Französisch */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>            <span>              {/* Sprache in ihrer eigenen Sprache - z.B. FR */}              {localeItem}            </span>          </a>        </li>      ))}    </ol>  );};

Dokumentationsreferenzen:

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

TypeScript konfigurieren

Intlayer verwendet Modulergänzung, um die Vorteile von TypeScript zu nutzen und Ihren Code zu stärken.

Stellen Sie sicher, dass Ihre TypeScript-Konfiguration die automatisch generierten Typen umfasst.

{  // ... Ihre vorhandenen TypeScript-Konfigurationen  "include": [    // ... Ihre vorhandenen TypeScript-Konfigurationen    "types", // Die automatisch generierten Typen einbeziehen  ],}

Git-Konfiguration

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

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

# Ignoriere die von Intlayer generierten Dateien.intlayer