Wie man eine bestehende Vite- und React-Anwendung nachträglich mehrsprachig (i18n) macht (i18n-Leitfaden 2026)

Siehe Anwendungsvorlage auf GitHub.

Inhaltsverzeichnis

Warum ist es schwierig, eine bestehende Anwendung zu internationalisieren?

Wenn Sie jemals versucht haben, mehrere Sprachen zu einer App hinzuzufügen, die nur für eine gebaut wurde, kennen Sie den Schmerz. Es ist nicht nur "schwer" – es ist mühsam. Sie müssen jede einzelne Datei durchforsten, jede Textzeichenfolge aufspüren und sie in separate Wörterbuchdateien verschieben.

Dann kommt der riskante Teil: das Ersetzen des gesamten Textes durch Code-Hooks, ohne Ihr Layout oder Ihre Logik zu beeinträchtigen. Es ist die Art von Arbeit, die die Entwicklung neuer Funktionen für Wochen zum Stillstand bringt und sich wie endloses Refactoring anfühlt.

Was ist der Intlayer-Compiler?

Der Intlayer-Compiler wurde entwickelt, um diese manuelle Routinearbeit zu überspringen. Anstatt dass Sie Zeichenfolgen manuell extrahieren, erledigt der Compiler dies für Sie. Er scannt Ihren Code, findet den Text und verwendet KI, um die Wörterbücher im Hintergrund zu generieren. Anschließend modifiziert er Ihren Code während des Builds, um die erforderlichen i18n-Hooks einzufügen. Im Grunde schreiben Sie Ihre App weiterhin so, als wäre sie einsprachig, und der Compiler übernimmt die mehrsprachige Transformation automatisch.

Dokumentation Compiler: /de/doc/compiler

Einschränkungen

Da der Compiler Codeanalysen und Transformationen (Einfügen von Hooks und Generieren von Wörterbüchern) zum Zeitpunkt der Kompilierung durchführt, kann er den Build-Leistung Ihrer Anwendung verlangsamen.

Um diese Auswirkungen während der Entwicklung abzumildern, können Sie den Compiler so konfigurieren, dass er im Modus 'build-only' läuft, oder ihn deaktivieren, wenn er nicht benötigt wird.

Schritt-für-Schritt-Anleitung zur Einrichtung von Intlayer in einer Vite- und React-Anwendung

Schritt 1: Abhängigkeiten installieren

Installieren Sie die erforderlichen Pakete mit npm:

npm install intlayer react-intlayernpm install vite-intlayer --save-devnpx intlayer init

• intlayer Das Kernpaket, das Internationalisierungswerkzeuge für die Konfigurationsverwaltung, Übersetzung, Inhaltsdeklaration, Transpilation und CLI-Befehle bereitstellt.

• react-intlayer Das Paket, das Intlayer in die React-Anwendung integriert. Es bietet Kontextanbieter und Hooks für die React-Internationalisierung.

• vite-intlayer Enthält das Vite-Plugin zur Integration von Intlayer in den Vite-Bundler sowie Middleware zur Erkennung des bevorzugten Gebietsschemas des Benutzers, zur Verwaltung von Cookies und zur Handhabung von URL-Umleitungen.

Schritt 2: Konfigurieren Sie Ihr Projekt

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, Locales.GERMAN],    defaultLocale: Locales.ENGLISH,  },  compiler: {    /**     * Gibt an, ob der Compiler aktiviert werden soll.     */    enabled: true,    /**     * Ausgabeverzeichnis für die optimierten Wörterbücher.     */    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,    /**     * Fügen Sie nur den Inhalt in die generierte Datei ein, ohne Schlüssel.     */    noMetadata: false,    /**     * Wörterbuch-Präfix     */    dictionaryKeyPrefix: "", // Remove base prefix    /**     * Gibt an, ob die Komponenten nach der Transformation gespeichert werden sollen.     * Auf diese Weise kann der Compiler nur einmal ausgeführt werden, um die App zu transformieren, und dann entfernt werden.     */    saveComponents: false,  },  ai: {    provider: "openai",    model: "gpt-5-mini",    apiKey: process.env.OPEN_AI_API_KEY,    applicationContext: "Diese App ist eine Karten-App", // Hinweis: Sie können diese App-Beschreibung anpassen  },};export default config;

Hinweis: Stellen Sie sicher, dass Ihr OPEN_AI_API_KEY in Ihren Umgebungsvariablen gesetzt ist.

Über diese Konfigurationsdatei können Sie lokalisierte URLs, Middleware-Umleitungen, Cookie-Namen, den Speicherort und die Erweiterung Ihrer Inhaltsdeklarationen festlegen, Intlayer-Protokolle in der Konsole deaktivieren und vieles mehr. Eine vollständige Liste der verfügbaren Parameter finden Sie in der Konfigurationsdokumentation.

Schritt 3: Intlayer in Ihre Vite-Konfiguration integrieren

Fügen Sie das Intlayer-Plugin zu Ihrer Konfiguration hinzu.

import { defineConfig } from "vite";import react from "@vitejs/plugin-react-swc";import { intlayer, intlayerCompiler } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [react(), intlayer(), intlayerCompiler()],});

