verbatra import

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 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.

SynopsisCopy Anchor Link

verbatra import <workbook> [flags]

• <workbook>: the handoff verbatra export wrote and the translator filled in. For xlsx it is the workbook file; for csv, tsv, xliff2 and xliff12 it is one <locale>.csv, <locale>.tsv or <locale>.xlf file, or the directory holding one file per locale.

ExamplesCopy Anchor Link

# 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"

FlagsCopy Anchor Link

Also takes the global flags --cwd, --config and --json.

BehaviorCopy Anchor Link

Locale files and leftoversCopy Anchor Link

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 locksCopy Anchor Link

--lock-timeout sets how long a locale waits for a contended write lock before it fails with LOCK_CONTENDED, exactly as on verbatra translate. 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.

XLIFFCopy Anchor Link

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.

Blank and broken rowsCopy Anchor Link

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 new. See Manual translation.

Terminal feedbackCopy Anchor Link

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:

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.

JSON outputCopy Anchor Link

Schema: import-envelope.json validates the whole envelope; Schemas lists the others.

With --json, the envelope carries one RunSummary, the same shape verbatra translate prints; RunSummary lists every field.

Exit codesCopy Anchor Link

The contract matches verbatra translate, 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 for the contract every command follows.

RelatedCopy Anchor Link

• 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.
• Hand off to a translation agency covers the XLIFF round-trip through a CAT tool.
• verbatra export produces the handoff this command reads.