Review in Studio

Verbatra Studio ist ein lokales Dashboard über deinem verbatra-Projekt: es zeigt den Zustand jedes Locales live, lässt dich Übersetzungen von Hand korrigieren und kann einzelne Keys neu übersetzen, wenn du es erlaubst. Diese Anleitung geht den Review-Workflow von Anfang bis Ende durch.

Die Haltung, die du dabei im Kopf behalten solltest: lokales Bearbeiten ist immer an, abgesichert nur durch dieselben Platzhalter- und ICU-Prüfungen wie jeder andere Schreibvorgang. Kostenpflichtige Provider-Aufrufe sind nie standardmäßig an; die Aktionen zum Neuübersetzen und zum Übersetzen ausstehender Änderungen existieren nur, wenn du Studio mit --allow-spend startest.

Starte Studio

Studio kommt als eigenes Paket und wird über die CLI erreicht:

pnpm add -D @verbatra/studio
verbatra studio

Der Befehl gibt eine Zeile aus und läuft weiter:

Verbatra Studio running at http://127.0.0.1:5849/?token=...

Öffne genau diese URL, inklusive Token; das Token wird bei jedem Start frisch erzeugt und ist die Art, wie sich der Browser authentifiziert. Der Server bindet sich nur an 127.0.0.1 (nie an dein Netzwerk), nutzt standardmäßig Port 5849 ohne Ausweichport, wenn dieser belegt ist, und nimmt --port zum Umziehen. Stoppe ihn mit Ctrl+C; ein zweiter Interrupt erzwingt das Ende mit Exit-Code 130. Alle Flags stehen unter verbatra studio.

Die Seitenleiste hat vier Seiten: Übersetzungen, Review, Aktivität und Einstellungen.

Lies die Seite Übersetzungen

Übersetzungen ist die Arbeitsansicht: alles Ausstehende über deine Ziel-Locales hinweg, und wie weit jedes Locale ist.

• Die Statistikleiste beantwortet die erste Frage auf einen Blick: wie viele Keys Aufmerksamkeit brauchen, die durchschnittliche Abdeckung, wie viele Locales synchron sind und der Token-Verbrauch des letzten Laufs. Wenn nichts aussteht, ersetzt ein Alles-erledigt-Banner den Key-Explorer.
• Der Key-Explorer listet jeden fehlenden, geänderten und verwaisten Key, als Raster Key mal Locale oder als Listen pro Locale mit einem Key-Filter.
• Die Locale-Tabelle zeigt die Abdeckung pro Locale (fehlend, veraltet, aktuell), zusammengeführt mit dem Zustand der Lock-Datei, damit du siehst, ob der Lock-Eintrag jedes Locales mit seinen Dateien übereinstimmt.

Klicke auf einen beliebigen Key, um seine Detailansicht zu öffnen: die Werte pro Locale, der Sync-Status jedes Locales und ein Integritätshinweis pro Übersetzung (Platzhalter stimmen, Platzhalter-Abweichung mit den fehlenden und überzähligen Tokens beim Namen genannt, oder ungültige Nachrichtensyntax). Von dort öffnet Edit den Editor für den Wert eines Locales.

Bearbeiten mit Integritäts-Gate

Der Editor zeigt den Quellstring und ein Textfeld, vorbefüllt mit der aktuellen Übersetzung. Speichern schickt den Wert durch dasselbe Gate wie jeder andere verbatra-Schreibvorgang: ein Wert, der einen Platzhalter fallen lässt oder erfindet oder die Struktur einer ICU-Nachricht bricht, wird mit benanntem Grund abgelehnt, und nichts wird geschrieben. Eine akzeptierte Bearbeitung schreibt die Locale-Datei und rückt den Lock-Eintrag des Keys vor, genau wie eine akzeptierte Import-Zeile.

Bearbeiten braucht kein Flag. Es berührt nur deine lokalen Dateien und ruft nie einen Provider auf.

Arbeite die Review-Warteschlange ab

Die Seite Review listet jeden Eintrag, den die Review-Heuristiken im letzten translate- oder watch-Lauf markiert haben: eine Zeile pro Locale und Key, mit einem Hinweis pro Grund (Übersetzung deutlich kürzer oder länger als die Quelle, identisch mit der Quelle, ein verpasster Glossarbegriff, umgeordnete Platzhalter oder ein degradierter Provider-Batch). Solange kein Lauf aufgezeichnet wurde, sagt die Seite das und bleibt leer; führe verbatra translate oder verbatra watch aus, um sie zu füllen.

