Schnellstart

Fügen Sie Ihrer React-App in unter 5 Minuten mehrsprachige Unterstützung hinzu.

Voraussetzungen

  • Node.js 18+
  • React-Anwendung mit Next.js (App Router) oder Vite

Installation

pnpm install @lingo.dev/compiler

Konfiguration

Next.js

Machen Sie Ihre Konfiguration asynchron und umschließen Sie sie mit withLingo:

// next.config.ts
import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {
    sourceRoot: "./app",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr"],
    models: "lingo.dev",
    dev: {
      usePseudotranslator: true, // Fake translations for development
    },
  });
}

Vite

Fügen Sie das Lingo-Plugin zu Ihrer Vite-Konfiguration hinzu:

// vite.config.ts
import { defineConfig } from "vite";
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,
      },
    }),
    // ...other plugins
  ],
});

Provider einrichten

Next.js

Umschließen Sie Ihre App mit LingoProvider in Ihrem Root-Layout:

// app/layout.tsx
import { LingoProvider } from "@lingo.dev/compiler/react";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <LingoProvider>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

Vite

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

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

Authentifizierung

Der Compiler verwendet standardmäßig die Lingo.dev Engine für Übersetzungen.

Option 1: Lingo.dev Engine (empfohlen)

Registrieren Sie sich unter lingo.dev und authentifizieren Sie sich:

npx lingo.dev@latest login

Windows-Benutzer: Falls npx lingo.dev in Ihrer Umgebung nicht funktioniert:

  1. Installieren Sie das Paket: npm install lingo.dev@latest
  2. Verwenden Sie stattdessen npx lingo (z. B. npx lingo login)

Dies speichert Ihren API-Schlüssel lokal. Der kostenlose Hobby-Tarif ist für die meisten Projekte ausreichend.

Authentifizierungsprobleme? Falls Ihr Browser den Auth-Flow blockiert, fügen Sie Ihren API-Schlüssel manuell zu .env hinzu:

LINGODOTDEV_API_KEY=your_key_here

Ihren API-Schlüssel finden Sie in den Lingo.dev-Projekteinstellungen.

Option 2: Direkter LLM-Provider

Alternativ können Sie jeden unterstützten LLM-Provider direkt verwenden. Aktualisieren Sie Ihre Konfiguration:

{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",
    // or "google:gemini-2.0-flash"
    // or "openai:gpt-4o"
    // or "anthropic:claude-3-5-sonnet"
  }
}

Fügen Sie den entsprechenden API-Schlüssel zu .env hinzu:

GROQ_API_KEY=your_key
# or GOOGLE_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY

Siehe Translation Providers für alle unterstützten Provider.

Development-Server starten

Starten Sie Ihren Dev-Server:

npm run dev

Der Compiler wird:

  1. Ihr JSX nach übersetzbarem Text scannen
  2. Pseudoübersetzungen generieren (Fake-Übersetzungen zur Visualisierung dessen, was übersetzt wird)
  3. Diese in Ihre Komponenten injizieren
  4. Metadaten in .lingo/metadata.json speichern

Warum Pseudoübersetzungen? Sie sind sofort verfügbar (keine API-Aufrufe), zeigen genau, was übersetzt wird, und helfen beim Testen Ihrer UI mit variierenden Textlängen – alles ohne API-Credits zu verbrauchen.

Übersetzung testen

Fügen Sie eine einfache Komponente hinzu:

export function Welcome() {
  return (
    <div>
      <h1>Welcome to our app</h1>
      <p>This text will be translated automatically</p>
    </div>
  );
}

Keine Code-Änderungen erforderlich – Text wird automatisch extrahiert und übersetzt.

Language-Switcher hinzufügen (optional)

Ermöglichen Sie Nutzern, die Sprache zu wechseln:

"use client"; // For Next.js

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

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

  return (
    <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>
  );
}

Echte Übersetzungen generieren

Wenn Sie bereit für echte Übersetzungen sind, aktualisieren Sie Ihre Konfiguration:

{
  dev: {
    usePseudotranslator: false, // Disable fake translations
  }
}

Starten Sie Ihren Dev-Server neu. Der Compiler generiert nun echte KI-Übersetzungen für jeden neuen oder geänderten Text.

Kostenbewusst? Pseudoübersetzungen sind kostenlos und sofort verfügbar. Deaktivieren Sie sie nur, wenn Sie die tatsächliche Übersetzungsqualität überprüfen müssen.

Häufige Fragen

Muss ich jeden übersetzbaren String markieren? Nein. Der Compiler erkennt JSX-Text automatisch. Um stattdessen Opt-in zu verwenden, setzen Sie useDirective: true und fügen Sie 'use i18n' am Anfang der Dateien hinzu, die Sie übersetzen möchten.

Was ist mit dynamischem Inhalt oder Props? Der Compiler verarbeitet String-Attribute wie alt, aria-label und placeholder automatisch. Für dynamischen Text verwenden Sie Template-Syntax: <p>Hello {name}</p> funktioniert wie erwartet.

Kann ich bestimmte Übersetzungen anpassen? Ja. Verwenden Sie das data-lingo-override-Attribut:

<h1 data-lingo-override={{ es: "Bienvenido", de: "Willkommen" }}>
  Welcome
</h1>

Wie committe ich Übersetzungen? Committen Sie das .lingo/-Verzeichnis in die Versionskontrolle. Es enthält Metadaten und gecachte Übersetzungen – sicher zum Committen und sollte zusammen mit Ihrem Code versioniert werden.

Nächste Schritte