Vite + React

Alpha

Der Lingo.dev Compiler befindet sich in der Alpha-Phase. Er ist instabil, für den Produktionseinsatz nicht empfohlen, und APIs können sich zwischen Releases ändern.

Der Lingo.dev Compiler lässt sich über lingoCompilerPlugin in Vite integrieren – ein Vite-Plugin, das Ihre React-Komponenten zur Build-Zeit transformiert und Übersetzungen einbindet. Es unterstützt vollständiges Hot Module Replacement, sodass Übersetzungen während der Entwicklung sofort aktualisiert werden.

Voraussetzungen#

Anforderungen

Vite 5+ mit React
Node.js 18+
@lingo.dev/compiler installiert

Installieren#

bash

pnpm install @lingo.dev/compiler

vite.config.ts konfigurieren#

Fügen Sie lingoCompilerPlugin zu Ihrer Vite-Konfiguration hinzu. Das Plugin muss vor dem react()-Plugin stehen – diese Reihenfolge ist erforderlich, weil der Compiler JSX transformieren muss, bevor das React-Plugin es verarbeitet.

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite";

export default defineConfig({
  plugins: [
    lingoCompilerPlugin({
      sourceRoot: "src",
      sourceLocale: "en",
      targetLocales: ["es", "de", "fr", "ja"],
      models: "lingo.dev",
      dev: {
        usePseudotranslator: true,
      },
    }),
    react(),
  ],
});

Die Plugin-Reihenfolge ist entscheidend

Wenn lingoCompilerPlugin nach react() platziert wird, verarbeitet das React-Plugin JSX zuerst und der Compiler kann keinen übersetzbaren Text mehr erkennen. Platzieren Sie das Lingo-Plugin im plugins-Array immer an erster Stelle.

LingoProvider hinzufügen#

Umschließen Sie die Wurzel Ihrer Anwendung in Ihrer Entry-Datei mit LingoProvider:

tsx

// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { LingoProvider } from "@lingo.dev/compiler/react";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <LingoProvider>
      <App />
    </LingoProvider>
  </StrictMode>
);

LingoProvider initialisiert den Sprachkontext und lädt das passende Übersetzungswörterbuch für die aktive Sprache.

Hot Module Replacement#

Das Plugin ist in Vites HMR-System integriert. Wenn Sie übersetzbaren Text in einer Komponente bearbeiten:

Quelltext bearbeiten

Ändern Sie beliebigen Text in Ihrem JSX – zum Beispiel eine Überschrift von "Willkommen" zu "Willkommen zurück".

Compiler erkennt die Änderung

Das Plugin fängt das HMR-Update ab, erkennt die geänderte Zeichenfolge und erzeugt eine neue Übersetzung (oder eine Pseudoübersetzung im Entwicklungsmodus).

Browser aktualisiert sich sofort

Die übersetzte Komponente wird ohne vollständiges Neuladen der Seite neu gerendert. Die Übersetzungsmetadaten in .lingo/metadata.json werden auf dem Datenträger aktualisiert.

sourceRoot-Konfiguration#

Die Option sourceRoot legt fest, welche Dateien der Compiler nach übersetzbarem Text durchsucht. Für ein Standardprojekt mit Vite + React gilt:

{
  sourceRoot: "src",
}

Projektstruktur	Empfohlene sourceRoot
Standard (`src/`)	`"src"`
Monorepo mit gemeinsam genutzten Paketen	`"."` (Projektstamm)
Benutzerdefiniertes Verzeichnis	Pfad zu Ihrem Komponentenverzeichnis

Bei großen Codebases verkürzt ein eng gefasstes sourceRoot die Build-Zeiten. Wenn Sie Übersetzungen nur in bestimmten Dateien benötigen, aktivieren Sie useDirective: true und fügen Sie 'use i18n' zu diesen Dateien hinzu. Siehe Projektstruktur.

Beispielprojektstruktur#

text

my-vite-app/
  src/
    main.tsx          # LingoProvider wraps <App />
    App.tsx           # Translatable components
    components/
      Header.tsx      # Automatically scanned
      Footer.tsx      # Automatically scanned
  .lingo/
    metadata.json     # Translation cache (commit this)
  vite.config.ts      # lingoCompilerPlugin configured here

Nächste Schritte#

Setup

Vollständige Schritt-für-Schritt-Anleitung mit Authentifizierung

Konfigurationsreferenz

Alle Konfigurationsoptionen

Sprachwechsel

Fügen Sie Ihrer App einen Sprachumschalter hinzu

Entwicklungstools

Pseudoübersetzer und Entwicklungsserver