Erste Schritte mit der Internationalisierung (i18n) mit Intlayer und Next.js 15 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 15-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.
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 dynamische 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 diesen Leitfaden konsultieren. Für Next.js 12, 13, 14 mit App Router, siehe 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-intlayerintlayer
Das Kernpaket, das Internationalisierungstools 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;Durch diese Konfigurationsdatei können Sie lokalisierte URLs, Middleware-Weiterleitungen, Cookie-Namen, den Speicherort und die Erweiterung Ihrer Inhaltsdeklarationen festlegen, Intlayer-Protokolle in der Konsole deaktivieren und mehr. Für eine vollständige Liste der verfügbaren Parameter lesen Sie die Konfigurationsdokumentation.
Schritt 3: Intlayer in Ihre Next.js-Konfiguration integrieren
Konfigurieren Sie Ihr Next.js-Setup, um Intlayer zu verwenden:
import type { NextConfig } from "next";import { withIntlayer } from "next-intlayer/server";const nextConfig: NextConfig = { /* Konfigurationsoptionen hier */};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. Darüber hinaus bietet es Aliase zur Leistungsoptimierung und stellt die Kompatibilität mit Serverkomponenten sicher.
Schritt 4: 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 Halten der RootLayout-Komponente leer ermöglicht das Setzen der lang- und dir-Attribute für das <html>-Tag.
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 { 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;Das [locale]-Pfadsegment wird verwendet, um die Sprache zu definieren. Beispiel: /en-US/about bezieht sich auf en-US und /fr/about auf fr.
Implementieren Sie dann die Funktion generateStaticParams in Ihrem Anwendungs-Layout.
export { generateStaticParams } from "next-intlayer"; // Zeile einfügenconst LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => { /*... Restlicher Code*/};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 5: 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 (standardmäßig ./src) enthalten sind und mit der Inhaltsdeklarationsdateierweiterung übereinstimmen (standardmäßig .content.{ts,tsx,js,jsx,mjs,cjs}). Weitere Details finden Sie in der Inhaltsdeklarationsdokumentation.
Schritt 6: Inhalte in Ihrem Code verwenden
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 an clientseitige Komponenten zu übergeben. Es kann in jeder übergeordneten Komponente, einschließlich des Layouts, platziert werden. Es wird jedoch empfohlen, es in einem Layout zu platzieren, da Next.js Layout-Code über Seiten hinweg 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 an die serverseitigen Kinder zu übergeben. Es kann nicht im Layout platziert 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 brechen und verhindern, dass die korrekten Werte des Serverkontexts an Ihre Serverkomponenten weitergegeben werden.
"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 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 7: 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 auf die entsprechende URL weiterzuleiten, wie in der Konfiguration angegeben. Darüber hinaus ermöglicht sie das Speichern der bevorzugten Sprache des Benutzers in einem Cookie.
(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 verwenden Sie die Funktion getTranslation, um Ihre Metadaten zu übersetzen.
import { type IConfigLocales, getTranslation, getMultilingualUrls,} from "intlayer";import type { Metadata } from "next";import type { LocalPromiseParams } from "next-intlayer";export const generateMetadata = async ({ params,}: LocalPromiseParams): Promise<Metadata> => { const { locale } = await params; 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], }, };};// ... Restlicher CodeErfahren 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. 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 Sitemap-Optimierung in der offiziellen Next.js-Dokumentation. Erfahren Sie mehr über die robots.txt-Optimierung in der offiziellen Next.js-Dokumentation.
(Optional) Schritt 10: Die Sprache Ihrer Inhalte ändern
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 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 ( <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:
(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, sodass z. B. ein französischsprachiger Benutzer, der auf einen Link zur Seite „Über uns“ klickt, zu /fr/about statt zu /about weitergeleitet wird.
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 wartbar und erweiterbar, 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 type { PropsWithChildren, FC } from "react";/** * Hilfsfunktion, um zu überprüfen, ob eine angegebene 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 wird `getLocalizedUrl` verwendet, um die URL mit der Sprache zu präfixieren (z. B. /fr/about). * Dies stellt sicher, dass die Navigation innerhalb des gleichen Sprachkontexts bleibt. */export const Link: FC<PropsWithChildren<NextLinkProps>> = ({ href, children, ...props}) => { 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} {...props}> {children} </NextLink> );};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 präfixieren. Das bedeutet, dass bei einem Benutzer, der Französisch verwendet, das Übergeben von /about als href 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 gewährleisten Sie eine kohärente und sprachbewusste Benutzererfahrung und profitieren gleichzeitig von verbesserter SEO und Benutzerfreundlichkeit.
TypeScript konfigurieren
Intlayer verwendet Modulerweiterungen, um die Vorteile von TypeScript zu nutzen und Ihre Codebasis 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", // Einschließen der automatisch generierten Typen ],}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 zu Ihrer .gitignore-Datei hinzu:
# Ignorieren der von Intlayer generierten Dateien.intlayerWeiterführende Schritte
Um weiterzugehen, können Sie den visuellen Editor implementieren oder Ihre Inhalte mit dem CMS auslagern.
Wenn Sie eine Idee haben, um diese Dokumentation zu verbessern, zögern Sie bitte nicht, durch das Einreichen eines Pull-Requests auf GitHub beizutragen.
GitHub-Link zur Dokumentation