Schnellstart für TanStack Start

Wie man den Lingo.dev Compiler mit TanStack Start einrichtet

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 Sie Lingo.dev Compiler mit TanStack Start einrichten.

Was Sie lernen werden

  • Wie man Lingo.dev Compiler in einem TanStack Start-Projekt initialisiert
  • Wie man den Compiler für Ihre TanStack Start-App 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.

So richten Sie einen API-Schlüssel ein:

  1. Melden Sie sich bei Lingo.dev Engine an.

  2. Navigieren Sie zur Seite Projects.

  3. Klicken Sie auf API key > Copy.

  4. 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

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

  1. Importieren Sie den Compiler:

    import lingoCompiler from "lingo.dev/compiler";

  2. 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",
});

    Um mehr über die verfügbaren Optionen zu erfahren, siehe Compiler-Optionen.

  3. Wenden Sie die Compiler-Konfiguration auf Ihre Basiskonfiguration an:

    export default defineConfig(withLingo(baseConfig));

Mit dieser Konfiguration wird der Lingo.dev Compiler:

  • Den Abstract Syntax Tree (AST) des Quellcodes durchlaufen
  • Lokalisierbare Inhalte finden (z.B. Text in JSX-Elementen und bestimmte Attributwerte)
  • 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 Spracheinstellung des Benutzers
  • Bereitstellen der geladenen Übersetzungen für Ihre App durch einen Context-Provider

In der Datei src/routes/__root.tsx:

  1. Importieren Sie die Komponente LingoProviderWrapper und die Funktion loadDictionary aus lingo.dev/react/client:

    import {
  LingoProviderWrapper,
  loadDictionary,
} from "lingo.dev/react/client";

    Die LingoProviderWrapper-Komponente ist ein Context-Provider, der die vom Compiler erstellten Platzhalter durch den lokalisierten Inhalt ersetzt.

    Die loadDictionary-Funktion:

    • Ruft die aktuelle Sprache aus dem lingo-locale-Cookie ab
    • Fällt auf "en" zurück, wenn keine Sprache definiert ist
    • Lädt den lokalisierten Inhalt aus der dictionary.js-Datei

  2. Umschließen Sie den Inhalt Ihrer App mit der LingoProviderWrapper-Komponente innerhalb der RootDocument-Komponente:

    function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        <LingoProviderWrapper
          loadDictionary={(locale) => loadDictionary(locale)}
        >
          {children}
        </LingoProviderWrapper>
        <Scripts />
      </body>
    </html>
  );
}

Schritt 5. Einrichten eines Locale-Switchers

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

  • Ein Dropdown-Menü mit verfügbaren Sprachen rendert
  • Benutzern die Auswahl einer Sprache ermöglicht
  • Die ausgewählte Sprache für zukünftige 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 Zielsprachen 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 Logik und UI für den Sprachwechsel implementieren. Die einzige Voraussetzung ist, dass die aktive Sprache aus dem lingo-locale Cookie gelesen und in diesen geschrieben wird.

Schritt 6. Ausführen der App

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

  1. Starten Sie den Entwicklungsserver:

    npm run dev

  2. Navigieren Sie zu localhost:3000.

  3. Verwenden Sie die LocaleSwitcher Komponente, um zwischen den Sprachen zu wechseln.

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

Alternative: Cookies manuell setzen

Wenn Sie die LocaleSwitcher Komponente nicht verwenden, können Sie alternativ überprüfen, ob die Lokalisierung funktioniert, indem Sie den lingo-locale Cookie manuell setzen.

Wenn Sie Google Chrome verwenden, folgen Sie diesen Anweisungen:

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

Weiterführende Lektüre