Filtere nach Locale oder Key-Teilstring, dann arbeite die Zeilen ab:

• Edit öffnet denselben integritätsgesicherten Editor wie die Seite Übersetzungen. Eine akzeptierte Bearbeitung entfernt die Zeile aus der Warteschlange.
• Approve verwirft die Zeile als "angesehen, passt so".
• Reject verwirft die Zeile ebenfalls; kombiniere es mit einer Bearbeitung oder einer Neuübersetzung, wenn sich der Wert wirklich ändern muss.

Approve und Reject gelten nur für die Sitzung: sie verbergen die Zeile für den Rest dieser Browser-Sitzung (auch über Live-Refreshes hinweg), schreiben aber nichts auf die Platte. Die dauerhaften Wege, ein Flag loszuwerden, sind den Wert zu korrigieren oder eine Übersetzung neu laufen zu lassen.

Review-Flags sind Hinweise, getrennt vom harten Integritäts-Gate; was jeder Grund bedeutet, steht in Übersetzungssicherheit.

Übersetze einen markierten Key neu

Starte Studio mit erlaubten Ausgaben:

verbatra studio --allow-spend

(Oder setze VERBATRA_STUDIO_ALLOW_SPEND=1; das Flag gewinnt, wenn beides gesetzt ist. Der API-Key des Providers kommt wie immer aus der Umgebung, nie aus Studio.)

Jetzt bekommt ein Key, dessen Integritätshinweis einen echten Defekt zeigt (eine Platzhalter-Abweichung oder ungültige Nachrichtensyntax), einen Retranslate-Button in seiner Detailansicht auf der Seite Übersetzungen. Er macht einen Provider-Aufruf für genau dieses Locale und diesen Key, schickt das Ergebnis durch das Integritäts-Gate, bevor irgendetwas die Platte erreicht, und meldet das Ergebnis neben dem Button. Der aktualisierte Wert fließt dann über die Live-Refresh-Schleife in die Oberfläche.

Ohne --allow-spend fehlt der Button vollständig, und der Server registriert den Retranslate-Endpunkt gar nicht erst: Ausgaben, die du beim Start nicht gewährt hast, lassen sich nicht aus dem Browser einschalten.

Übersetze ausstehende Änderungen

Studio beobachtet deine Quelldatei, jede Ziel-Locale-Datei und die Lock-Datei, solange es läuft. Ändert sich eine davon, aktualisiert sich jede offene Seite von selbst, und ein Toast nennt, was sich geändert hat, mit einem Key-Delta aus hinzugefügt, geändert und entfernt.

Wenn sich die Quelldatei ändert und Studio mit --allow-spend läuft, bietet dieser Toast zusätzlich Translate pending changes across all locales an: einen vollen Übersetzungslauf über alles derzeit Ausstehende, dieselbe Arbeit, die verbatra translate erledigen würde. Der Button meldet Erfolg, Fehlschläge pro Locale oder den Fehler direkt an Ort und Stelle.

Diese Live-Schleife heißt auch, dass Studio gut zu einer Editor-Sitzung passt: ändere einen Quellstring, sieh den Toast erscheinen, übersetze, und sieh zu, wie die Raster grün werden, ohne das Terminal anzufassen.

Prüfe den Schaden unter Aktivität

Die Seite Aktivität stellt zwei Referenzansichten nebeneinander:

• Locale-Datei-Historie: der Git-Commit-Feed für deine Quell- und Ziel-Locale-Dateien (als nicht verfügbar angezeigt, wenn das Projekt keine Git-Historie hat).
• Letzter Lauf: die Eingabe- und Ausgabe-Token-Zahlen des letzten Laufs und, wenn ein Token-Budget konfiguriert ist, die Budgetanzeige und ob die Obergrenze erreicht wurde. Das ist ein Schnappschuss zum Stand des letzten aufgezeichneten Laufs, mit Zeitstempel, nie ein Live-Zähler; ein Provider, der keinen Verbrauch meldet (DeepL), wird als "not reported" gezeigt statt als erfundene Null.

Einstellungen, die vierte Seite, zeigt die aufgelöste Konfiguration und das Glossar, mit denen diese Sitzung gestartet wurde; starte Studio nach einer Änderung der Konfigurationsdatei neu.

Weiter

• verbatra studio: jedes Flag und der Startvertrag.
• Übersetzungssicherheit: das Integritäts-Gate und die Review-Gründe.
• CI und Exit-Codes: sichere in CI dieselbe Drift ab, die Studio dir lokal zeigt.