Fehlerbehebung

Häufige Probleme und Lösungen bei der Verwendung von @lingo.dev/compiler.

Installationsprobleme

"Cannot find module '@lingo.dev/compiler'"

Ursache: Paket nicht installiert oder fehlerhaft installiert.

Lösung:

npm install @lingo.dev/compiler
# or
pnpm install @lingo.dev/compiler

Installation überprüfen:

ls node_modules/@lingo.dev/compiler

"Module not found: Can't resolve '@lingo.dev/compiler/react'"

Ursache: Import aus falschem Pfad oder veraltetes Paket.

Lösung:

  1. Import-Anweisung überprüfen:

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

  2. Paket neu installieren:

    rm -rf node_modules
npm install

Konfigurationsprobleme

"Config must be async function" (Next.js)

Ursache: Next.js-Konfiguration ist nicht in einer async-Funktion gekapselt.

Lösung:

// Wrong
export default withLingo(nextConfig, {...});

// Correct
export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {...});
}

"sourceLocale is required"

Ursache: Fehlende sourceLocale in der Konfiguration.

Lösung:

{
  sourceLocale: "en", // Required
  targetLocales: ["es", "de"],
}

"targetLocales must be an array"

Ursache: targetLocales ist kein Array oder ist leer.

Lösung:

{
  targetLocales: ["es", "de"], // Must be array with at least one locale
}

Übersetzungsprobleme

Übersetzungen werden nicht angezeigt

Symptome: Text erscheint nur in der Ausgangssprache.

Ursachen und Lösungen:

1. LingoProvider nicht hinzugefügt oder an falscher Stelle

// Wrong - too low in tree
export default function Page() {
  return (
    <LingoProvider>
      <Content />
    </LingoProvider>
  );
}

