Alpha
Der Lingo.dev Compiler befindet sich in der Alpha-Phase. Er ist instabil, nicht für den Produktionseinsatz empfohlen, und APIs können sich zwischen Releases ändern.
Der Lingo.dev Compiler arbeitet mit zwei Build-Modi, die steuern, ob während des Builds neue Übersetzungen erzeugt werden. Diese Modi zu verstehen, ist entscheidend für eine zuverlässige Pipeline in Entwicklung, CI und Produktion.
Die zwei Modi#
| Modus | Verhalten | Einsatzgebiet |
|---|---|---|
"translate" | Erzeugt fehlende Übersetzungen über den konfigurierten LLM-Anbieter. Bereits zwischengespeicherte Übersetzungen werden wiederverwendet. | Entwicklung und CI – wenn neue oder geänderte Texte übersetzt werden müssen. |
"cache-only" | Verwendet ausschließlich Übersetzungen aus .lingo/metadata.json. Schlägt fehl, wenn eine Übersetzung fehlt. | Produktions-Builds – deterministische Ausgabe ohne externe API-Aufrufe. |
So funktioniert der Übersetzungsmodus#
Im Modus translate prüft der Compiler jeden übersetzbaren String anhand von .lingo/metadata.json. Wenn bereits eine zwischengespeicherte Übersetzung vorhanden ist und sich der Quelltext nicht geändert hat, wird die gecachte Version verwendet. Ist der String neu oder wurde er geändert, ruft der Compiler den konfigurierten Übersetzungsanbieter auf, erzeugt eine Übersetzung und aktualisiert den Cache.
{
buildMode: "translate",
}Dieser Modus ist standardmäßig aktiv. Er funktioniert sowohl mit dem Pseudotranslator (für sofortige Pseudo-Übersetzungen) als auch mit echten LLM-Anbietern.
So funktioniert der Cache-only-Modus#
Im Modus cache-only liest der Compiler Übersetzungen ausschließlich aus .lingo/metadata.json. Es erfolgen keine LLM-Aufrufe. Fehlt ein übersetzbarer String im Cache, schlägt der Build mit einer Fehlermeldung fehl, die die fehlenden Strings auflistet.
.lingo/metadata.json muss in die Versionskontrolle eingecheckt werden. Produktions-Builds im Modus cache-only setzen voraus, dass diese Datei im Repository vorhanden ist – nicht nur lokal generiert wurde.
{
buildMode: "cache-only",
}Dieser Modus sorgt für deterministische Builds – derselbe Quellcode und derselbe Cache liefern immer dieselbe Ausgabe. Außerdem entfallen externe API-Abhängigkeiten während des Produktions-Builds.
Empfohlener Workflow#
Entwicklung – Pseudotranslator
Aktivieren Sie den Pseudotranslator für sofortiges Feedback ohne API-Aufrufe:
{
buildMode: "translate",
dev: {
usePseudotranslator: true,
},
}Pseudo-Übersetzungen erscheinen als [!!! Welcome !!!]. So lassen sich nicht übersetzte Strings leicht erkennen und Layouts mit unterschiedlichen Textlängen testen.
CI – Übersetzungsmodus
Führen Sie den Build mit buildMode: "translate" und einem echten LLM-Anbieter aus. Der CI-Job erzeugt Übersetzungen für alle neuen oder geänderten Strings und committed die aktualisierte .lingo/metadata.json zurück ins Repository.
# CI environment
LINGO_BUILD_MODE=translate npm run buildProduktion – Cache-only-Modus
Stellen Sie mit buildMode: "cache-only" bereit, um ausschließlich vorab generierte Übersetzungen zu verwenden. In der Produktionsumgebung werden keine API-Schlüssel benötigt.
# Production environment
LINGO_BUILD_MODE=cache-only npm run buildÜberschreibung per Umgebungsvariable#
Die Umgebungsvariable LINGO_BUILD_MODE überschreibt die Konfigurationsoption buildMode. So können Sie dieselbe Konfigurationsdatei in verschiedenen Umgebungen verwenden:
# Override in any environment
LINGO_BUILD_MODE=cache-only npm run buildDie Umgebungsvariable hat Vorrang vor dem Wert in der Konfigurationsdatei.
CI-Beispiele#
# .github/workflows/translate.yml
name: Generate Translations
on:
push:
branches: [main]
jobs:
translate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm run build
env:
LINGO_BUILD_MODE: translate
LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
- uses: stefanzweifel/git-auto-commit-action@v5
with:
commit_message: "chore: update translations"
file_pattern: ".lingo/metadata.json"Committen Sie .lingo/metadata.json immer in die Versionskontrolle. Produktions-Builds im Modus cache-only sind auf diese Datei angewiesen. Fehlt sie oder ist sie unvollständig, schlägt der Build fehl.