Das intlayer()-Vite-Plugin wird verwendet, um Intlayer in Vite zu integrieren. Es stellt die Erstellung von Inhaltsdeklarationsdateien sicher und überwacht diese im Entwicklungsmodus. Es definiert Intlayer-Umgebungsvariablen innerhalb der Vite-Anwendung. Darüber hinaus bietet es Aliase zur Leistungsoptimierung.

Das intlayerCompiler()-Vite-Plugin wird verwendet, um Inhalte aus Komponenten zu extrahieren und .content-Dateien zu schreiben.

Schritt 4: Kompilieren Sie Ihren Code

Schreiben Sie Ihre Komponenten einfach mit fest codierten Zeichenfolgen in Ihrem Standard-Gebietsschema. Der Compiler kümmert sich um den Rest.

Beispiel, wie Ihre Seite aussehen könnte:

import { useState, type FC } from "react";import reactLogo from "./assets/react.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider } from "react-intlayer";const AppContent: FC = () => { const [count, setCount] = useState(0); return (   <>     <div>       <a href="https://vitejs.dev" target="_blank">         <img src={viteLogo} className="logo" alt="Vite logo" />       </a>       <a href="https://react.dev" target="_blank">         <img src={reactLogo} className="logo react" alt="React logo" />       </a>     </div>     <h1>Vite + React</h1>     <div className="card">       <button onClick={() => setCount((count) => count + 1)}>         count is {count}       </button>       <p>         Edit <code>src/App.tsx</code> and save to test HMR       </p>     </div>     <p className="read-the-docs">       Click on the Vite and React logos to learn more     </p>   </> );};const App: FC = () => ( <IntlayerProvider>   <AppContent /> </IntlayerProvider>);export default App;

{ key: "app-content", content: {   nodeType: "translation",   translation: {     en: {       viteLogo: "Vite logo",       reactLogo: "React logo",       title: "Vite + React",       countButton: "count is",       editMessage: "Edit",       hmrMessage: "and save to test HMR",       readTheDocs: "Click on the Vite and React logos to learn more",     },     de: {       viteLogo: "Vite Logo",       reactLogo: "React Logo",       title: "Vite + React",       countButton: "Zähler ist",       editMessage: "Bearbeite",       hmrMessage: "und speichere, um HMR zu testen",       readTheDocs: "Klicke auf die Vite- und React-Logos, um mehr zu erfahren",     },   } }}

import { useState, type FC } from "react";import reactLogo from "./assets/react.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider, useIntlayer } from "react-intlayer";const AppContent: FC = () => { const [count, setCount] = useState(0); const content = useIntlayer("app-content"); return (   <>     <div>       <a href="https://vitejs.dev" target="_blank">         <img src={viteLogo} className="logo" alt={content.viteLogo.value} />       </a>       <a href="https://react.dev" target="_blank">         <img           src={reactLogo}           className="logo react"           alt={content.reactLogo.value}         />       </a>     </div>     <h1>{content.title}</h1>     <div className="card">       <button onClick={() => setCount((count) => count + 1)}>         {content.countButton} {count}       </button>       <p>         {content.editMessage} <code>src/App.tsx</code> {content.hmrMessage}       </p>     </div>     <p className="read-the-docs">{content.readTheDocs}</p>   </> );};const App: FC = () => ( <IntlayerProvider>   <AppContent /> </IntlayerProvider>);export default App;

