Schnellstart für React Router (v6)

Einführung

Lingo.dev Compiler ist ein KI-gestütztes Tool, das die Lokalisierung von React-basierten Apps ermöglicht, ohne bestehende Komponenten zu verändern. Sie konfigurieren nur einige Einstellungen, umschließen Ihre App mit einem Context Provider, und das war's – Ihre App ist lokalisiert.

Diese Anleitung erklärt, wie man Lingo.dev Compiler mit v6 von React Router einrichtet, einer clientseitigen Routing-Bibliothek für React. Wenn Sie v7 verwenden, sehen Sie sich den Schnellstart für React Router (v7) an.

Was Sie lernen werden

Wie man Lingo.dev Compiler in React Router initialisiert
Wie man den Compiler für die Kompatibilität mit React Router konfiguriert
Wie man einen Locale-Switcher zum Umschalten zwischen Sprachen einrichtet

Schritt 1. API-Schlüssel einrichten

Lingo.dev Compiler verwendet Large Language Models (LLMs), um Apps mit KI zu lokalisieren. Um eines dieser Modelle zu nutzen, benötigen Sie einen API-Schlüssel von einem unterstützten Anbieter.

Um schnellstmöglich loszulegen, empfehlen wir Lingo.dev Engine – unsere eigene, gehostete Plattform, die 10.000 Tokens kostenlose monatliche Nutzung bietet.

Um einen API-Schlüssel einzurichten:

Melden Sie sich bei Lingo.dev Engine an.
Navigieren Sie zur Projects-Seite.
Klicken Sie auf API key > Copy.
Speichern Sie den API-Schlüssel in einer Umgebungsvariable:
```
export LINGODOTDEV_API_KEY="<your_api_key>"
```

Alternative: Benutzerdefinierte LLM-Anbieter

Sie müssen nicht Lingo.dev Engine verwenden. Sie können den Compiler so konfigurieren, dass er mit verschiedenen benutzerdefinierten LLM-Anbietern integriert wird, darunter:

Groq
Google
Mistral
Ollama
OpenRouter

Schritt 2. Paket installieren

Lingo.dev Compiler wird als Teil des lingo.dev npm-Pakets vertrieben. Zur Installation verwenden Sie Ihren bevorzugten Paketmanager:

npm install lingo.dev

Schritt 3. Initialisieren des Compilers

Der Lingo.dev Compiler integriert sich in Vite und läuft zur Build-Zeit. Um in den Build-Prozess von Vite einzugreifen, nehmen Sie folgende Änderungen an der Datei vite.config.ts vor:

Importieren Sie den Compiler:

import lingoCompiler from "lingo.dev/compiler";

Initialisieren Sie den Compiler mit der vite-Methode:
```
const withLingo = lingoCompiler.vite({
  sourceRoot: "src",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: false,
  useDirective: false,
  debug: false,
  models: "lingo.dev",
});
```
Für die Kompatibilität mit React Router stellen Sie sicher, dass:
- sourceRoot auf "src" gesetzt ist
- rsc auf false gesetzt ist
Um mehr über die verfügbaren Optionen zu erfahren, siehe Compiler-Optionen.

Umschließen Sie Ihre bestehende Vite-Konfiguration mit dem Compiler:

const viteConfig: UserConfig = {
  plugins: [react()],
};

export default withLingo(viteConfig);

Mit dieser Konfiguration wird der Lingo.dev Compiler:

Den Abstract Syntax Tree (AST) des Quellcodes durchlaufen
Lokalisierbare Inhalte finden (d.h. Text in JSX-Elementen und bestimmten Attributwerten)
Die konfigurierten KI-Modelle verwenden, um Übersetzungen zu generieren
Die originalen und übersetzten Inhalte in einer dictionary.js-Datei speichern
Lokalisierte Inhalte durch Platzhalter ersetzen

Schritt 4. Laden des lokalisierten Inhalts

Nachdem der Compiler Ihre App verarbeitet und Übersetzungen generiert hat, müssen Sie diesen lokalisierten Inhalt laden und Ihren Benutzern bereitstellen. Dies beinhaltet:

Laden des entsprechenden Wörterbuchs basierend auf der Sprachpräferenz des Benutzers
Bereitstellen der geladenen Übersetzungen für Ihre App durch einen Context-Provider

