Stellen Sie Ihre Frage und erhalten Sie einen Resümee des Dokuments, indem Sie diese Seite und den AI-Anbieter Ihrer Wahl referenzieren
Durch die Integration des Intlayer MCP-Servers in Ihren bevorzugten AI-Assistenten können Sie alle Dokumente direkt von ChatGPT, DeepSeek, Cursor, VSCode usw. abrufen.
Dokumentation des MCP-Servers ansehenDer Inhalt dieser Seite wurde mit einer KI übersetzt.
Den englischen Originaltext ansehenWenn 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 DokumentationMarkdown des Dokuments in die Zwischenablage kopieren
Erste Schritte zur Internationalisierung (i18n) mit Intlayer und Next.js unter Verwendung des Page Routers
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:
Kopieren Sie den Code in die Zwischenablage
npm install intlayer next-intlayer
intlayer
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:
Kopieren Sie den Code in die Zwischenablage
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:
Kopieren Sie den Code in die Zwischenablage
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:
Kopieren Sie den Code in die Zwischenablage
export { intlayerMiddleware 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.
Erstellen Sie locale-spezifische Seiten:
Benennen Sie Ihre Hauptseiten-Datei um, um das dynamische Segment [locale] einzuschließen.
bashCode kopierenKopieren Sie den Code in die Zwischenablage
mv src/pages/index.tsx src/pages/[locale]/index.tsx
Aktualisieren Sie _app.tsx, um die Lokalisierung zu unterstützen:
Ändern Sie Ihre _app.tsx, um Intlayer-Provider einzubinden.
src/pages/_app.tsxCode kopierenKopieren 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;
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.tsxCode kopierenKopieren 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.
Kopieren Sie den Code in die Zwischenablage
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.
Kopieren Sie den Code in die Zwischenablage
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 getStaticPropsexport 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:
jsxCode kopierenKopieren Sie den Code in die Zwischenablage
<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 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.
Kopieren Sie den Code in die Zwischenablage
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;
Kopieren Sie den Code in die Zwischenablage
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.
Kopieren Sie den Code in die Zwischenablage
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.
Kopieren Sie den Code in die Zwischenablage
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(); const { setLocaleCookie } = useLocaleCookie(); 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={() => setLocaleCookie(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.
Kopieren Sie den Code in die Zwischenablage
"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:
(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:
Kopieren Sie den Code in die Zwischenablage
"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:
Kopieren Sie den Code in die Zwischenablage
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.
Kopieren Sie den Code in die Zwischenablage
{ // ... 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:
Kopieren Sie den Code in die Zwischenablage
# 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.
Dokumentationshistorie
- 5.5.10 - 2025-06-29: Historie initialisiert