• IntlayerProvider wird verwendet, um das Gebietsschema für verschachtelte Komponenten bereitzustellen.

(Optional) Schritt 6: Die Sprache Ihres Inhalts ändern

Um die Sprache Ihres Inhalts zu ändern, können Sie die Funktion setLocale verwenden, die vom Hook useLocale bereitgestellt wird. Mit dieser Funktion können Sie das Gebietsschema der Anwendung festlegen und den Inhalt entsprechend aktualisieren.

import type { FC } from "react";import { Locales } from "intlayer";import { useLocale } from "react-intlayer";const LocaleSwitcher: FC = () => {  const { setLocale } = useLocale();  return (    <button onClick={() => setLocale(Locales.GERMAN)}>      Sprache auf Deutsch ändern    </button>  );};

Um mehr über den Hook useLocale zu erfahren, lesen Sie die Dokumentation.

(Optional) Schritt 7: Fehlende Übersetzungen ausfüllen

Intlayer bietet ein CLI-Tool an, mit dem Sie fehlende Übersetzungen ausfüllen können. Sie können den Befehl intlayer verwenden, um fehlende Übersetzungen in Ihrem Code zu testen und auszufüllen.

npx intlayer test         # Testen, ob Übersetzungen fehlen

npx intlayer fill         # Fehlende Übersetzungen ausfüllen

Weitere Informationen finden Sie in der CLI-Dokumentation

(Optional) Sitemap und robots.txt (Build-Zeit)

Intlayer stellt Hilfsfunktionen bereit - generateSitemap und getMultilingualUrls -, mit denen Sie mehrsprachige sitemap.xml- und robots.txt-Inhalte für Crawler formatieren und automatisch nach public/ schreiben können. Üblich ist ein kleines Node-Skript vor Vite (z. B. npm-predev-/prebuild-Hooks), damit die Dateien beim Build bzw. Dev-Server vorliegen.

Sitemap

Der Sitemap-Generator von Intlayer berücksichtigt Ihre Locales und die üblichen Metadaten für Crawler.

Die erzeugte Sitemap unterstützt den xhtml:link-Namensraum (Hreflang). Statt nur flacher URLs verknüpft Intlayer alle Sprachversionen einer Seite bidirektional (z. B. /about, /fr/about oder /about?lang=fr je nach Routing), was Suchmaschinen hilft.

Robots.txt

Mit getMultilingualUrls gelten Disallow-Regeln für alle lokalisierten Varianten sensibler Pfade.

1. generate-seo.mjs im Projektroot anlegen

import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

intlayer muss installiert sein. Setzen Sie SITE_URL in der Produktion über die Umgebung (z. B. in der CI).

Nutzen Sie möglichst generate-seo.mjs für Node-ESM. Bei generate-seo.js "type": "module" in der package.json setzen oder Node mit ESM starten.

2. Skript vor Vite ausführen

{  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

Bei pnpm oder yarn die Befehle anpassen. Aufruf aus der CI ist ebenfalls möglich.

Git-Konfiguration

Es wird empfohlen, die von Intlayer generierten Dateien zu ignorieren. Dies ermöglicht es Ihnen zu vermeiden, sie in Ihr Git-Repository zu übertragen.

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

# Von Intlayer generierte Dateien ignorieren.intlayer

VS Code-Erweiterung

Um Ihre Entwicklungserfahrung mit Intlayer zu verbessern, können Sie die offizielle Intlayer VS Code-Erweiterung installieren.

Im VS Code Marketplace installieren

Diese Erweiterung bietet:

• Autovervollständigung für Übersetzungsschlüssel.
• Fehlererkennung in Echtzeit für fehlende Übersetzungen.
• Inline-Vorschauen von übersetzten Inhalten.
• Schnellaktionen, um Übersetzungen einfach zu erstellen und zu aktualisieren.

Weitere Details zur Verwendung der Erweiterung finden Sie in der Dokumentation zur Intlayer VS Code-Erweiterung.

Weiterführendes

Um weiterzugehen, können Sie den visuellen Editor implementieren oder Ihre Inhalte mit dem CMS extern verwalten.