Undo a run

Use this when a run produced translations you do not want: the wrong tone, the wrong model, a glossary you forgot. verbatra has no undo command and keeps no backups. Version control is the recovery mechanism, which is why the locale files, the lock file and the provenance file are committed: together they are the snapshot you go back to.

You need the project in git, with the state before the run committed.

What a run writesCopy Anchor Link

A translate, watch or import run writes the files a rollback cares about:

• the target locale files, at your files.pattern path;
• verbatra.lock.json, one source content hash per translated key.

verbatra.cache.json and .verbatra-local/ are regenerable, gitignored state; never restore them. Every tracked file is written atomically, so there is never a half-written file to repair.

The provenance fileCopy Anchor Link

A run also writes verbatra.provenance.json, which records who wrote each value. Restore it with the other two, or delete it if this run created it. Forgetting it is not harmless: a reverted value no longer matches its record, so it reads as external, counts as a human edit under the default humanEdits: protect, and is never translated again.

Roll back a completed runCopy Anchor Link

If the run is not committed yet, discard the locale files and the lock file together, then the provenance file:

git checkout HEAD -- locales verbatra.lock.json

Restore verbatra.provenance.json the same way if it is already committed. If this run created it, git has nothing to restore, so delete it:

git checkout HEAD -- verbatra.provenance.json   # already committed
rm verbatra.provenance.json                      # created by this run

If the run is already committed, revert that commit:

git revert <commit>

Either way, restore the locale files, verbatra.lock.json and verbatra.provenance.json in the same operation. The next section is why.

Why all three files, or noneCopy Anchor Link

The lock file records a hash of the source value behind each translation, and nothing about the translated value itself; the provenance file records who wrote each value, keyed to a hash of that value. Reverting one file without the others leaves them describing different points in time.

Only the locale files. The lock still says every key is current. On the next run, a key the revert restored is present and its hash matches the source, so it is never sent again: the old value stays in place for good. Only keys the run newly created come back as missing. check and diff compare against the same baseline, so they report the locale as clean, and nothing tells you those translations are out of date.

Only the lock file. The restored hashes are older than the current source, so the affected keys read as changed. The next run translates them again and overwrites the locale files, including hand corrections made since. You pay twice and lose the edits.

Without the provenance file. The reverted values no longer match their records, so they read as external, and under the default humanEdits: protect they are never translated again.

All three. The hashes, the records and the translations go back to the same point, and the next run behaves as if the bad run never happened.

Re-run after a rollbackCopy Anchor Link

Rolling back and running verbatra translate again is a redo, not a second opinion. With the same provider, model, tone, the glossary terms verbatra would send and provider localeMap, the cache fingerprint is unchanged, so the run serves the same translations from verbatra.cache.json without calling the provider.

To get a different result, change what made the first one wrong: a new tone, glossary or model changes the fingerprint and retranslates on its own. To re-send the same configuration to the provider, add --no-cache:

verbatra translate --no-cache

To rebuild a locale from scratch rather than undo one run, see How do I re-translate everything?. Deleting the lock file is not a reset: without a baseline nothing is detected as stale, so the next run translates nothing.

An interrupted or failed runCopy Anchor Link

An interrupted run needs no rollback. Run it again.

Each locale is committed on its own: its file is written, then its lock entries are recorded. An interrupt leaves the finished locales complete and the others untouched, and a re-run picks up the untouched ones. The one gap, between a locale's file write and its lock update, resolves itself: added keys are adopted as they stand, and changed keys still carry their old hash, so they are translated again. No work is lost.

Keys withheld during a run, by a failed check, a failed provider call or a token budget, keep their previous hash, so the next run retries them. See Troubleshooting for each cause.

An interrupted run releases its write locks. A process killed hard (kill -9, a crash) can leave one behind under .verbatra-local/; the next run on the same machine sees that the process is gone and reclaims it. A lock it cannot check makes the run wait and then fail with LOCK_CONTENDED, which names the path to delete.

Before a run you cannot easily undoCopy Anchor Link

• Commit your locale files, verbatra.lock.json and verbatra.provenance.json first, so git checkout HEAD -- has something to return to.
• Preview with verbatra translate --dry-run, verbatra diff or verbatra check. None of them calls a provider or writes a file.
• Try one locale first with --locales <locale>.

RelatedCopy Anchor Link

• The lock file: what it records and how drift is detected.
• The translation cache: the fingerprint and --no-cache.
• verbatra translate: --dry-run, --locales and --no-cache.
• Error codes: LOCK_CONTENDED and the other lock errors.