Build-Modi

@lingo.dev/compiler unterstützt zwei Build-Modi, die steuern, wann und wie Übersetzungen generiert werden.

Modi-Übersicht

ModusWann verwendenAPI-AufrufeVerhalten
translateEntwicklung, CIJaGeneriert fehlende Übersetzungen mit konfiguriertem LLM
cache-onlyProduktions-BuildsNeinVerwendet nur gecachte Übersetzungen aus .lingo/metadata.json

Translate-Modus

Zweck: Übersetzungen bei Bedarf während des Builds generieren.

{
  buildMode: "translate"
}

Verhalten:

  • Scannt Code nach übersetzbarem Text
  • Prüft .lingo/metadata.json auf vorhandene Übersetzungen
  • Generiert fehlende Übersetzungen über konfigurierten LLM-Provider
  • Aktualisiert .lingo/metadata.json mit neuen Übersetzungen
  • Build schlägt fehl, wenn Übersetzungsgenerierung fehlschlägt

Wann verwenden:

  • Lokale Entwicklung (mit usePseudotranslator: true)
  • CI/CD-Pipelines (mit echten LLM-Providern)
  • Ersteinrichtung und Übersetzungsgenerierung

Erfordert:

  • Gültigen API-Key für konfigurierten Provider (oder aktivierten Pseudotranslator)
  • Netzwerkverbindung zum LLM-Provider

Cache-Only-Modus

Zweck: Build nur mit vorgeneriertem Übersetzungen durchführen.

{
  buildMode: "cache-only"
}

Verhalten:

  • Liest Übersetzungen aus .lingo/metadata.json
  • Keine API-Aufrufe durchgeführt
  • Build schlägt fehl, wenn Übersetzungen für eine Locale fehlen
  • Schnelle, deterministische Builds

Wann verwenden:

  • Produktions-Builds
  • Deployments ohne API-Keys
  • Umgebungen mit eingeschränktem Netzwerkzugriff

Erfordert:

  • .lingo/metadata.json mit Übersetzungen für alle Locales
  • Übersetzungen in CI oder Entwicklung vorgeneriert

Empfohlener Workflow

1. Lokale Entwicklung

Verwenden Sie Pseudotranslator für sofortiges Feedback:

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

Vorteile:

  • Sofortige Fake-Übersetzungen
  • Keine API-Kosten
  • Sehen Sie genau, was übersetzt wird
  • Testen Sie UI mit variierenden Textlängen

2. CI/CD-Pipeline

Echte Übersetzungen in CI generieren:

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

Einrichtung in CI:

# GitHub Actions example
- name: Install dependencies
  run: pnpm install

- name: Generate translations
  env:
    LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
  run: pnpm run build

- name: Commit translations
  run: |
    git config user.name "github-actions[bot]"
    git config user.email "github-actions[bot]@users.noreply.github.com"
    git add .lingo/
    git commit -m "chore: update translations" || exit 0
    git push

Vorteile:

  • Echte Übersetzungen werden einmal pro Deployment generiert
  • In Versionskontrolle committet
  • Produktions-Builds benötigen keine API-Schlüssel

3. Produktions-Build

Nur gecachte Übersetzungen verwenden:

{
  buildMode: "cache-only",
}

Vorteile:

  • Keine API-Schlüssel erforderlich
  • Schnelle Builds
  • Deterministisch – gleiche Eingabe erzeugt immer gleiche Ausgabe
  • Keine externen Netzwerkabhängigkeiten

Überschreiben der Umgebungsvariable

Build-Modus über Umgebungsvariable überschreiben:

# Force cache-only mode
LINGO_BUILD_MODE=cache-only npm run build

# Force translate mode
LINGO_BUILD_MODE=translate npm run build

Dies ist nützlich für Deployment-Umgebungen, in denen Sie Cache-Only erzwingen möchten, ohne die Konfiguration zu ändern.

Umgang mit fehlenden Übersetzungen

Im Translate-Modus

Wenn die Übersetzung fehlschlägt:

Error: Failed to generate translation for locale "es":
  - Hash: abc123def
  - Source text: "Welcome to our app"
  - Provider: lingo.dev
  - Reason: API key invalid

Lösung: API-Schlüssel korrigieren, Build erneut ausführen.

Im Cache-Only-Modus

Wenn Übersetzungen fehlen:

Error: Missing translations for locale "es":
  - Hash: abc123def
  - Source text: "Welcome to our app"
  - File: app/page.tsx:12

Run with buildMode: "translate" to generate missing translations.

Lösung: Führen Sie einen Build mit translate-Modus aus, um fehlende Übersetzungen zu generieren, und committen Sie dann .lingo/.

Inkrementelle Übersetzung

Der Compiler verwendet Content-Hashing, um zu bestimmen, was übersetzt werden muss:

  1. Jeder übersetzbare String erhält einen stabilen Hash
  2. Hash basiert auf Quelltext + Kontext
  3. Wenn Hash in .lingo/metadata.json existiert, wird Übersetzung wiederverwendet
  4. Nur neuer oder geänderter Text löst erneute Übersetzung aus

Ergebnis: Sie zahlen nur einmal für Übersetzungen. Nachfolgende Builds verwenden gecachte Übersetzungen wieder.

CI-Konfigurationsbeispiele

GitHub Actions

name: Generate Translations

on:
  push:
    branches: [main]
  pull_request:

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v2
        with:
          version: 8

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "pnpm"

      - name: Install dependencies
        run: pnpm install

      - name: Generate translations
        env:
          LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
        run: pnpm run build

      - name: Commit translations
        if: github.event_name == 'push'
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add .lingo/
          git diff --quiet && git diff --staged --quiet || git commit -m "chore: update translations"
          git push

GitLab CI

stages:
  - translate

generate-translations:
  stage: translate
  script:
    - pnpm install
    - pnpm run build
    - git config user.name "GitLab CI"
    - git config user.email "[email protected]"
    - git add .lingo/
    - git diff --quiet && git diff --staged --quiet || git commit -m "chore: update translations"
    - git push origin HEAD:$CI_COMMIT_REF_NAME
  only:
    - main

Häufige Fragen

Benötige ich API-Keys in Production? Nein. Verwenden Sie buildMode: "cache-only" in Production. Übersetzungen werden in CI vorgeneriert.

Was passiert, wenn ich vergesse, Übersetzungen in CI zu generieren? Production-Build schlägt mit einer klaren Fehlermeldung fehl, die fehlende Übersetzungen auflistet. Generieren Sie diese in CI, committen Sie und deployen Sie erneut.

Kann ich den Translate-Modus in Production verwenden? Ja, aber nicht empfohlen. Es macht Builds nicht-deterministisch und erfordert API-Keys in Production. Besser ist es, Übersetzungen in CI zu generieren.

Wie teste ich den Cache-Only-Modus lokal?

  1. Generieren Sie Übersetzungen mit translate-Modus
  2. Wechseln Sie zu cache-only-Modus
  3. Führen Sie Build aus – sollte mit gecachten Übersetzungen erfolgreich sein

Was passiert, wenn sich mein Quelltext ändert? Der Hash ändert sich, sodass eine neue Übersetzung generiert wird (im translate-Modus). Alte Übersetzung wird in .lingo/metadata.json für die Historie behalten.

Soll ich .lingo/ in Git committen? Ja. Das .lingo/-Verzeichnis sollte versionskontrolliert werden. Es enthält Ihren Übersetzungs-Cache.

Nächste Schritte