verbatra translate

Maschinell übersetzte Seite

Diese Seite wurde automatisch übersetzt und kann daher Fehler oder seltsame Formulierungen enthalten. Die englische Version ist die maßgebliche Quelle. Das englische Original lesen.

Führe einen Übersetzungsdurchlauf über jedes Ziel-Locale aus; danach beendet sich der Befehl. translate liest das Quell-Locale, vergleicht es mit der Lock-Datei, schickt nur die neuen oder geänderten Strings an den Provider, führt die Integritätsprüfungen aus, schreibt die Locale-Dateien und aktualisiert das Lock. Was noch aktuell ist, wird nie erneut gesendet; du zahlst also nie zweimal für einen unveränderten String.

Synopsis

verbatra translate [flags]

Flags

Flag	Argument	Standard	Wirkung
`--cwd`	`<path>`	aktuelles Verzeichnis	Konfiguration und Locale-Dateien von diesem Verzeichnis aus auflösen
`--config`	`<path>`	wird gesucht	diese Konfigurationsdatei laden, statt eine zu suchen
`--locales`	`<list>`	jede konfigurierte Ziel-Locale	nur diese kommagetrennte Teilmenge übersetzen; ein nicht konfiguriertes Locale lässt den Lauf mit `UNKNOWN_LOCALE` scheitern, bevor irgendetwas gelesen oder ein kostenpflichtiger Provider-Aufruf gemacht wird, und eine leere Liste ist ein Verwendungsfehler, Exit `2`
`--dry-run`	keins	aus	Änderungen ansehen, ohne einen Provider aufzurufen oder Dateien zu schreiben (kein API-Key nötig)
`--prune`	keins	die `prune`-Option der Konfiguration, sonst aus	verwaiste Keys (in einer Zieldatei, aber nicht in der Quelle) aus der geschriebenen Datei und dem Lock entfernen
`--lock-timeout`	`<seconds>`	`600`	wie lange auf eine gehaltene Schreibsperre eines Locales gewartet wird, bevor der Lauf scheitert; muss eine reine positive Ganzzahl von Sekunden sein (ein Wert wie `60s`, `0` oder `-1` ist ein Nutzungsfehler, Exit `2`)
`--concurrency`	`<n>`	`1`	bis zu `n` Ziel-Locales gleichzeitig übersetzen; muss eine positive Ganzzahl sein
`--no-cache`	keins	aus (Cache an)	den lokalen Translation-Memory-Cache (`verbatra.cache.json`) für diesen Lauf umgehen
`--json`	keins	aus	einen JSON-Envelope auf stdout ausgeben, der die Lauf-Zusammenfassung unter `result` trägt (die `RunSummary`-Form), oder bei einem fehlgeschlagenen Lauf den Fehlercode; die menschenlesbare Fehlerzeile geht weiter auf stderr

Standardmäßig löscht ein Lauf nichts: verwaiste Keys werden gemeldet und bleiben stehen. --prune entfernt genau diese Keys und sonst nichts und übersteuert für diesen Lauf die prune-Option der Konfiguration. Vor dem Lauf lädt translate .env.local und dann .env aus dem Arbeitsverzeichnis; eine bereits in der echten Umgebung gesetzte Variable gewinnt.

--dry-run baut überhaupt keinen Provider auf, braucht also keinen API-Key und kann nichts ausgeben: Es liest Quell- und Zieldateien, vergleicht sie mit der Lock-Datei und meldet genau, was ein echter Lauf ändern würde. Es schreibt nichts (keine Locale-Datei, keine Lock-Aktualisierung, keinen Run-Status-Schnappschuss), es liest und schreibt den Cache nicht und es nimmt keine Schreibsperre pro Locale, wartet also nie auf einen bereits laufenden Lauf. Das Laden von .env oben passiert auf einem Dry-Run weiterhin; es gibt nur keinen Schlüssel zu lesen. Damit ist es ein vollwertiger Weg, verbatra an einem echten Projekt auszuprobieren, bevor du ein Provider-Konto anlegst.

