Vite + React Integration

@lingo.dev/compiler integriert sich über ein Plugin in Vite, das sowohl mit SPA- als auch mit SSR-Setups funktioniert.

Einrichtung

1. Paket installieren

pnpm install @lingo.dev/compiler

2. Vite konfigurieren

Fügen Sie lingoCompilerPlugin zu Ihrer Vite-Konfiguration hinzu:

// 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"],
      models: "lingo.dev",
      dev: {
        usePseudotranslator: true,
      },
    }),
    react(),
  ],
});

Plugin-Reihenfolge: Platzieren Sie lingoCompilerPlugin vor dem react()-Plugin. Dadurch wird sichergestellt, dass der Compiler Ihr JSX transformiert, bevor React es verarbeitet.

3. Provider hinzufügen

Umschließen Sie Ihre App mit LingoProvider in Ihrem Einstiegspunkt:

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

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

Wichtig: Platzieren Sie LingoProvider so weit oben wie möglich in Ihrem Komponentenbaum. Wenn Sie TanStack Router oder React Router verwenden, platzieren Sie LingoProvider über dem Router-Provider.

SPA-Einrichtung

Für Single-Page-Anwendungen ist die obige Einrichtung ausreichend. Die Locale wird clientseitig verwaltet.

Sprachwechsler

"use client";

import { useLingoContext } from "@lingo.dev/compiler/react";

export function LanguageSwitcher() {
  const { locale, setLocale } = useLingoContext();

  return (
    <div>
      <label>Language:</label>
      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
        <option value="en">English</option>
        <option value="es">Español</option>
        <option value="de">Deutsch</option>
        <option value="fr">Français</option>
      </select>
    </div>
  );
}

SSR-Einrichtung (React Router, Remix, TanStack Start)

Für SSR-Frameworks müssen Sie möglicherweise die Locale-Erkennung auf dem Server handhaben.

Benutzerdefinierte Locale-Erkennung

Erstellen Sie .lingo/locale-resolver.server.ts für serverseitige Logik:

// .lingo/locale-resolver.server.ts
export async function getServerLocale(): Promise<string> {
  // Access request context (framework-specific)
  // Example: parse cookies, headers, or database
  return "en"; // Return detected locale
}

Und .lingo/locale-resolver.client.ts für clientseitige:

// .lingo/locale-resolver.client.ts
export function getClientLocale(): string {
  return localStorage.getItem("locale") || "en";
}

export function persistLocale(locale: string): void {
  localStorage.setItem("locale", locale);
}

Siehe Benutzerdefinierte Locale-Resolver für framework-spezifische Beispiele.

TanStack Router-Integration

Platzieren Sie bei TanStack Router LingoProvider über RouterProvider:

// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { RouterProvider, createRouter } from "@tanstack/react-router";
import { LingoProvider } from "@lingo.dev/compiler/react";
import { routeTree } from "./routeTree.gen";

const router = createRouter({ routeTree });

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <LingoProvider>
      <RouterProvider router={router} />
    </LingoProvider>
  </StrictMode>
);

Dies stellt sicher, dass Übersetzungen in allen gerouteten Komponenten verfügbar sind und der Kontext nicht durch Code-Splitting unterbrochen wird.

React Router-Integration

Für React Router v6/v7:

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

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

HMR und Entwicklung

Der Compiler unterstützt vollständig Vites Hot Module Replacement (HMR). Wenn Sie übersetzbare Texte aktualisieren:

  1. Der Compiler erkennt die Änderung
  2. Der Übersetzungsserver generiert neue Übersetzungen (oder Pseudoübersetzungen)
  3. HMR aktualisiert Ihre Komponente ohne vollständiges Neuladen
  4. Der Komponentenstatus bleibt erhalten

Fast Refresh funktioniert normal – der Compiler beeinträchtigt Vites HMR nicht.

Build-Konfiguration

Development-Build

{
  dev: {
    usePseudotranslator: true, // Fast fake translations
  }
}

Führen Sie npm run dev aus, um sofortiges Feedback mit Pseudoübersetzungen zu erhalten.

Production-Build

{
  buildMode: "cache-only", // Use pre-generated translations
}

Führen Sie npm run build aus. Übersetzungen stammen aus .lingo/metadata.json – keine API-Aufrufe erforderlich.

Best Practice: Generieren Sie echte Übersetzungen in CI vor Production-Builds. Siehe Build-Modi.

Code-Splitting

Der Compiler respektiert Vites Code-Splitting. Jeder lazy-geladene Chunk enthält nur die Übersetzungen, die er benötigt.

// Lazy-loaded route
const Dashboard = lazy(() => import("./pages/Dashboard"));

// Dashboard component's translations are bundled with the Dashboard chunk

Übersetzungen werden automatisch tree-shaken – nur verwendete Übersetzungen werden in jedem Chunk enthalten.

TypeScript

Der Compiler ist vollständig typisiert:

import type { LingoConfig } from "@lingo.dev/compiler";

const config: LingoConfig = {
  sourceRoot: "src",
  sourceLocale: "en",
  targetLocales: ["es", "de"],
  models: "lingo.dev",
};

Umgebungsvariablen

Verwenden Sie Vites Umgebungsvariablen-System für API-Schlüssel:

# .env
VITE_LINGO_API_KEY=your_key_here

Zugriff in der Konfiguration:

{
  models: "lingo.dev",
  // API key is automatically read from LINGODOTDEV_API_KEY env variable
}

Committen Sie niemals API-Schlüssel. Fügen Sie .env zu .gitignore hinzu.

Häufige Probleme

"Cannot find module '@lingo.dev/compiler/react'" Stellen Sie sicher, dass das Paket installiert ist: pnpm install @lingo.dev/compiler

HMR bricht nach Hinzufügen von LingoProvider ab Überprüfen Sie, dass lingoCompilerPlugin vor dem react()-Plugin in Ihrer Vite-Konfiguration platziert ist.

Übersetzungen werden in der Produktion nicht angezeigt Überprüfen Sie buildMode: "cache-only" und dass .lingo/metadata.json Übersetzungen für alle Locales enthält.

Context durch Code-Splitting unterbrochen Stellen Sie sicher, dass LingoProvider oberhalb Ihres Router-Providers (TanStack Router, React Router usw.) platziert ist. Andernfalls können Code-Split-Routen den Context verlieren.

Port 60000 bereits in Verwendung Der Übersetzungsserver findet automatisch verfügbare Ports (60000-60099). Wenn alle belegt sind, konfigurieren Sie manuell:

{
  dev: {
    translationServerStartPort: 61000, // Use different port range
  }
}

Nächste Schritte