--- title: "verbatra import" description: "Import a filled workbook, CSV, TSV, or XLIFF handoff back into the locale files, running the same safety checks." type: "reference" --- # verbatra import Import a filled workbook, CSV, TSV, or XLIFF handoff back into the locale files, running the same safety checks. Read a handoff 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](https://verbatra.kreitz-webdev.de/docs/the-lock-file.md) is updated, values that fail are withheld and reported, so a bad cell never lands in a locale file. A real run also adds missing entries to an existing `.gitignore`, see [.gitignore entries](https://verbatra.kreitz-webdev.de/docs/cli.md#gitignore-entries). ## Synopsis [#synopsis] ```bash verbatra import [flags] ``` - ``: the handoff [`verbatra export`](https://verbatra.kreitz-webdev.de/docs/cli/export.md) wrote and the translator filled in. For `xlsx` it is the workbook file; for `csv`, `tsv`, `xliff2` and `xliff12` it is one `.csv`, `.tsv` or `.xlf` file, or the directory holding one file per locale. ## Examples [#examples] ```bash # 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 csv # import one XLIFF file back from a CAT tool, naming the reviewer verbatra import handoff/de.xlf --reviewer "Agency GmbH" ``` ## Flags [#flags] | Flag | Argument | Default | Effect | | --- | --- | --- | --- | | `--dry-run` | none | off | validate and report without writing locale files or updating the lock | | `--format` | `` | from the path's extension: `csv`, `tsv`, `xliff2` for `.xlf` or `.xliff`, otherwise `xlsx`; for a directory, from the export manifest or the locale files inside | `xlsx`, `csv`, `tsv`, `xliff2` or `xliff12`; either XLIFF format reads both versions | | `--reviewer` | `` | none | name recorded on each XLIFF unit marked reviewed or final; at most 64 characters, stored in the committed provenance file | | `--lock-timeout` | `` | `600` | how long to wait for a held per-locale write lock; a whole number from `1` to `3600`, otherwise a usage error, exit `2` | Also takes the [global flags](https://verbatra.kreitz-webdev.de/docs/cli.md#global-flags) `--cwd`, `--config` and `--json`. ## Behavior [#behavior] Every filled value that passes the checks replaces the value in the locale file, including one a person wrote. Run `--dry-run` first to see what would change. ### Locale files and leftovers [#locale-files-and-leftovers] With `csv` or `tsv` the locale comes from the file name, so keep every file named exactly as it was exported. A configured target locale with no file (or, in a workbook, no sheet) fails that locale with `WORKBOOK_SHEET_MISSING`; it is never silently skipped. A file left over from an earlier export with a wider `--locales` selection is never applied. Import checks the directory against the manifest the most recent export wrote and fails such a locale with `HANDOFF_FILE_STALE`. Re-export that locale or delete the file. A directory with no readable manifest (assembled by hand, or stripped by an archive) is read as it is, and so is a single file you name directly. ### Write locks [#write-locks] `--lock-timeout` sets how long a locale waits for a contended [write lock](https://verbatra.kreitz-webdev.de/docs/the-lock-file.md#the-write-lock) before it fails with `LOCK_CONTENDED`, exactly as on [`verbatra translate`](https://verbatra.kreitz-webdev.de/docs/cli/translate.md). The wait happens before the locale's file is written, so a locale that times out stays untouched while the others still import, and the command exits `1`. Once a file is written, recording it in the lock file waits up to the ten-minute default whatever `--lock-timeout` says. A wait longer than a second prints a line naming the lock and its holder (a `lock-wait` record under `--json`). `--dry-run` takes no lock, so it never waits. ### XLIFF [#xliff] An XLIFF file is read with the version it declares, and a single file whose name is not a configured locale is matched by the target language it declares. A unit whose target equals the current value changes nothing; any other target runs the integrity gate like a workbook row. A unit marked `reviewed` or `final` (in 1.2 also `signed-off` or `approved="yes"`) is recorded as approved, naming `--reviewer`, and reported with the `HANDOFF_REVIEWS_RECORDED` notice. A unit whose id names no source key is reported as a malformed row. See [Hand off to a translation agency](https://verbatra.kreitz-webdev.de/docs/translation-agency.md). ### Blank and broken rows [#blank-and-broken-rows] A blank `Translation` cell never fails a locale: the row is skipped, its lock baseline is kept, and the key is reported as `unfilled` while it still needs a translation. Importing a handoff nobody has filled in yet therefore succeeds and lists every pending key. A single unreadable row is reported as a malformed row, and the rest of the locale still imports. A handoff that is oversized or cannot be parsed at all (for example, not a readable xlsx container) is a whole-run `SOURCE_INVALID` error whose message says what was wrong. In a CSV, TSV or xlsx handoff, a filled row equal to the value an up-to-date key already holds is left alone and reported unchanged, not translated, once it passes the integrity gate . See [Manual translation](https://verbatra.kreitz-webdev.de/docs/manual-translation.md#what-import-accepts). ### Terminal feedback [#terminal-feedback] `import` shows one line while it reads and applies the file. After a clean import it suggests `verbatra check`, and after `--dry-run` the same import without the flag. After a locale fails or comes out partial, it suggests the same import once you correct the refused rows or, when a locale failed with an error that has a next step, that step: ```text output verbatra: importing verbatra-translations.xlsx... done (0.4s) next: verbatra check (confirm every locale is in sync) ``` These lines go to stderr, and `--quiet` drops them. See [Terminal output](https://verbatra.kreitz-webdev.de/docs/cli/output.md#terminal-output). ### JSON output [#json-output] Schema: [`import-envelope.json`](https://verbatra.kreitz-webdev.de/schema/v1/import-envelope.json) validates the whole envelope; [Schemas](https://verbatra.kreitz-webdev.de/docs/cli/output.md#schemas) lists the others. With `--json`, the [envelope](https://verbatra.kreitz-webdev.de/docs/cli/output.md#json-output) carries one `RunSummary`, the same shape [`verbatra translate`](https://verbatra.kreitz-webdev.de/docs/cli/translate.md) prints; [RunSummary](https://verbatra.kreitz-webdev.de/docs/sdk/run-summary.md) lists every field. ## Exit codes [#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, handoff, format, or a corrupt lock file), or a usage error | | `130` | interrupted with Ctrl-C (SIGINT) after releasing the run's write locks | | `143` | stopped with SIGTERM after releasing the run's write locks | The contract matches [`verbatra translate`](https://verbatra.kreitz-webdev.de/docs/cli/translate.md), so a manual handoff branches the same way in CI: a partial locale exits `1`, and a lock file that is or turns corrupt stops the whole run with `2`, leaving the remaining locales untouched (locales applied before stay written). See [Exit codes](https://verbatra.kreitz-webdev.de/docs/cli/output.md#exit-codes) for the contract every command follows. ## Related [#related] - [Manual translation](https://verbatra.kreitz-webdev.de/docs/manual-translation.md) covers the full export, fill, import round-trip and what a translator may edit. - [Translation safety](https://verbatra.kreitz-webdev.de/docs/translation-safety.md) explains the checks that can withhold a value. - [Hand off to a translation agency](https://verbatra.kreitz-webdev.de/docs/translation-agency.md) covers the XLIFF round-trip through a CAT tool. - [`verbatra export`](https://verbatra.kreitz-webdev.de/docs/cli/export.md) produces the handoff this command reads.