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

Siehe Application Template auf GitHub.

Inhaltsverzeichnis

Warum Intlayer gegenüber Alternativen?

Im Vergleich zu Hauptlösungen wie „next-intl“ oder „i18next“ ist Intlayer eine Lösung, die über integrierte Optimierungen verfügt wie:

Schritt-für-Schritt-Anleitung zur Einrichtung von Intlayer in einer Next.js-Anwendung

1. 1

   Abhängigkeiten installieren

   Installieren Sie die erforderlichen Pakete mit npm:

   bash

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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.

2. 2

   Konfigurieren Sie Ihr Projekt

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

   bash

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   .├── 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:

   intlayer.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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.

3. 3

   Intlayer in Ihre Next.js-Konfiguration integrieren

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

   next.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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:

   ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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:

   ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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:

   ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

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

4. 4

   Dynamische Locale-Routen definieren

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

   src/app/layout.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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 (): Promise<Metadata> => {
     const locale = await getLocale();
     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;

5. 5

   Deklarieren Sie Ihre Inhalte

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

   src/app/metadata.content.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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;

   src/app/page.content.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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,cjs,md,mdx,yaml,yml}).

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

6. 6

   Inhalte in Ihrem Code nutzen

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

   src/app/page.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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.

   src/components/clientComponentExample/ClientComponentExample.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   "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>
     );
   };

   src/components/serverComponentExample/ServerComponentExample.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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.:

   html

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   <img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

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

7. 7

   Proxy zur Erkennung der bevorzugten Locale konfigurieren

   Optional

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

   src/proxy.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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.

   ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

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

8. 8

   Ändern Sie die Sprache Ihrer Inhalte

   Optional

   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.

   src/components/localeSwitcher/LocaleSwitcher.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   "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();
   
     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

9. 9

   Aktuelle Locale in Server Actions abrufen

   Optional

   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:

   src/app/actions/getLocale.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   "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.

10. 10

    Bundle-Größe optimieren

    Optional

    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:

    bash

    Inhalt kopieren

    Code kopieren

    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 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: 'fetch' (in the dictionary configuration) 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.