Best Practices

Empfohlene Muster und Workflows für @lingo.dev/compiler.

Entwicklungs-Workflow

Pseudotranslator standardmäßig verwenden

Empfohlen:

{
  dev: {
    usePseudotranslator: true, // Fast, free, instant feedback
  }
}

Warum:

  • Sofortiges Feedback – keine API-Latenz
  • Keine Kosten – keine API-Credits verbraucht
  • Visuelle Markierungen zeigen, was übersetzt wird
  • Testet die Benutzeroberfläche mit unterschiedlichen Textlängen

Nur deaktivieren, wenn die tatsächliche Übersetzungsqualität überprüft werden soll.

Entwicklung, CI und Produktion trennen

Entwicklung:

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: true,
  }
}

CI:

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: false,
  }
}

Produktion:

{
  buildMode: "cache-only",
}

Dieser Workflow:

  • Hält die Entwicklung schnell und kostengünstig
  • Generiert echte Übersetzungen in CI einmal pro Deployment
  • Macht Produktions-Builds deterministisch und schnell

Übersetzungsstrategie

KI die meisten Übersetzungen übernehmen lassen

Empfohlen:

<p>Welcome to our application</p>

Nicht empfohlen:

<p data-lingo-override={{ es: "...", de: "...", fr: "..." }}>
  Welcome to our application
</p>

Overrides sparsam verwenden – nur für:

  • Markennamen
  • Fachbegriffe, die spezifische Übersetzungen erfordern
  • Rechtstexte, die eine Zertifizierung erfordern
  • Marketingtexte, die eine menschliche Überprüfung benötigen

Overrides konsistent verwenden

Empfohlen:

// Consistent brand name across app
<h1 data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>
  Lingo.dev
</h1>

<p>
  Welcome to <span data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>
    Lingo.dev
  </span>
</p>

Nicht:

<h1 data-lingo-override={{ es: "Lingo.dev" }}>Lingo.dev</h1>
<p>Welcome to Lingo.dev</p> // Missing override—inconsistent

Konfiguration

Einfach beginnen

Empfohlen:

{
  sourceLocale: "en",
  targetLocales: ["es", "de"],
  models: "lingo.dev",
}

Nicht:

{
  sourceLocale: "en",
  targetLocales: ["es", "de", "fr", "pt", "it", "ja", "zh", "ar", "ru", "ko"],
  models: {
    "en:es": "groq:...",
    "en:de": "google:...",
    // Complex mappings for 10 locales
  },
  prompt: "Long custom prompt...",
  pluralization: { enabled: false },
}

Beginnen Sie mit 2-3 Zielsprachen. Fügen Sie bei Bedarf weitere hinzu. Vermeiden Sie vorzeitige Optimierung.

Lingo.dev Engine verwenden

Empfohlen:

{
  models: "lingo.dev" // Simple, optimized, supports all features
}

Nicht:

{
  models: {
    "*:*": "groq:...", // Requires manual model selection
  }
}

Lingo.dev Engine bietet:

  • Automatische Modellauswahl
  • Fallback-Behandlung
  • Translation Memory
  • Glossar-Unterstützung

Verwenden Sie direkte LLM-Provider nur, wenn Sie vollständige Kontrolle oder Kostenoptimierung benötigen.

Locale-Erkennung

Empfohlen:

{
  localePersistence: {
    type: "cookie",
    config: {
      name: "locale",
      maxAge: 31536000,
    },
  },
}

Wann anpassen:

  • localStorage erforderlich (SPA-Präferenz)
  • URL-basiertes Routing (/en/about)
  • Subdomain-Routing (es.example.com)
  • Datenbankgestützte Benutzerpräferenzen

Implementieren Sie Custom Locale Resolvers nur, wenn die Standardeinstellung nicht passt.

Versionskontrolle

.lingo/-Verzeichnis committen

Empfohlen:

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

Warum:

  • Versionskontrolle verfolgt Übersetzungsänderungen
  • Team teilt Übersetzungen
  • CI/CD verwendet committete Übersetzungen
  • Produktions-Builds benötigen keine API-Schlüssel

Commit nach CI-Durchlauf

Empfohlen (in CI):

- name: Generate translations
  run: npm run build

- name: Commit translations
  run: |
    git add .lingo/
    git commit -m "chore: update translations" || exit 0
    git push

Dies stellt sicher, dass Produktions-Builds immer aktuelle Übersetzungen haben.

CI/CD

Übersetzungen in CI generieren

Empfohlen:

# GitHub Actions
- name: Generate translations
  env:
    LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
  run: npm run build

Nicht:

# Production build without API key
- name: Build
  run: npm run build # Fails if translations missing

Generieren Sie Übersetzungen in CI, wo Sie API-Schlüssel haben. Produktions-Builds verwenden gecachte Übersetzungen.

Cache-only in Produktion verwenden

Empfohlen:

# Production build
LINGO_BUILD_MODE=cache-only npm run build

Nicht:

# Production build with translate mode
LINGO_BUILD_MODE=translate npm run build # Non-deterministic, requires API keys

Performance

Pluralisierung selektiv aktivieren

Empfohlen (wenn Sie Pluralformen verwenden):

{
  pluralization: {
    enabled: true,
  }
}

Empfohlen (wenn Sie keine Pluralformen verwenden):

{
  pluralization: {
    enabled: false, // Skip plural detection—faster builds
  }
}

