Getting Started internationalizing (i18n) with Intlayer and Next.js 15 App Router

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 lässt sich nahtlos in das neueste Next.js 15 Framework integrieren, einschließlich seines leistungsstarken App Routers. Es ist optimiert zur Nutzung mit Server Components für effizientes Rendering und ist vollständig kompatibel mit Turbopack.

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 clientseitigen und serverseitigen Komponenten.
• TypScript-Unterstützung sicherstellen mit automatisch generierten Typen, die die Autovervollständigung und Fehlersuche verbessern.
• Von fortschrittlichen Funktionen profitieren, wie dynamische Sprachenerkennung und -wechsel.

Intlayer ist kompatibel mit Next.js 12, 13, 14 und 15. Wenn Sie den Next.js Page Router verwenden, können Sie auf diesen Leitfaden verweisen. Für Next.js 12, 13, 14 mit App Router, verweisen Sie 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 das 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. Darüber hinaus 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: Ihr 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 Sprachen    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

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

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

Konfigurieren Sie Ihr Next.js-Setup zur Verwendung von Intlayer:

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 gewährleistet den Aufbau von Inhaltsdeklarationsdateien 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 stellt die Kompatibilität mit Serverkomponenten sicher.

Schritt 4: Middleware zur Sprachenerkennung 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. Darüber hinaus ermöglicht sie das Speichern der bevorzugten Sprache des Benutzers in einem Cookie.

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 leere Haltelement RootLayout ermöglicht es, die Attribute lang und dir im <html> Tag festzulegen.

Um dynamische Routen zu implementieren, geben Sie den Pfad für die Sprache an, indem Sie ein neues Layout im Verzeichnis [locale] hinzufügen:

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

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

Implementieren Sie dann die Funktion generateStaticParams in Ihrem Layout.

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

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

Schritt 6: Deklarieren Sie Ihren Inhalt

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, solange sie in das Verzeichnis contentDir (standardmäßig ./src) aufgenommen werden. Und das Matchen der Dateierweiterung für die Inhaltsdeklaration (standardmäßig .content.{ts,tsx,js,jsx,mjs,cjs}). Weitere Informationen finden Sie in der Dokumentation zur Inhaltsdeklaration.

Schritt 7: Nutzen Sie Inhalte in Ihrem Code

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

import type { FC } from "react";import { ClientComponentExample } from "@components/ClientComponentExample";import { ServerComponentExample } from "@components/ServerComponentExample";import { type NextPageIntlayer, IntlayerClientProvider } from "next-intlayer";import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";const PageContent: FC = () => {  const { title, content } = useIntlayer("page");  return (    <>      <p>{content.getStarted.main}</p>      <code>{content.getStarted.pageLink}</code>    </>  );};const Page: NextPageIntlayer = async ({ params }) => {  const { locale } = await params;  return (    <>      <IntlayerServerProvider locale={locale}>        <PageContent />        <ServerComponentExample />        <IntlayerClientProvider locale={locale}>          <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 im Layout zu platzieren, da Next.js Layout-Code zwischen Seiten teilt, was es effizienter macht. Durch die Verwendung von IntlayerClientProvider im Layout vermeiden Sie die Wiederinitialisierung für jede Seite, was die Leistung verbessert und einen konsistenten Lokalisierungs-Kontext in Ihrer Anwendung aufrechterhält.

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

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

"use client";import type { FC } from "react";import { useIntlayer } from "next-intlayer";export 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";export 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 verwenden möchten, wie z.B. alt, title, href, aria-label, usw., müssen Sie den Wert der Funktion so aufrufen:

jsx

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

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

(Optional) Schritt 8: Internationalisierung Ihrer Metadaten

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

import {  type IConfigLocales,  getTranslationContent,  getMultilingualUrls,} from "intlayer";import type { Metadata } from "next";import type { LocalPromiseParams } from "next-intlayer";export const generateMetadata = async ({  params: { locale },}: LocalPromiseParams): Metadata => {  const { locale } = await params;  const t = <T>(content: IConfigLocales<T>) =>    getTranslationContent(content, locale);  /**   * Generiert ein Objekt mit allen URLs für jede Sprache.   *   * 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 getMultilingualUrls Funktion verwenden, die von Intlayer bereitgestellt wird. 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 Optimierung der Sitemap 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 Sie die Sprache Ihrer Inhalte

Um die Sprache Ihrer Inhalte zu ändern, können Sie die Funktion setLocale verwenden, die von dem useLocale Hook bereitgestellt wird. Diese Funktion ermöglicht es Ihnen, die Sprache der Anwendung festzulegen und die Inhalte entsprechend zu aktualisieren.

"use client";import type { FC } from "react";import {  Locales,  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,} from "intlayer";import { useLocale } from "next-intlayer";import Link from "next/link";export const LocaleSwitcher: FC = () => {  const { locale, pathWithoutLocale, availableLocales, setLocale } =    useLocale();  return (    <ol>      {availableLocales.map((localeItem) => (        <li key={localeItem}>          <Link            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. Französisch */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Sprache in der aktuellen Sprache - z.B. Spanisch, wenn die aktuelle Sprache auf Locales.SPANISH gesetzt ist */}              {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>          </Link>        </li>      ))}    </ol>  );};

Dokumentationsreferenzen:

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

TypeScript konfigurieren

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

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

{  // ... Ihre bestehenden TypeScript-Konfigurationen  "include": [    // ... Ihre bestehenden TypeScript-Konfigurationen    "types", // Fügen Sie die automatisch generierten Typen hinzu  ],}

Git-Konfiguration

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

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

# Ignoriere die von Intlayer generierten Dateien.intlayer