--- title: "verbatra export" description: "Exportiere unübersetzte Strings als Übergabe für Übersetzerinnen: als Excel-Arbeitsmappe, als CSV- oder TSV-Datei pro Locale oder als XLIFF für ein CAT-Tool." type: "reference" --- # verbatra export Exportiere unübersetzte Strings als Übergabe für Übersetzerinnen: als Excel-Arbeitsmappe, als CSV- oder TSV-Datei pro Locale oder als XLIFF für ein CAT-Tool. Schreibe die zu übersetzenden Strings in eine Übergabe, die ein Mensch ausfüllt und für [`verbatra import`](https://verbatra.kreitz-webdev.de/de/docs/cli/import.md) zurückschickt. Standardmäßig enthält sie nur die fehlenden und geänderten Strings, also dieselben Keys, die ein automatischer Lauf an einen Provider schicken würde. Ein Key, dessen Quellwert leer ist oder nur aus Leerraum besteht, bekommt keine Zeile, bis du seinen Quelltext schreibst. `export` ruft nie einen Provider auf und braucht keinen API-Key. ## Synopsis [#synopsis] ```bash verbatra export [flags] ``` ## Beispiele [#beispiele] ```bash # 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 ``` ## Flags [#flags] | Flag | Argument | Standard | Wirkung | | --- | --- | --- | --- | | `--out` | `` | `verbatra-translations.xlsx`, bei den anderen Formaten `verbatra-translations` | wohin die Übergabe geschrieben wird: eine Datei bei `xlsx`, ein Verzeichnis bei `csv`, `tsv`, `xliff2` und `xliff12` | | `--format` | `` | `xlsx` | `xlsx` (Excel-Arbeitsmappe), `csv` oder `tsv` (eine Datei pro Locale), `xliff2` oder `xliff12` (eine XLIFF-Datei pro Locale) | | `--locales` | `` | jede konfigurierte Ziel-Locale | nur diese kommagetrennte Teilmenge exportieren; eine nicht konfigurierte Locale scheitert mit `UNKNOWN_LOCALE`, eine leere Liste mit `INVALID_LOCALES`, beide mit Exit `2` | | `--include-unchanged` | keins | aus | auch bereits aktuelle Strings exportieren | Außerdem nimmt der Befehl die [globalen Flags](https://verbatra.kreitz-webdev.de/de/docs/cli.md#globale-flags) `--cwd`, `--config` und `--json`. ## Verhalten [#verhalten] ### CSV und TSV [#csv-und-tsv] `--format csv` und `--format tsv` schreiben eine `.csv` oder `.tsv` pro exportierter Locale, mit denselben Spalten in derselben Reihenfolge wie ein Arbeitsmappen-Blatt. `--out` benennt das Verzeichnis, das bei Bedarf angelegt wird. Eine Datei mit Trennzeichen lässt sich diffen und überall öffnen, hat aber keinen Zellschutz: Jede Spalte ist bearbeitbar, und die Spalte `Source hash` ist sichtbar. Einem geänderten Hash wird nie vertraut: Der Import vergleicht ihn mit der aktuellen Quelle und hält die Zeile zurück. Jeder Export mit Trennzeichen schreibt zusätzlich ein verstecktes Manifest, `.verbatra-export-csv.json` oder `.verbatra-export-tsv.json`, das die geschriebenen Locales benennt. Ein späterer Export mit engerem `--locales` legt die weggefallenen Locales still: ihre Dateien bleiben liegen, und [`verbatra import`](https://verbatra.kreitz-webdev.de/de/docs/cli/import.md) weist sie als Überbleibsel zurück. Der Export löscht nie etwas aus dem Ausgabeverzeichnis. ### XLIFF [#xliff] `--format xliff2` schreibt XLIFF 2.0 und `--format xliff12` XLIFF 1.2: eine `.xlf` pro exportierter Locale in das `--out`-Verzeichnis, dazu ein Manifest `.verbatra-export-xliff.json`, das wie das CSV-Manifest funktioniert. Jeder Key wird zu einer Unit mit dem Key als Namen, Platzhalter und Markup werden zu geschützten Inline-Codes, Beschreibung und Bedeutung des Keys werden zu Notizen, und der Segmentstatus folgt dem Lock- und Review-Status (`initial` für einen fehlenden oder veralteten Key, `translated` wenn aktuell, `reviewed` wenn freigegeben). Siehe [An eine Übersetzungsagentur übergeben](https://verbatra.kreitz-webdev.de/de/docs/translation-agency.md). Jedes Ziel sagt außerdem, woher es stammt. In XLIFF 1.2 trägt ein Ziel, das ein Provider, der Übersetzungsspeicher oder ein KI-Agent geschrieben und noch niemand freigegeben hat, `state-qualifier="mt-suggestion"`; in XLIFF 2.0 trägt die `verbatra`-Metagruppe der Unit `origin` und `review-state`. Der Import ignoriert beides. Lässt sich `verbatra.provenance.json` nicht lesen, wird keine Markierung geschrieben, und das `--json`-Ergebnis trägt `provenanceMarkers: "unavailable"`. Siehe [Nachweis maschineller Übersetzungen](https://verbatra.kreitz-webdev.de/de/docs/provenance-evidence.md#markierungen-in-exporten). ### Wohin die Übergabe geschrieben wird [#wohin-die-übergabe-geschrieben-wird] Die Übergabe landet nur innerhalb der Projektwurzel. Bevor irgendetwas gelesen wird, lehnt `export` mit `EXPORT_OUTPUT_CONFLICT` ein `--out` ab, das aus der Projektwurzel hinausführt oder (selbst oder über eine Datei, die es schreiben würde) eine Datei benennt, von der das Projekt abhängt: eine konfigurierte Locale-Datei, die Lock-Datei, die Herkunftsdatei, den Übersetzungsspeicher-Cache, eine Konfigurationsdatei, nach der verbatra sucht, die Konfiguration des Laufs oder die konfigurierte `glossary`-Datei. Bei `xlsx` wird auch ein Pfad abgelehnt, der keine Datei benennt (etwa `out/`) oder die Projektwurzel selbst ist. Namen werden ohne Beachtung der Groß- und Kleinschreibung verglichen, und die Prüfungen laufen nach dem Auflösen symbolischer Links noch einmal. Ein Pfad, der besteht, kann beim Schreiben trotzdem scheitern (nicht schreibbar, etwas im Weg, Platte voll): Der Lauf bricht dann mit `EXPORT_UNWRITABLE` ab und nennt die Datei und den Dateisystem-Code. Eine Ziel-Locale, die ihr Blatt oder ihre Datei nicht benennen kann, stoppt den Export mit `WORKBOOK_INVALID`. Ein xlsx-Blattname muss 1 bis 31 Zeichen lang sein, darf keines der Zeichen `: \ / ? * [ ]` enthalten und darf, ohne Beachtung der Groß- und Kleinschreibung, weder `Instructions` noch dem Blattnamen einer anderen Ziel-Locale entsprechen. Ein `csv`-, `tsv`- oder `xlf`-Dateiname darf nicht leer, `.` oder `..` sein und kein Pfadtrennzeichen, kein Steuerzeichen und keines der Zeichen `: * ? " < > |` enthalten. Derselbe Code gilt für eine Arbeitsmappe, die sich nicht serialisieren ließ. ### Rückmeldung im Terminal [#rückmeldung-im-terminal] `export` zeigt eine Zeile, während es schreibt, und wenn es etwas zu übergeben gab, nennt es den Import, der die ausgefüllte Datei zurückholt: ```text output verbatra: exporting to xlsx... done (0.3s) next: verbatra import verbatra-translations.xlsx (once your translators have filled it in) ``` Ist nichts offen und wurde `--include-unchanged` nicht übergeben, hat die Datei keine Zeilen, und die `next:`-Zeile schlägt stattdessen denselben Export mit `--include-unchanged` vor, mit `--format`, `--out`, `--locales`, `--cwd` und `--config`. Diese Zeilen gehen auf stderr, und `--quiet` lässt sie weg. Siehe [Terminalausgabe](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#terminalausgabe). ### JSON-Ausgabe [#json-ausgabe] Schema: [`export-envelope.json`](https://verbatra.kreitz-webdev.de/schema/v1/export-envelope.json) validiert den ganzen Envelope; [Schemas](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#schemas) listet die übrigen auf. Mit `--json` trägt der [Envelope](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#json-ausgabe), wohin die Übergabe ging, und die Zeilenzahl pro Locale: ```ts { path: string; // absolute path: the workbook for xlsx, the output directory otherwise locales: { locale: string; rows: number }[]; provenanceMarkers?: "written" | "unavailable"; // XLIFF formats only } ``` ## Exit-Codes [#exit-codes] | Code | Bedeutung | | --- | --- | | `0` | die Übergabe wurde geschrieben | | `2` | konnte nicht laufen: ein Fehler des gesamten Laufs, ein abgelehnter Ausgabepfad (`EXPORT_OUTPUT_CONFLICT`), eine Übergabe, die sich nicht schreiben ließ (`EXPORT_UNWRITABLE`, `WORKBOOK_INVALID`), oder ein Verwendungsfehler | `export` hat keinen Fehlermodus pro Locale und endet deshalb nie mit `1`. Den Vertrag, dem jeder Befehl folgt, findest du unter [Exit-Codes](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#exit-codes). ## Siehe auch [#siehe-auch] - [Menschliche Übersetzung](https://verbatra.kreitz-webdev.de/de/docs/manual-translation.md) behandelt den Aufbau der Arbeitsmappe, die Review-Spalten und den vollständigen Roundtrip. - [An eine Übersetzungsagentur übergeben](https://verbatra.kreitz-webdev.de/de/docs/translation-agency.md) behandelt die XLIFF-Übergabe für ein CAT-Tool. - [`verbatra import`](https://verbatra.kreitz-webdev.de/de/docs/cli/import.md) liest die ausgefüllte Übergabe zurück.