verbatra import
Import a filled workbook, CSV, or TSV handoff back into the locale files, running the same safety checks.
Read a workbook a translator filled in back into your locale files. Every value runs through the same integrity checks as an automated run: values that pass are written and the lock file is updated; values that fail are withheld and reported instead of written, so a bad cell never lands in a locale file.
Synopsis
verbatra import <workbook> [flags]<workbook> is the path to the handoff produced by verbatra export and filled in by the translator: the workbook file for xlsx, and for csv and tsv either one <locale>.csv file or the directory holding one file per locale.
Flags
| Flag | Argument | Default | Effect |
|---|---|---|---|
--cwd | <path> | current directory | resolve config and locale files from this directory |
--config | <path> | search for one | load this config file instead of searching for one |
--dry-run | none | off | validate and report without writing locale files or updating the lock |
--format | <format> | xlsx | read an Excel workbook (xlsx) or delimited files (csv, tsv) |
--json | none | off | print one JSON envelope on stdout carrying the run summary under result (the same RunSummary shape as translate), or the error code on a failed run; the human-readable error line still goes to stderr |
Examples
# import the filled workbook
verbatra import verbatra-translations.xlsx
# validate and report, write nothing
verbatra import verbatra-translations.xlsx --dry-run
# import every locale file in a CSV handoff directory
verbatra import handoff --format csvWith csv or tsv the locale comes from the file name, not from a sheet name, so keep every file named exactly as it was exported. A configured target locale with no file is reported as that locale's failure, never silently skipped.
A file left over from an earlier export with a wider --locales selection is never applied. Import reconciles the directory against the manifest the most recent export wrote there and reports such a locale as failed with HANDOFF_FILE_STALE, so an outdated translation cannot slip back in unnoticed. Re-export that locale to refresh its file, or delete the file. A directory with no readable manifest (one assembled by hand, or one that lost the hidden file on its way through an archive) is read as it always was, every present file is imported. Naming a single file directly is likewise taken at face value.
Exit codes
| Code | Meaning |
|---|---|
0 | every target locale came out complete |
1 | the run finished but one or more locales failed or came out partial |
2 | could not run: a whole-run error (config, workbook, format, or lock), or a usage error |
The contract matches verbatra translate, so a manual handoff branches the same way in CI. That includes partial locales: a locale written with keys still missing exits 1, not 0. It also includes the lock file: a lock file that is corrupt, or that turns corrupt while the import is running, stops the whole run with 2 instead of reporting one failed locale, so the locales still to come are left untouched. Locales applied before the abort stay written; fix the lock file and import again.
A blank Translation cell never fails a locale: the row is skipped, its prior lock baseline is kept, and the key is reported as unfilled whenever it still needs a translation, whether the row was exported as new or changed. Importing a workbook nobody has filled in yet therefore succeeds and returns the full inventory of pending keys.
Related
- Manual translation covers the full export, fill, import round-trip and what a translator may edit.
- Translation safety explains the checks that can withhold a value.
verbatra exportproduces the handoff this command reads.