// Correct - in root layout
export default function RootLayout({ children }) {
  return (
    <LingoProvider>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

2. Fehlende Übersetzungen in den Metadaten Prüfen Sie .lingo/metadata.json:

{
  "translations": {
    "abc123": {
      "locales": {
        "es": "..." // Should have translation
      }
    }
  }
}

Falls leer oder fehlend, führen Sie mit buildMode: "translate" aus:

npm run dev # or build

3. Build-Modus ist cache-only ohne zwischengespeicherte Übersetzungen

# Generate translations first
LINGO_BUILD_MODE=translate npm run build

# Then use cache-only
LINGO_BUILD_MODE=cache-only npm run build

Übersetzungen sind alle "[!!! ...]"

Ursache: Pseudotranslator ist aktiviert.

Lösung:

{
  dev: {
    usePseudotranslator: false, // Disable for real translations
  }
}

Starten Sie den Dev-Server neu.

Einige Texte werden nicht übersetzt

Ursachen:

1. Dynamischer Inhalt oder Props

// Not translated (yet) - string in variable
const title = "Welcome";
<h1>{title}</h1>

// Translated - string in JSX
<h1>Welcome</h1>

Lösung: Der Compiler wird erweitert, um String-Literale zu unterstützen. Fügen Sie den Text vorerst direkt in JSX ein.

2. Text in Attributen erfordert spezielle Behandlung

// Translated automatically
<img alt="Logo" />
<button aria-label="Close" />

// May need explicit handling
<div custom-attr="Some text" /> // Not translated unless configured

3. useDirective ist aktiviert Wenn useDirective: true, werden Dateien ohne 'use i18n' nicht übersetzt.

Lösung: Direktive hinzufügen:

'use i18n';

export function Component() { ... }

Build-Probleme

"Fehlende Übersetzungen für Locale X"

Ursache: buildMode: "cache-only", aber Übersetzungen fehlen.

Lösung:

  1. Übersetzungen generieren:

    npm run dev # or
LINGO_BUILD_MODE=translate npm run build

  2. .lingo/metadata.json committen

  3. Mit cache-only erneut versuchen

"Generierung der Übersetzung fehlgeschlagen"

Ursachen:

1. Ungültiger API-Key

# Check .env file
cat .env | grep API_KEY

Stellen Sie sicher, dass der API-Key für Ihren Provider korrekt ist.

2. Netzwerkprobleme API-Verbindung testen:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

3. Rate-Limiting Übersetzungsgenerierung verlangsamen oder API-Tier upgraden.

4. Ungültige Modellkonfiguration

// Wrong
{
  models: {
    "*:*": "invalid-provider:model",
  }
}

// Correct
{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",
  }
}

Build ist langsam

Ursachen:

1. Viele Übersetzungen werden generiert Erster Build mit neuem Text ist langsam. Nachfolgende Builds sind schnell (gecacht).

2. Pseudotranslator in Entwicklung deaktiviert

{
  dev: {
    usePseudotranslator: true, // Enable for fast development
  }
}

3. Pluralisierung unnötigerweise aktiviert

{
  pluralization: {
    enabled: false, // Disable if not using plural forms
  }
}

HMR-Probleme

HMR funktioniert nicht

Ursache: Platzierung des LingoProvider oder Framework-Konfiguration.

Lösungen:

Next.js: Stellen Sie sicher, dass der LingoProvider im Root-Layout und nicht in verschachtelten Layouts platziert ist.

Vite: Stellen Sie sicher, dass lingoCompilerPlugin vor dem react()-Plugin platziert ist:

plugins: [
  lingoCompilerPlugin({...}), // Before react plugin
  react(),
]

State wird bei Übersetzungsänderung zurückgesetzt

Ursache: Seitenneuladung wird durch Locale-Änderung ausgelöst.

Erwartetes Verhalten: setLocale() lädt die Seite standardmäßig neu, um die neue Locale anzuwenden.

Um Neuladung zu vermeiden: Implementieren Sie eine benutzerdefinierte persistLocale ohne Neuladung:

// .lingo/locale-resolver.client.ts
export function persistLocale(locale: string): void {
  localStorage.setItem("locale", locale);
  // Don't call window.location.reload()
}

Hinweis: Dies erfordert das Vorladen der Übersetzungen für alle Locales.

API-/Auth-Probleme

"API-Key ungültig"

Lösungen:

1. Umgebungsvariablenname überprüfen

# Lingo.dev Engine
LINGODOTDEV_API_KEY=...

# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

2. Überprüfen Sie, ob der API-Key aktiv ist Melden Sie sich im Provider-Dashboard an und überprüfen Sie den Key-Status.

3. Dev-Server nach Hinzufügen des Keys neu starten

npm run dev

Umgebungsvariablen werden beim Start geladen.

"Authentifizierung fehlgeschlagen" (Lingo.dev)

Lösungen:

1. Erneut authentifizieren

npx lingo.dev@latest login

2. Manueller API-Schlüssel

# Add to .env
LINGODOTDEV_API_KEY=your_key_here

Schlüssel aus den Projekteinstellungen von lingo.dev abrufen.

Browser blockiert Authentifizierungsablauf

Ursache: Brave-Browser oder Erweiterungen blockieren die Authentifizierung.

Lösung: API-Schlüssel manuell zu .env hinzufügen:

LINGODOTDEV_API_KEY=...

Server-Probleme

"Übersetzungsserver konnte nicht gestartet werden"

Ursache: Ports 60000-60099 sind alle belegt.

Lösungen:

1. Anderen Port-Bereich konfigurieren

{
  dev: {
    translationServerStartPort: 61000,
  }
}

2. Bestehende Prozesse beenden

# Find processes using ports
lsof -i :60000-60099

# Kill process
kill -9 <PID>

"Port 60000 bereits in Verwendung"

Ursache: Ein anderer Prozess verwendet diesen Port.

Lösung: Der Server findet automatisch den nächsten verfügbaren Port. Tatsächlichen Port in der Konsole prüfen:

[lingo] Translation server started on port 60001

Wenn alle Ports belegt sind, siehe "Übersetzungsserver konnte nicht gestartet werden" oben.

Typfehler

"Property 'data-lingo-override' does not exist"

Ursache: TypeScript erkennt das Attribut nicht.

Lösung: Typdeklaration hinzufügen:

// global.d.ts
declare namespace React {
  interface HTMLAttributes<T> {
    "data-lingo-override"?: Record<string, string>;
  }
}

Oder Anführungszeichen verwenden:

<div {"data-lingo-override"}={{ es: "..." }}>
  Text
</div>

"Type error: Config must return Promise"

Ursache: Next.js-Konfiguration ist nicht korrekt typisiert.

Lösung:

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

Produktionsprobleme

Übersetzungen fehlen in Produktion

Ursachen:

1. .lingo/ nicht committed

git add .lingo/
git commit -m "chore: add translations"
git push

2. Produktions-Build-Modus ist falsch

// Should be cache-only in production
{
  buildMode: "cache-only",
}

3. CI hat keine Übersetzungen generiert CI-Logs prüfen – sicherstellen, dass Übersetzungen generiert und committed wurden.

Unterschiedliche Übersetzungen in Dev vs. Prod

Ursache: Pseudotranslator ist in Produktion aktiviert.

Lösung:

{
  dev: {
    usePseudotranslator: process.env.NODE_ENV === "development", // Only in dev
  }
}

Hilfe erhalten

Falls Sie weiterhin nicht weiterkommen:

  1. Logs prüfen – Nach Fehlermeldungen in der Konsole suchen
  2. .lingo/metadata.json prüfen – Struktur und Inhalte verifizieren
  3. Mit Pseudotranslator testen – API-Probleme isolieren
  4. GitHub-Issues prüfen – github.com/lingodotdev/lingo.dev/issues
  5. Auf Discord fragen – discord.gg/lingo

Wenn Sie um Hilfe bitten, geben Sie Folgendes an:

  • Fehlermeldung (vollständiger Stack-Trace)
  • Konfiguration (next.config.ts oder vite.config.ts)
  • Paketversionen (npm list @lingo.dev/compiler)
  • Schritte zur Reproduktion

Häufige Fragen

F: Benötige ich API-Schlüssel in der Produktion? A: Nein, mit buildMode: "cache-only". Übersetzungen werden in der CI vorab generiert.

F: Warum schlägt mein Build fehl? A: Prüfen Sie die Fehlermeldung. Häufige Ursachen: fehlende Übersetzungen, ungültiger API-Schlüssel, Netzwerkprobleme.

F: Kann ich mehrere LLM-Provider verwenden? A: Ja, mit Locale-Pair-Mapping in der models-Konfiguration.

F: Wie kann ich ohne API-Kosten testen? A: Aktivieren Sie usePseudotranslator: true in der Entwicklung.

Nächste Schritte