Übersetzen Sie Ihre Next.js 16-Website (ohne [locale] im Seitenpfad) mit Intlayer | Internationalisierung (i18n)

Siehe Application Template auf GitHub.

Inhaltsverzeichnis

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 lässt sich nahtlos in das aktuelle Next.js 16-Framework integrieren, einschließlich dessen leistungsstarkem App Router. Sie ist darauf optimiert, mit Server Components für effizientes Rendering zusammenzuarbeiten und ist vollständig kompatibel mit Turbopack.

Mit Intlayer können Sie:

• Übersetzungen einfach verwalten mithilfe deklarativer Dictionaries auf Komponentenebene.
• Metadaten, Routen und Inhalte dynamisch lokalisieren.
• Auf Übersetzungen sowohl in Client- als auch in Server-Komponenten zugreifen.
• TypeScript-Unterstützung sicherstellen mit automatisch generierten Typen, die Autocompletion und Fehlererkennung verbessern.
• Profitieren Sie von erweiterten Funktionen, wie dynamische Locale-Erkennung und -Wechsel.

Intlayer ist mit Next.js 12, 13, 14 und 16 kompatibel. Wenn Sie den Next.js Page Router verwenden, können Sie diesen Leitfaden zu Rate ziehen. Für Next.js 12, 13 und 14 mit App Router lesen Sie 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-intlayernpx intlayer init

• intlayer

  Das Kernpaket, das Internationalisierungswerkzeuge für Konfigurationsmanagement, Übersetzung, Inhaltsdeklaration, Transpilation und CLI-Befehle bereitstellt.

• next-intlayer

Das Paket, das Intlayer mit Next.js integriert. Es stellt Context-Provider und Hooks für die Internationalisierung mit Next.js bereit. Zusätzlich enthält es das Next.js-Plugin zur Integration von Intlayer mit Webpack oder Turbopack sowie einen Proxy zur Erkennung der bevorzugten Locale des Benutzers, zur Verwaltung von Cookies und zur Behandlung von URL-Weiterleitungen.

Schritt 2: Konfigurieren Sie Ihr Projekt

Hier ist die endgültige Struktur, die wir erstellen werden:

.├── src│   ├── app│   │   ├── layout.tsx│   │   ├── page.content.ts│   │   └── page.tsx│   ├── components│   │   ├── clientComponentExample│   │   │   ├── client-component-example.content.ts│   │   │   └── ClientComponentExample.tsx│   │   ├── localeSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   └── serverComponentExample│   │       ├── server-component-example.content.ts│   │       └── ServerComponentExample.tsx│   └── proxy.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json

Wenn du kein locale routing möchtest, kann Intlayer als einfacher Provider / Hook verwendet werden. Siehe diese Anleitung für weitere Details.

