Docs / Guides
Review in Studio
Start Verbatra Studio, work the needs-review queue, fix entries in place, and retranslate flagged keys from the local dashboard.
Find pending machine translations, fix values, and approve or reject what a provider wrote, in Verbatra Studio.
Two rules: local editing is always on, and provider spend is always off unless you start Studio with --allow-spend.
Start Studio
npm install --save-dev @verbatra/studio
verbatra studioOpen the URL it prints, token included. verbatra studio covers the port, token, flags and live refresh.
Read the Translations page
One key tablenew
Translations is one table of every key that needs attention: missing, changed, orphaned, protected, in the review queue or failing an integrity check. Each row shows the key, source text and a status per locale; pick a locale for translation, status and origin. Search also finds in-sync keys.
Key details
Click a key to open its editor, which lists each locale's value with an integrity indicator: placeholders match, a mismatch with the tokens named, or invalid message syntax. Also shown:
| Detail | Shows |
|---|---|
| Inline markup mismatch | each tag the translation dropped (-) or added (+) |
| ICU arms mismatch | plural or select arms that do not fit the target language; right-to-left values render right to left (Language support) |
| Origin badge | who wrote each value, read from verbatra.provenance.json, such as Machine, Human or Edited outside verbatra |
Filter by state
Chips beside the search narrow the table by state, including Review queue and Integrity problems. Copy as review report copies the pending keys as Markdown for a pull request.
Edit with integrity gating
Edit opens that locale's draft. Saving runs the value through the integrity gate; a value it refuses is not written, and the reason is shown. An accepted edit writes the locale file and updates the lock file.
Draft checks
The editor shows the key's description, the glossary terms your draft uses or misses, and its length against the source and maxLength. Ctrl or Cmd with Enter saves.
Set a length limitnew
Under the length line, Set limit, Change limit and Remove limit edit the key's entry in verbatra.limits.json, for every locale. The config's maxLength wins, read-only. An unusable file shows why and blocks the control. A limit is advisory: translate runs flag a longer value for review, and nothing is blocked. Studio sets limits only for source keys; a limit written for a generated form's own key still applies.
Preview ICU messagesnew
With next-intl-json or arb, a collapsed ICU preview under the draft renders it once per arm in the locale's language and direction. A typed sample adds a row when it reaches an arm, else a note. Numbers and dates use this computer's language data, so your app may differ.
Beside the tablenew
From 1280px wide the editor sits beside the table; below that it is a drawer. Leaving the key with unsaved edits asks you to save, discard or keep editing; leaving Studio gets the browser's own confirmation.
Search and replacenew
Search and replace changes literal text in translated values: choose the text, replacement, case and locales, review up to 1,000 matches, then apply. Pinned keys and protected values stay out unless you tick their box. Protected means a person wrote, imported or changed it outside verbatra, or any value while verbatra.provenance.json is unreadable.
Work the Review queue
The Review page lists every value a machine wrote that nobody approved: one row per locale and key with the full source and translation, origin and any review flags from the last run on this machine.
Flag labels
Two review flags read Over length budget and Reused after source edit.
Row actions
Filter by locale or text, then:
- Edit opens the integrity-gated editor. An accepted edit clears the row.
- Approve accepts the value.
- Reject removes the value for replacement, after confirming.
Saved decisions
Both decisions are saved in verbatra.provenance.json under the Review decisions rules. An approval also needs the value to be up to date with its source. Commit the locale, lock and provenance files together; in an XLIFF project, edit instead of rejecting.
One queue for the whole team
The queue is read from the committed files, so a teammate who pulls them sees it too. A value leaves it once a person approves, rejects, writes or imports it; an approved value that a machine rewrites comes back.
The Needs review and Approved chips switch the list and show counts; the bar narrows by origin; with a locale chosen, Approve all in approves it all after confirming. To fail a pull request while machine translations wait, run verbatra check --require-reviewed in CI.
Work the queue from the keyboard
Press j or the down arrow to start, then:
| Key | Action |
|---|---|
j or down arrow | next entry |
k or up arrow | previous entry |
a | approve the highlighted entry |
r | reject it (the confirmation still opens) |
e or Enter | open it in the editor |
t | retranslate it (only with --allow-spend; calls your provider) |
x | select or unselect it for a bulk action |
? | show or hide the shortcut list |
Shortcuts pause while you type, in the filter bar or in a dialog.
Act on several entries at once
Tick rows (or the header box for all filtered rows), then choose Approve selected, Reject selected or, with --allow-spend, Retranslate selected. Failures are listed by cause and stay selected. A batch holds at most 100 entries to approve or reject, or 20 to retranslate.
Retranslate a flagged key
Start Studio with spend allowed (how spend is granted):
verbatra studio --allow-spendA Retranslate button appears on each Review row, and in a key's editor for a value with an integrity defect. It makes one provider call, gates the result, and leaves the new value in the queue to approve. From a Review row, a value a person wrote is never replaced; in its editor on Translations, choose Replace anyway.
Translate pending changes
When a source or target locale file changes while Studio runs, a toast reads Source changed or Target changed: de with its key counts. With --allow-spend, the source toast also offers Translate pending changes across all locales, the run verbatra translate would do.
Check coverage and the last run on Overviewnew
Studio opens on Overview: each locale's coverage with its lock file state, the locale files' git history and the last run's token usage, with the budget meter when set.
Run history and cost below it charts cost and tokens for the newest runs above a table, with each locale's last known coverage.
Keep the glossary current on the Glossary page
Glossary has its own page. With a JSON glossary you can search, add, edit and remove terms. Removing one asks first; unsaved edits ask before you leave. An inline glossary stays read-only.
A glossary edit changes what the next run is told, never text already written; restart Studio so its own retranslations use it.
Per-locale view
Show translations for switches to one locale's glossary view: translation, forbidden renderings and note.
Related
- Drive Studio with a browser agent: the same workflow from a browser AI agent.
- Record machine-translation evidence
- Review and retranslate from the SDK