Getting Started Internationalizing (i18n) with Intlayer and Next.js using Page Router
Was ist Intlayer?
Intlayer ist eine innovative, Open-Source-Bibliothek für Internationalisierung (i18n), die darauf ausgelegt ist, die Unterstützung mehrerer Sprachen in modernen Webanwendungen zu vereinfachen. Intlayer integriert sich nahtlos mit dem neuesten Next.js-Framework, einschließlich dessen traditionellem Page Router.
Mit Intlayer können Sie:
- Übersetzungen einfach verwalten mithilfe deklarativer Wörterbücher auf Komponentenebene.
- Dynamisch Metadaten, Routen und Inhalte lokalisieren.
- TypeScript-Unterstützung sicherstellen mit automatisch generierten Typen, die die Autovervollständigung und Fehlererkennung verbessern.
- Von erweiterten Funktionen profitieren, wie dynamischer Spracherkennung und Sprachenwechsel.
Intlayer ist kompatibel mit Next.js 12, 13, 14 und 15. Wenn Sie den Next.js App Router verwenden, beachten Sie 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 erforderlichen Pakete mit Ihrem bevorzugten Paketmanager:
npm install intlayer next-intlayer
intlayer
Das Kernpaket, das Tools zur Internationalisierung für Konfigurationsmanagement, Übersetzung, Inhaltserklärung, Transpilation 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. Außerdem 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 von Ihrer Anwendung unterstützten Sprachen festzulegen:
import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = { internationalization: { locales: [ Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH, // Fügen Sie hier Ihre weiteren Sprachen 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 Inhaltserklärungen, die Deaktivierung der Intlayer-Protokolle in der Konsole und vieles mehr festlegen. Eine vollständige Liste der verfügbaren Parameter finden Sie in der Konfigurationsdokumentation.
Schritt 3: Intlayer mit der Next.js-Konfiguration integrieren
Ändern Sie Ihre Next.js-Konfiguration, um Intlayer zu integrieren:
import { withIntlayer } from "next-intlayer/server";/** @type {import('next').NextConfig} */const nextConfig = { // Ihre vorhandene Next.js-Konfiguration};export default withIntlayer(nextConfig);
Das withIntlayer() Next.js-Plugin wird verwendet, um Intlayer mit Next.js zu integrieren. Es sorgt dafür, dass Dateien für Inhaltserklärungen generiert werden und überwacht diese im Entwicklungsmodus. Es definiert Intlayer-Umgebungsvariablen innerhalb der Webpack oder Turbopack Umgebungen. Außerdem bietet es Aliase zur Optimierung der Leistung und gewährleistet die Kompatibilität mit Serverkomponenten.
Schritt 4: Middleware zur Spracherkennung konfigurieren
Richten Sie Middleware ein, um die bevorzugte Sprache des Benutzers automatisch zu erkennen und zu behandeln:
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 matcher-Parameter an, um die Routen Ihrer Anwendung anzupassen. Weitere Informationen finden Sie in der Next.js-Dokumentation zur Konfiguration des Matchers.
Schritt 5: Dynamische Sprachrouten definieren
Implementieren Sie die dynamische Routenführung, um lokalisierte Inhalte basierend auf der Sprache des Benutzers bereitzustellen.
Erstellen Sie sprachspezifische Seiten:
Benennen Sie Ihre Hauptseiten-Datei um, um das dynamische Segment [locale] einzuschließen.
bashmv src/pages/index.tsx src/pages/[locale]/index.tsx
Aktualisieren Sie _app.tsx, um die Lokalisierung zu behandeln:
Ändern Sie Ihr _app.tsx, um Intlayer-Anbieter einzuschließen.
src/pages/_app.tsximport 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;
Richten Sie getStaticPaths und getStaticProps ein:
Definieren Sie in Ihrer [locale]/index.tsx die Pfade und Props zur Handhabung verschiedener Sprachen.
src/pages/[locale]/index.tsximport 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 erforderlichen Seiten für alle Sprachen im Next.js Page Router vorab generiert. Dieser Ansatz reduziert die Rechenleistung zur Laufzeit und führt zu einem verbesserten Nutzererlebnis. Für weitere Details, beachten Sie die Next.js-Dokumentation zu getStaticPaths und getStaticProps.
Schritt 6: Deklarieren Sie Ihren Inhalt
Erstellen und verwalten Sie Ihre Inhaltserklärungen zur Speicherung von Übersetzungen.
import { t, type Dictionary } from "intlayer";const homeContent = { key: "home", content: { title: t({ en: "Willkommen auf meiner Website", fr: "Bienvenue sur mon site Web", es: "Bienvenido a mi sitio web", }), description: t({ en: "Fangen Sie an, indem Sie diese Seite bearbeiten.", fr: "Commencez par éditer cette page.", es: "Comience por editar esta página.", }), },} satisfies Dictionary;export default homeContent;
Für weitere Informationen zur Deklaration von Inhalten, beachten Sie die Inhaltserklärungsanleitung.
Schritt 7: Inhalt in Ihrem Code nutzen
Greifen Sie auf Ihre Inhaltswörterbücher in der gesamten Anwendung zu, um übersetzte Inhalte anzuzeigen.
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;
import type { FC } from "react";import { useIntlayer } from "next-intlayer";export const ComponentExample: FC = () => { const content = useIntlayer("component-example"); // Stellen Sie sicher, dass Sie eine entsprechende Inhaltserklärung haben return ( <div> <h2>{content.title}</h2> <p>{content.content}</p> </div> );};
Beim Einsatz von Übersetzungen in string-Attributen (z. B. alt, title, href, aria-label) sollte der Wert der Funktion wie folgt aufgerufen werden:
jsx<img src={content.image.src.value} alt={content.image.value} />
Um mehr über den useIntlayer-Hook zu erfahren, beachten Sie die Dokumentation.
(Optional) Schritt 8: Internationalisieren Sie Ihre Metadaten
Um Metadaten wie Seitentitel und Beschreibungen zu internationalisieren, verwenden Sie die Funktion getStaticProps in Verbindung mit der Funktion getTranslation von Intlayer.
import { GetStaticPaths, GetStaticProps } from "next";import { type IConfigLocales, getTranslation, Locales } from "intlayer";import { useIntlayer } from "next-intlayer";interface HomePageProps { locale: string; metadata: Metadata;}const HomePage = ({ metadata }: HomePageProps) => { // Metadaten können im Kopf oder in anderen Komponenten verwendet werden return ( <div> <Head> <title>{metadata.title}</title> <meta name="description" content={metadata.description} /> </Head> {/* Zusätzliche Inhalte */} </div> );};export const getStaticProps: GetStaticProps = async ({ params }) => { const locale = params?.locale as string; const t = <T,>(content: IConfigLocales<T>) => getTranslation(content, locale); const metadata = { title: t({ en: "Meine Website", fr: "Mon Site Web", es: "Mi Sitio Web", }), description: t({ en: "Willkommen auf meiner Website.", fr: "Bienvenue sur mon site Web.", es: "Bienvenido a mi sitio web.", }), }; return { props: { locale, metadata, }, };};export default HomePage;// ... Rest des Codes einschließlich getStaticPaths
(Optional) Schritt 9: Ändern Sie die Sprache Ihres Inhalts
Um den Benutzern zu ermöglichen, die Sprachen dynamisch zu wechseln, verwenden Sie die Funktion setLocale, die vom useLocale-Hook bereitgestellt wird.
import { Locales, getHTMLTextDir, getLocaleName, getLocalizedUrl,} from "intlayer";import { useLocalePageRouter } from "next-intlayer";import { type FC } from "react";const LocaleSwitcher: FC = () => { const { locale, pathWithoutLocale, availableLocales, setLocale } = useLocalePageRouter(); 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 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> );};
Die useLocalePageRouter API entspricht der von useLocale. Um mehr über den useLocale-Hook zu erfahren, beachten Sie die Dokumentation.
Dokumentationsreferenzen:
Beispiel der Vorteile von TypeScript:
Git-Konfiguration
Um Ihr Repository sauber zu halten und die Einfügung generierter Dateien zu vermeiden, wird empfohlen, die von Intlayer erstellten Dateien zu ignorieren.
Fügen Sie die folgenden Zeilen zu Ihrer .gitignore-Datei hinzu:
# Ignoriere die von Intlayer generierten Dateien.intlayer
Zusätzliche Ressourcen
- Intlayer-Dokumentation: GitHub-Repository
- Inhaltserklärungsanleitung: Inhaltserklärung
- Konfigurationsdokumentation: Konfigurationsanleitung
Durch die Befolgung dieser Anleitung können Sie Intlayer erfolgreich in Ihre Next.js-Anwendung mit dem Page Router integrieren und eine robuste und skalierbare Internationalisierungsunterstützung für Ihre Webprojekte aktivieren.
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