Laden des Wörterbuchs

In Ihrer Root-Route-Datei:

Importieren Sie die Funktion loadDictionary aus lingo.dev/react/react-router:
```
import { loadDictionary } from "lingo.dev/react/react-router";
```
Diese Funktion:
- Ruft die aktuelle Locale aus dem lingo-locale Cookie ab
- Fällt auf "en" zurück, wenn keine Locale definiert ist
- Lädt den lokalisierten Inhalt aus der dictionary.js Datei

Rufen Sie die loadDictionary Funktion aus der loader Funktion auf:

import { LoaderFunctionArgs } from "react-router-dom";

export async function loader({ request }: LoaderFunctionArgs) {
  const lingoDictionary = await loadDictionary(request);
  return {
    lingoDictionary,
  };
}

Bereitstellung der Übersetzungen

In Ihrer Root-Komponente:

Importieren Sie die LingoProvider Komponente aus lingo.dev/react/client:
```
import { LingoProvider } from "lingo.dev/react/client";
```
Diese Komponente ist ein React Context Provider, der die vom Compiler erstellten Platzhalter durch den lokalisierten Inhalt ersetzt.
Holen Sie in Ihrer Root-Komponente die Daten aus dem Data Loader:
```
const data = useLoaderData<typeof loader>();
```

Umschließen Sie die App mit der LingoProvider Komponente:

<LingoProvider dictionary={data?.lingoDictionary}>
  {/* Bestehender App-Code */}
</LingoProvider>

Schritt 5. Einrichtung eines Locale-Switchers

Um Benutzern das Umschalten zwischen Locales zu ermöglichen, importieren Sie den LocaleSwitcher aus dem lingo.dev-Paket. Dies ist eine unstyled Komponente, die:

Ein Dropdown-Menü der verfügbaren Locales rendert
Benutzern die Auswahl einer Locale ermöglicht
Die ausgewählte Locale für wiederkehrende Besuche speichert

Um die Komponente zu verwenden, betten Sie sie an beliebiger Stelle in Ihrer App ein und setzen Sie die locales-Prop auf ein Array, das die konfigurierten Quell- und Ziel-Locales enthält:

import { LocaleSwitcher } from "lingo.dev/react/client";

<LocaleSwitcher locales={["en", "es"]} />;

Alternative: Benutzerdefinierter Locale-Switcher

Sie müssen nicht die LocaleSwitcher-Komponente verwenden. Sie können eine benutzerdefinierte Locale-Switching-Logik und UI implementieren. Die einzige Anforderung ist, die aktive Locale aus dem lingo-locale-Cookie zu lesen und zu schreiben.

Schritt 6. Ausführen der App

Um zu überprüfen, ob der Lingo.dev Compiler korrekt eingerichtet wurde:

Starten Sie den Entwicklungsserver:
```
npm run dev
```
Navigieren Sie zu localhost:5173.
Verwenden Sie die LocaleSwitcher-Komponente, um zwischen Locales zu wechseln.

Die Seite sollte neu geladen werden und den lokalisierten Inhalt anzeigen.

Alternative: Cookies manuell setzen

Wenn Sie die LocaleSwitcher-Komponente nicht verwenden, ist eine alternative Möglichkeit zur Überprüfung der Lokalisierungsfunktion das manuelle Setzen des lingo-locale-Cookies.

Wenn Sie Google Chrome verwenden, befolgen Sie diese Anweisungen:

Navigieren Sie zu Ansicht > Entwickler > Entwicklertools.
Gehen Sie zum Tab Anwendung.
Erweitern Sie in der linken Seitenleiste unter Speicher die Option Cookies und wählen Sie die URL der Website aus.
Klicken Sie in der Cookie-Tabelle mit der rechten Maustaste und wählen Sie Hinzufügen.
Geben Sie in der Spalte Name lingo-locale ein.
Geben Sie in der Spalte Wert die gewünschte Sprache ein (z.B. es).
Drücken Sie Enter, um das Cookie zu speichern.
Aktualisieren Sie die Seite, um das Cookie anzuwenden.

Weiterführende Lektüre

Um zu verstehen, wie der Compiler funktioniert, siehe Funktionsweise.
Um zu erfahren, wie man den Compiler konfiguriert, siehe Compiler-Optionen.