verbatra export

Write the strings that need translating into a handoff a person fills in and sends back for verbatra import. By default it carries only the missing and changed strings, the same keys an automated run would send to a provider. A key whose source value is empty or whitespace only gets no row until you write its source text. export never calls a provider and needs no API key.

SynopsisCopy Anchor Link

verbatra export [flags]

ExamplesCopy Anchor Link

# write the workbook with missing and changed strings
verbatra export

# only the German and French sheets, to a specific path
verbatra export --locales de,fr --out handoff/round-2.xlsx

# one de.csv and fr.csv under handoff/
verbatra export --format csv --out handoff

# one de.xlf and fr.xlf in XLIFF 2.0 for a CAT tool
verbatra export --format xliff2 --out handoff

FlagsCopy Anchor Link

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

BehaviorCopy Anchor Link

CSV and TSVCopy Anchor Link

--format csv and --format tsv write one <locale>.csv or <locale>.tsv per exported locale, with the same columns in the same order as a workbook sheet. --out names the directory, which is created if it is missing.

A delimited file is diffable and opens anywhere, but it has no cell protection: every column is editable and the Source hash column is visible. An edited hash is never trusted: import compares it against the live source and withholds the row.

Each delimited export also writes a hidden manifest, .verbatra-export-csv.json or .verbatra-export-tsv.json, naming the locales it wrote. A later export with a narrower --locales retires the locales it dropped: their files stay on disk, and verbatra import refuses them as leftovers. The export never deletes anything from the output directory.

XLIFFCopy Anchor Link

--format xliff2 writes XLIFF 2.0 and --format xliff12 XLIFF 1.2: one <locale>.xlf per exported locale in the --out directory, plus a .verbatra-export-xliff.json manifest that works like the CSV one. Each key becomes a unit named by the key, placeholders and markup become protected inline codes, the key's description and meaning become notes, and the segment state follows the lock and review state (initial for a missing or stale key, translated when up to date, reviewed when approved). See Hand off to a translation agency.

Each target also says where it came from. In XLIFF 1.2, a target a provider, the translation memory or an AI agent wrote, and that no person approved, carries state-qualifier="mt-suggestion"; in XLIFF 2.0 the unit's verbatra metadata group carries origin and review-state. Import ignores both. When verbatra.provenance.json cannot be read, no marker is written and the --json result carries provenanceMarkers: "unavailable". See Machine-translation evidence.

Where the handoff is writtenCopy Anchor Link

The handoff is only written inside the project root. Before anything is read, export refuses with EXPORT_OUTPUT_CONFLICT an --out that climbs out of the project root, or that (itself or through a file it would write) names a file the project depends on: a configured locale file, the lock file, the provenance file, the translation-memory cache, a config file verbatra searches for, the config the run loaded, or the configured glossary file. For xlsx, a path that names no file (such as out/) or the project root itself is refused too. Names compare case-insensitively, and the checks run again after symbolic links are resolved.

A path that passes can still fail while writing (not writable, something in the way, disk full): the run stops with EXPORT_UNWRITABLE, naming the file and the file-system code.

A target locale that cannot name its sheet or file stops the export with WORKBOOK_INVALID. An xlsx sheet name must be 1 to 31 characters, must not contain any of : \ / ? * [ ], and must not match Instructions or another target locale's sheet name, ignoring case. A csv, tsv or xlf file name must not be empty, . or .., and must not contain a path separator, a control character, or any of : * ? " < > |. The same code covers a workbook that could not be serialized.

Terminal feedbackCopy Anchor Link

export shows one line while it writes, and when there was anything to hand off it names the import that brings the filled file back:

verbatra: exporting to xlsx... done (0.3s)
next: verbatra import verbatra-translations.xlsx (once your translators have filled it in)

When nothing is pending and --include-unchanged was not passed, the file has no rows, and the next: line suggests the same export with --include-unchanged instead, keeping --format, --out, --locales, --cwd and --config.

These lines go to stderr, and --quiet drops them. See Terminal output.

JSON outputCopy Anchor Link

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

With --json, the envelope carries where the handoff went and the row count per locale:

{
  path: string;                // absolute path: the workbook for xlsx, the output directory otherwise
  locales: { locale: string; rows: number }[];
  provenanceMarkers?: "written" | "unavailable"; // XLIFF formats only
}

Exit codesCopy Anchor Link

export has no per-locale failure mode, so it never exits 1. See Exit codes for the contract every command follows.

RelatedCopy Anchor Link

• Manual translation covers the workbook layout, the review columns and the full round-trip.
• Hand off to a translation agency covers the XLIFF handoff for a CAT tool.
• verbatra import reads the filled handoff back.