Erstelle eine Konfigurationsdatei, um die Sprachen deiner Anwendung zu konfigurieren:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Weitere Locales    ],    defaultLocale: Locales.ENGLISH,  },  routing: {    mode: "search-params", // oder `no-prefix` - Nützlich für die Erkennung durch Middleware  },};export default config;

Über diese Konfigurationsdatei können Sie lokalisierte URLs, Proxy-Weiterleitungen, Cookie-Namen, den Speicherort und die Erweiterung Ihrer Inhaltsdeklarationen, das Deaktivieren der Intlayer-Logs in der Konsole und mehr festlegen. Für eine vollständige Liste der verfügbaren Parameter siehe die Konfigurationsdokumentation.

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

Konfigurieren Sie Ihr Next.js-Setup so, dass Intlayer verwendet wird:

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 dient zur Integration von Intlayer in Next.js. Es stellt den Aufbau der Content-Deklarationsdateien sicher und überwacht diese im Entwicklungsmodus. Es legt Intlayer-Umgebungsvariablen innerhalb der Webpack oder Turbopack-Umgebungen fest. Zusätzlich stellt es Aliase zur Optimierung der Performance bereit und gewährleistet die Kompatibilität mit Server-Komponenten.

Die Funktion withIntlayer() ist eine Promise-Funktion. Sie ermöglicht die Vorbereitung der Intlayer-Dictionaries, bevor der Build startet. Wenn Sie sie mit anderen Plugins verwenden möchten, können Sie sie awaiten. Beispiel:

const nextConfig = await withIntlayer(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

Wenn Sie es synchron verwenden möchten, können Sie die Funktion withIntlayerSync() verwenden. Beispiel:

const nextConfig = withIntlayerSync(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

Intlayer erkennt automatisch, ob Ihr Projekt webpack oder Turbopack verwendet, basierend auf den Kommandozeilen-Flags --webpack, --turbo oder --turbopack sowie Ihrer aktuellen Next.js-Version.

Ab next>=16, wenn Sie Rspack verwenden, müssen Sie Intlayer explizit zwingen, die webpack-Konfiguration zu verwenden, indem Sie Turbopack deaktivieren:

withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));

Schritt 4: Dynamische Locale-Routen definieren

Entfernen Sie alles aus RootLayout und ersetzen Sie es durch den folgenden Code:

import type { Metadata } from "next";import type { ReactNode } from "react";import "./globals.css";import { IntlayerClientProvider, LocalPromiseParams } from "next-intlayer";import { getHTMLTextDir, getIntlayer } from "intlayer";import { getLocale } from "next-intlayer/server";export { generateStaticParams } from "next-intlayer";export const generateMetadata = async ({  params,}: LocalPromiseParams): Promise<Metadata> => {  const { locale } = await params;  const { title, description, keywords } = getIntlayer("metadata", locale);  return {    title,    description,    keywords,  };};const RootLayout = async ({  children,}: Readonly<{  children: ReactNode;}>) => {  const locale = await getLocale();  return (    <html lang={locale} dir={getHTMLTextDir(locale)}>      <IntlayerClientProvider defaultLocale={locale}>        <body>{children}</body>      </IntlayerClientProvider>    </html>  );};export default RootLayout;

Schritt 5: Deklarieren Sie Ihre Inhalte

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

import { t, type Dictionary } from "intlayer";import { Metadata } from "next";const metadataContent = {  key: "metadata",  content: {    title: t({      de: "Titel meines Projekts",      en: "My Project Title",      fr: "Le Titre de mon Projet",      es: "El Título de mi Proyecto",    }),    description: t({      de: "Entdecken Sie unsere innovative Plattform, die darauf ausgelegt ist, Ihren Workflow zu optimieren und die Produktivität zu steigern.",      en: "Discover our innovative platform designed to streamline your workflow and boost productivity.",      fr: "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.",      es: "Descubra nuestra plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad.",    }),    keywords: t({      de: ["Innovation", "Produktivität", "Workflow", "SaaS"],      en: ["innovation", "productivity", "workflow", "SaaS"],      de: ["Innovation", "Produktivität", "Workflow", "SaaS"],      fr: ["innovation", "productivité", "flux de travail", "SaaS"],      es: ["innovación", "productividad", "flujo de trabajo", "SaaS"],    }),  },} as Dictionary<Metadata>;export default metadataContent;

import { t, type Dictionary } from "intlayer";/** @type {import('intlayer').Dictionary<import('next').Metadata>} */const metadataContent = {  key: "metadata",  content: {    title: t({      de: "Titel meines Projekts",      en: "My Project Title",      fr: "Le Titre de mon Projet",      es: "El Título de mi Proyecto",    }),    description: t({      de: "Entdecken Sie unsere innovative Plattform, die darauf ausgelegt ist, Ihren Workflow zu vereinfachen und Ihre Produktivität zu steigern.",      en: "Discover our innovative platform designed to streamline your workflow and boost productivity.",      de: "Entdecken Sie unsere innovative Plattform, die entwickelt wurde, um Ihren Workflow zu vereinfachen und Ihre Produktivität zu steigern.",      fr: "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.",      es: "Descubra nuestra plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad.",    }),    keywords: t({      de: ["innovation", "produktivität", "workflow", "SaaS"],      en: ["innovation", "productivity", "workflow", "SaaS"],      fr: ["innovation", "productivité", "flux de travail", "SaaS"],      es: ["innovación", "productividad", "flujo de trabajo", "SaaS"],    }),  },};export default metadataContent;

import { t, type Dictionary } from "intlayer";const pageContent = {  key: "page",  content: {    getStarted: {      main: t({        de: "Beginnen Sie mit der Bearbeitung",        en: "Get started by editing",        fr: "Commencez par éditer",        es: "Comience por editar",      }),      pageLink: "src/app/page.tsx",    },  },} satisfies Dictionary;export default pageContent;

Ihre Content-Deklarationen können überall in Ihrer Anwendung definiert werden, sobald sie in das Verzeichnis contentDir (standardmäßig ./src) aufgenommen sind. Sie müssen zudem der Dateiendung für Content-Deklarationsdateien entsprechen (standardmäßig .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

Weitere Informationen finden Sie in der Dokumentation zur Content-Deklaration.

Schritt 6: Inhalte in Ihrem Code nutzen

Greifen Sie in Ihrer gesamten Anwendung auf Ihre Content-Dictionaries zu:

import type { FC } from "react";import { ClientComponentExample } from "@components/clientComponentExample/ClientComponentExample";import { ServerComponentExample } from "@components/serverComponentExample/ServerComponentExample";import {  IntlayerServerProvider,  useIntlayer,  getLocale,} from "next-intlayer/server";import { NextPage } from "next";import { headers, cookies } from "next/headers";const PageContent: FC = () => {  const content = useIntlayer("page");  return (    <>      <p>{content.getStarted.main}</p>      <code>{content.getStarted.pageLink}</code>    </>  );};const Page: NextPage = async () => {  const locale = await getLocale();  return (    <IntlayerServerProvider locale={locale}>      <PageContent />      <ServerComponentExample />      <ClientComponentExample />    </IntlayerServerProvider>  );};export default Page;

• IntlayerClientProvider wird verwendet, um die Locale 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 ü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, verbessern die Leistung und behalten einen konsistenten Lokalisierungskontext in Ihrer Anwendung bei.

• IntlayerServerProvider wird verwendet, um die locale an die serverseitigen Kinder bereitzustellen. Es kann nicht im Layout gesetzt werden.

  Layout und Seite können keinen gemeinsamen Serverkontext teilen, da das Serverkontext-System auf einem pro-Anfrage-Datenspeicher basiert (über React's 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 aufheben und verhindern, dass die Serverkontextwerte korrekt 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"); // Erstelle die zugehörige Content-Deklaration  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"); // Erstelle die zugehörige Inhaltsdeklaration  return (    <div>      <h2>{content.title}</h2>      <p>{content.content}</p>    </div>  );};

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

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

Weitere Informationen zum useIntlayer-Hook finden Sie in der Dokumentation.

(Optional) Schritt 7: Proxy zur Erkennung der bevorzugten Locale konfigurieren

Richten Sie den Proxy ein, um die bevorzugte Locale des Benutzers zu erkennen:

export { intlayerProxy as proxy } from "next-intlayer/proxy";export const config = {  matcher:    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",};

Der intlayerProxy wird verwendet, um die bevorzugte Locale des Nutzers zu erkennen und ihn auf die entsprechende URL weiterzuleiten, wie in der Konfiguration angegeben. Außerdem ermöglicht er, die bevorzugte Locale des Nutzers in einem Cookie zu speichern.

Wenn Sie mehrere Proxies hintereinander schalten müssen (zum Beispiel intlayerProxy zusammen mit Authentifizierung oder benutzerdefinierten Proxies), stellt Intlayer jetzt einen Helfer namens multipleProxies zur Verfügung.

import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";import { customProxy } from "@utils/customProxy";export const proxy = multipleProxies([intlayerProxy, customProxy]);

(Optional) Schritt 8: Ändern Sie die Sprache Ihrer Inhalte

Um die Sprache Ihrer Inhalte in Next.js zu ändern, empfiehlt es sich, die Link-Komponente zu verwenden, um Benutzer auf die entsprechende lokalisierte Seite weiterzuleiten. Die Link-Komponente ermöglicht das Prefetching der Seite, wodurch ein vollständiger Seitenreload vermieden werden kann.

"use client";import type { FC } from "react";import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";import { useLocale } from "next-intlayer";export const LocaleSwitcher: FC = () => {  const { locale, availableLocales, setLocale } = useLocale({    onChange: () => window.location.reload(),  });  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <button            key={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={() => setLocale(localeItem)}          >            <span>              {/* Locale - z. B. FR */}              {localeItem}            </span>            <span>              {/* Sprache in ihrer eigenen Locale - z. B. Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Sprache in der aktuellen Locale - z. B. Francés, wenn die aktuelle Locale 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>          </button>        ))}      </div>    </div>  );};

Eine alternative Möglichkeit ist, die vom useLocale Hook bereitgestellte Funktion setLocale zu verwenden. Diese Funktion ermöglicht kein Prefetching der Seite. Weitere Details findest du in der Dokumentation des useLocale-Hooks.

Dokumentationsreferenzen:

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

(Optional) Schritt 9: Aktuelle Locale in Server Actions abrufen

Wenn Sie die aktive Locale innerhalb einer Server Action benötigen (z. B. um E-Mails zu lokalisieren oder lokalisierungsabhängige Logik auszuführen), rufen Sie getLocale aus next-intlayer/server auf:

"use server";import { getLocale } from "next-intlayer/server";export const myServerAction = async () => {  const locale = await getLocale();  // Mit der Locale etwas tun};

Die Funktion getLocale folgt einer kaskadierenden Strategie, um die Locale des Benutzers zu bestimmen:

1. Zuerst prüft sie die Request-Header auf einen Locale-Wert, der möglicherweise vom Proxy gesetzt wurde
2. Wenn in den Headern keine Locale gefunden wird, sucht sie nach einer in Cookies gespeicherten Locale
3. Findet sich kein Cookie, versucht sie, die bevorzugte Sprache des Benutzers aus den Browsereinstellungen zu ermitteln
4. Als letzter Ausweg fällt sie auf die in der Anwendung konfigurierte Standard-Locale zurück

Dies stellt sicher, dass die am besten geeignete Locale basierend auf dem verfügbaren Kontext ausgewählt wird.

(Optional) Schritt 10: Bundle-Größe optimieren

Bei Verwendung von next-intlayer werden Wörterbücher standardmäßig 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 von 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:

npm install @intlayer/swc --save-devnpx intlayer init

Hinweis: Diese Optimierung ist nur für Next.js 13 und höher verfügbar.

Hinweis: Dieses Paket wird nicht standardmäßig installiert, da SWC-Plugins in Next.js noch experimentell sind. Das kann sich in Zukunft ändern.

Hinweis: Wenn Sie die Option als importMode: 'dynamic' oder importMode: 'live' setzen, basiert dies auf Suspense, daher müssen Sie Ihre useIntlayer-Aufrufe in eine Suspense-Grenze einhüllen. Das bedeutet, dass Sie useIntlayer nicht direkt auf der obersten Ebene Ihrer Page-/Layout-Komponente verwenden können.

Wörterbuchänderungen mit Turbopack überwachen

Wenn Sie Turbopack als Entwicklungsserver mit dem Befehl next dev verwenden, werden Wörterbuchänderungen standardmäßig nicht automatisch erkannt.

Diese Einschränkung entsteht, weil Turbopack nicht in der Lage ist, webpack-Plugins parallel auszuführen, um Änderungen an Ihren Inhaltsdateien zu überwachen. Um dies zu umgehen, müssen Sie den Befehl intlayer watch verwenden, um gleichzeitig sowohl den Entwicklungsserver als auch den Intlayer-Build-Watcher auszuführen.

{  // ... Ihre vorhandenen package.json-Konfigurationen  "scripts": {    // ... Ihre vorhandenen Skript-Konfigurationen    "dev": "intlayer watch --with 'next dev'",  },}

Wenn Sie next-intlayer@<=6.x.x verwenden, müssen Sie das Flag --turbopack beibehalten, damit die Next.js 16-Anwendung korrekt mit Turbopack funktioniert. Wir empfehlen die Verwendung von next-intlayer@>=7.x.x, um diese Einschränkung zu vermeiden.

TypeScript konfigurieren

Intlayer verwendet Module Augmentation, um die Vorteile von TypeScript zu nutzen und Ihre Codebase robuster zu machen.

Stellen Sie sicher, dass Ihre TypeScript-Konfiguration die automatisch generierten Typen enthält.

{  // ... Ihre vorhandenen TypeScript-Konfigurationen  "include": [    // ... Ihre vorhandenen TypeScript-Konfigurationen    ".intlayer/**/*.ts", // Include the auto-generated types  ],}

Git-Konfiguration

Es wird empfohlen, die von Intlayer generierten Dateien zu ignorieren. So vermeiden Sie, sie in Ihr Git-Repository zu committen.

Dazu können Sie die folgenden Anweisungen in Ihre .gitignore-Datei hinzufügen:

# Ignoriere die von Intlayer generierten Dateien.intlayer

VS Code-Erweiterung

Um Ihre Entwicklererfahrung mit Intlayer zu verbessern, können Sie die offizielle Intlayer VS Code Extension installieren.

Aus dem VS Code Marketplace installieren

Diese Erweiterung bietet:

• Autovervollständigung für Übersetzungsschlüssel.
• Echtzeit-Fehlererkennung für fehlende Übersetzungen.
• Inline-Vorschauen des übersetzten Inhalts.
• Schnellaktionen zum einfachen Erstellen und Aktualisieren von Übersetzungen.

Für weitere Details zur Verwendung der Extension siehe die Intlayer VS Code Extension Dokumentation.

Weiterführende Informationen

Um weiterzugehen, können Sie den visual editor implementieren oder Ihre Inhalte mit dem CMS externalisieren.