--locales de,fr grenzt den Lauf auf eine Teilmenge der konfigurierten Ziele ein. Ausgelassene Locales bleiben unberührt: ihre Dateien, ihre Lock-Einträge und ihre Cache-Einträge bleiben, wie sie waren. Es ist das Flag für ein ratenbegrenztes kostenloses Kontingent, wo ein Locale nach dem anderen der einzige Weg durch ist, und zugleich der schnellste Weg, ein einzelnes partial gebliebenes Locale erneut laufen zu lassen. Der Run-Status-Schnappschuss beschreibt immer nur den jüngsten Lauf; ein Teilmengen-Lauf grenzt ihn also auf diese Teilmenge ein.

--lock-timeout stellt ein, wie lange ein Locale auf eine umkämpfte Schreibsperre wartet, bevor der Lauf mit LOCK_CONTENDED scheitert: erhöhe es, wenn ein anderer Lauf die Sperre berechtigt eine Weile hält, senke es, um in CI schnell zu scheitern.

--concurrency übersetzt mehrere Ziel-Locales parallel, um ein großes Projekt schneller abzuschließen. Es wird mit Exit 2 abgelehnt, wenn die Konfiguration ein maxTokens-Budget setzt, weil parallele Locales ein Token-Limit nicht deterministisch einhalten können (ein Dry-Run ist ausgenommen). Taucht ein Fehler des gesamten Laufs (in der Praxis eine beschädigte Lock-Datei) auf, während bereits Locales laufen, wird kein weiteres Locale mehr gestartet, und die laufenden schließen ab und geben ihre Schreibsperren frei, bevor der Befehl mit Exit 2 endet; der Lauf lässt also keine Sperre zurück, auf die der nächste warten müsste. Während ein Lauf fortschreitet, wird der Fortschritt auf stderr ausgegeben (eine Zeile pro Locale-Start, Provider-Sub-Batch und Locale-Ende), sodass der stdout eines --json-Laufs eine einzige saubere Zusammenfassung bleibt. --no-cache überspringt den Translation-Memory-Cache für den Lauf und macht genau die Provider-Aufrufe, die es ohne vorhandenen Cache machen würde.

Beispiele

# translate once using the config it finds
verbatra translate

# preview the keys that would be pruned, spending nothing
verbatra translate --prune --dry-run

# one locale at a time, which is what a rate-limited free tier needs
verbatra translate --locales de

Exit-Codes

Code	Bedeutung
`0`	jedes Ziel-Locale kam vollständig durch
`1`	der Lauf lief durch, aber ein oder mehrere Locales schlugen fehl oder blieben `partial`
`2`	konnte nicht laufen: ein Fehler des gesamten Laufs (Konfiguration, Quelle, Format, Provider oder Lock) oder ein Verwendungsfehler

Ein fehlschlagendes Locale ist nicht fatal: der Lauf läuft zu Ende, endet mit 1, und das Detail pro Locale steht in der Zusammenfassung. Ein Locale mit dem Status partial endet ebenfalls mit 1. Das ist ein Locale, dessen Datei geschrieben wurde, dem aber weiterhin Keys fehlen, typischerweise weil ein Provider-Sub-Batch fehlschlug oder das Integritäts-Gate eine Übersetzung abgelehnt hat; es als Erfolg auszuliefern würde eine halb übersetzte Datei unbemerkt in deinem Repository liegen lassen.

Siehe auch

Wie es funktioniert erklärt die Pipeline aus Lesen, Diffen, Übersetzen, Schreiben.
Der Cache erklärt, was --no-cache umgeht und wie die Wiederverwendung eingegrenzt ist.
Übersetzungssicherheit behandelt die Integritätsprüfungen und die Review-Warteschlange.
verbatra diff zeigt dieselben ausstehenden Keys schreibgeschützt an.
CI und Exit-Codes zeigt, wie du auf diese Codes verzweigst.

Edit on GitHub