Pluralisierung verursacht einen geringen Overhead (ein LLM-Aufruf pro Text mit Zahlen). Deaktivieren, falls nicht benötigt.

Schnelle Modelle für Pluralisierung verwenden

Empfohlen:

{
  pluralization: {
    enabled: true,
    model: "groq:llama-3.1-8b-instant", // Fast, cheap
  }
}

Nicht:

{
  pluralization: {
    model: "openai:gpt-4o", // Expensive overkill for plural detection
  }
}

Locale-Pair-Mapping optimieren

Empfohlen (Kostenoptimierung):

{
  models: {
    "en:es": "groq:llama-3.3-70b-versatile", // Fast & cheap
    "en:ja": "openai:gpt-4o", // High quality for complex language
    "*:*": "lingo.dev", // Fallback
  }
}

Schnelle/günstige Modelle für ähnliche Sprachen verwenden (romanische, germanische Sprachen). Hochwertige Modelle für komplexe Sprachen verwenden (CJK, Arabisch).

Testen

Zuerst mit Pseudotranslator testen

Empfohlen:

  1. Pseudotranslator aktivieren
  2. Alle UI-Komponenten testen
  3. Layout-Probleme beheben (Überlauf, Abschneidung)
  4. Dann echte Übersetzungen generieren

Grund:

  • Pseudoübersetzungen sind sofort verfügbar
  • Deckt Layout-Probleme frühzeitig auf
  • Spart API-Kosten

Alle Ziel-Locales testen

Empfohlen:

// Test with locale switcher
<LanguageSwitcher /> // Switch between all locales

// Or manually test
setLocale("es"); // Spanish
setLocale("de"); // German
setLocale("fr"); // French

Jedes Locale überprüfen:

  • Übersetzungen werden korrekt angezeigt
  • Layout berücksichtigt Textlänge
  • Kein unübersetzter Text
  • RTL-Sprachen werden korrekt gerendert (falls zutreffend)

Fehlerbehandlung

Fehlende Übersetzungen elegant behandeln

Der Compiler bricht den Build ab, wenn Übersetzungen fehlen. Dies ist beabsichtigt – besser, fehlende Übersetzungen frühzeitig zu erkennen, als eine fehlerhafte UI auszuliefern.

Falls Build fehlschlägt:

  1. Mit buildMode: "translate" ausführen, um fehlende Übersetzungen zu generieren
  2. .lingo/metadata.json committen
  3. Production-Build mit buildMode: "cache-only" erneut versuchen

Übersetzungsfehler überwachen

In CI auf Übersetzungsfehler prüfen:

- name: Generate translations
  run: npm run build 2>&1 | tee build.log

- name: Check for translation errors
  run: |
    if grep -q "Failed to generate translation" build.log; then
      echo "Translation generation failed"
      exit 1
    fi

Wartung

Regelmäßige Bereinigung

Entfernen Sie regelmäßig ungenutzte Übersetzungen:

# Backup first
cp .lingo/metadata.json .lingo/metadata.backup.json

# Manual: Search for each hash in codebase, remove if not found

# Automated (coming soon):
npx @lingo.dev/compiler clean

Dateigröße überwachen

.lingo/metadata.json wächst mit Ihrer App. Wenn die Datei zu groß wird (>5 MB):

  • Erwägen Sie die Aufteilung in mehrere Apps
  • Archivieren Sie alte Übersetzungen
  • Nutzen Sie automatisierte Bereinigung

Häufige Anti-Patterns

Verwenden Sie Overrides nicht übermäßig

Schlecht:

<p data-lingo-override={{ es: "...", de: "...", fr: "..." }}>
  Welcome to our app
</p>

Lassen Sie die KI regulären Text verarbeiten. Overrides sind für Ausnahmen gedacht.

Committen Sie keine API-Keys

Schlecht:

// next.config.ts
{
  models: "lingo.dev",
  apiKey: "your-api-key-here", // NEVER commit API keys
}

Gut:

# .env (not committed)
LINGODOTDEV_API_KEY=your_key_here

Verwenden Sie den translate-Modus nicht in der Produktion

Schlecht:

// production config
{
  buildMode: "translate", // Non-deterministic, requires API keys
}

Gut:

{
  buildMode: "cache-only", // Deterministic, no API keys
}

Überspringen Sie nicht die Versionskontrolle

Schlecht:

# .gitignore
.lingo/ # DON'T ignore translations

Gut:

# .gitignore
.env # Ignore API keys only

Migrationsstrategie

Schrittweise Einführung

Beim Hinzufügen des Compilers zu einer bestehenden App:

  1. Beginnen Sie mit 1-2 Locales
  2. Aktivieren Sie den Pseudotranslator
  3. Testen Sie alle Seiten
  4. Beheben Sie Layout-Probleme
  5. Fügen Sie weitere Locales hinzu
  6. Generieren Sie echte Übersetzungen
  7. Deployen Sie

Versuchen Sie nicht, am ersten Tag 20 Locales zu übersetzen.

Inkrementelle Einführung

Sie müssen nicht die gesamte App auf einmal übersetzen:

{
  useDirective: true, // Opt-in per file
}

Fügen Sie die 'use i18n'-Direktive zu den Dateien hinzu, die Sie übersetzen möchten:

'use i18n'; // This file gets translated

export function HomePage() {
  return <h1>Welcome</h1>;
}

Andere Dateien bleiben unübersetzt, bis Sie sie aktivieren.

Nächste Schritte