--- title: "verbatra tmx" description: "Importiere den TMX-Übersetzungsspeicher eines anderen Tools, damit spätere Läufe seine Strings wiederverwenden, oder exportiere den Projektspeicher als TMX." type: "reference" --- # verbatra tmx Importiere den TMX-Übersetzungsspeicher eines anderen Tools, damit spätere Läufe seine Strings wiederverwenden, oder exportiere den Projektspeicher als TMX. Bring einen Übersetzungsspeicher im TMX-Format herein oder hinaus, dem Austauschformat der gängigen Übersetzungsplattformen. `tmx import` übernimmt den Speicher eines anderen Tools in [den Übersetzungsspeicher dieses Projekts](https://verbatra.kreitz-webdev.de/de/docs/the-cache.md), damit spätere Läufe diese Strings wiederverwenden, statt sie erneut zu bezahlen; `tmx export` schreibt den Speicher wieder hinaus. Keine der beiden Richtungen ruft einen Provider auf, liest einen API-Key oder geht ins Netz. Ein echter Import ergänzt außerdem fehlende Einträge in einer vorhandenen `.gitignore`, siehe [.gitignore-Einträge](https://verbatra.kreitz-webdev.de/de/docs/cli.md#gitignore-einträge). ## Synopsis [#synopsis] ```bash verbatra tmx [file] [flags] ``` - ``: `import` oder `export`; alles andere wird mit `INVALID_DIRECTION` abgelehnt. - `[file]`: die TMX-Datei, die gelesen oder geschrieben wird, standardmäßig `verbatra-memory.tmx` in der Projektwurzel. ## Beispiele [#beispiele] ```bash # den Speicher eines anderen Tools in dieses Projekt übernehmen verbatra tmx import legacy.tmx # berichten, was ankäme, nichts ändern verbatra tmx import legacy.tmx --dry-run # die Datei gewinnen lassen, wo sie dem Speicher widerspricht verbatra tmx import legacy.tmx --overwrite # den Speicher nach verbatra-memory.tmx schreiben verbatra tmx export # nur Deutsch, an einen gewählten Pfad verbatra tmx export out/memory.tmx --locales de ``` ## Flags [#flags] | Flag | Argument | Standard | Wirkung | | --- | --- | --- | --- | | `--locales` | `` | jede konfigurierte Ziel-Locale | nur diese kommagetrennte Teilmenge der Ziel-Locales importieren oder exportieren | | `--dry-run` | keins | aus | nur beim Import: prüfen und berichten, ohne den Speicher zu ändern; ein Export lehnt es mit `INVALID_DIRECTION` ab | | `--overwrite` | keins | aus | nur beim Import: eine importierte Einheit darf eine Übersetzung ersetzen, die der Speicher schon hat; ein Export lehnt es mit `INVALID_DIRECTION` ab | Außerdem nimmt der Befehl die [globalen Flags](https://verbatra.kreitz-webdev.de/de/docs/cli.md#globale-flags) `--cwd`, `--config` und `--json`. Die Config-Suche und ein relatives `[file]`, das du angibst, gehen hier von `--cwd` aus, der Speicher und das Standard-`verbatra-memory.tmx` dagegen von der [Projektwurzel](https://verbatra.kreitz-webdev.de/de/docs/config-file.md#das-arbeitsverzeichnis-und-env). ## Verhalten [#verhalten] ### Was eine importierte Einheit erfüllen muss [#was-eine-importierte-einheit-erfüllen-muss] Eine Datei aus einem anderen Tool ist nicht vertrauenswürdig, und eine Einheit im Speicher kann wiederverwendet werden, ohne dass noch einmal jemand gefragt wird. Deshalb durchläuft jede Kandidat-Übersetzung dasselbe [Integritäts-Gate](https://verbatra.kreitz-webdev.de/de/docs/translation-safety.md) wie die Ausgabe eines Providers, geprüft beim Eintritt in den Speicher: - ihre Platzhalter passen zu denen ihres eigenen Quellsegments, - ihre Inline-HTML- oder XML-Tags passen zu denen des Quellsegments, ein eingeschleustes Tag wie `` wird also abgelehnt, - sie ist eine gültige ICU-Nachricht für den Adapter des konfigurierten Formats, - sie ist nicht zu ausuferndem Unsinn entartet, - sie ist nicht leer, wo die Quelle Text hat. Eine Einheit mit leerem Quellsegment bezeichnet keinen String und wird ebenfalls abgelehnt. Inline-Markup (`bpt`, `ept`, `ph`, `it`) wird zu seinem Text abgeflacht, sodass die Platzhalterprüfung Markup erkennt, das etwas Wichtiges trug; der Text eines `sub`-Elements ist ein eigener Textfluss (ein Tooltip, ein Alternativtext) und wird weggelassen. Eigenschaften eines Segments, auch die `x-origin` und `x-review`, die ein verbatra-Export schreibt, werden ignoriert: Der Speicher hält keine Herkunft fest. Nichts verschwindet stillschweigend: Jede Ablehnung, jede unbrauchbare Einheit, jede Einheit ohne Segment in deiner Quell-Locale, jede abgeflachte Einheit und jeder weggelassene `sub`-Text wird nach Grund gezählt. Jede abgelehnte Einheit wird außerdem mit ihrer Position, ihrem Grund und, wenn die Prüfung es benennen kann, dem Fehler aufgeführt, zum Beispiel `unit 12: icu ({count} plural: missing arm "few" required by the target language)`. ### Sprach-Tags zuordnen [#sprach-tags-zuordnen] Eine TMX-Datei schreibt Sprachen so, wie das Tool ihres Autors es tat. Die Zuordnungsregel rät nie: 1. Beide Seiten werden kleingeschrieben und Unterstriche zu Bindestrichen, `pt_BR`, `pt-br` und `pt-BR` sind also eine Locale. Ein exakter Treffer gewinnt. 2. Sonst passt eine konfigurierte Locale, die ein Subtag-Präfix des Tags ist, die längste zuerst (RFC-4647-Lookup): Mit `de` und `de-AT` landet `de-AT-1996` auf `de-AT` und `de-CH-1901` auf `de`. 3. Ein kürzeres Tag erreicht auch eine konfigurierte Locale, die nur eine Region oder Variante ergänzt, nie eine Schrift: `de` landet auf `de-DE` und `pt` auf `pt-BR`, aber `sr` nie auf `sr-Latn`. 4. Tags mit abweichender Schrift oder Region passen nie: `zh-CN` wird nie als `zh-TW` gespeichert und `de-AT` nie als `de-CH`. 5. Mehrdeutig ist ein Tag nur, wenn die erreichbaren Locales nicht auf einer Präfixkette liegen, etwa `pt` bei konfiguriertem `pt-BR` und `pt-AO`. Jedes Segment wird in einem Durchgang gegen die Quell-Locale und alle konfigurierten Ziele aufgelöst, auch mit `--locales`, sodass ein Ziel `pt-BR` in einem Projekt mit Quelle `pt` nie als Quelle gelesen wird. Quellsegmente werden wie Zielsegmente gewichtet: Ein exaktes Tag schlägt einen Präfixtreffer, gleiche Werte stimmen überein, und gleichrangige Segmente mit verschiedenen Werten (`en-US` "Color" und `en-GB` "Colour") führen zur Ablehnung der Einheit. Eine Config, deren Quelle und ein Ziel zum selben Tag normalisiert werden, wird ganz abgelehnt. Zwei Zielsegmente, die dieselbe Locale erreichen, lassen nie einfach das letzte gewinnen: Ein exaktes Tag schlägt einen Präfixtreffer, und zwei gleichrangige Segmente mit verschiedenen Werten speichern für diese Locale nichts und zählen die Einheit als widersprüchlich. Tags ohne Treffer werden pro Tag gezählt, `tu`-Elemente außerhalb des ersten `body` ebenso, und ein `srclang` im Header, der nicht deine Quell-Locale ist, wird gemeldet. ### Wenn Datei und Übersetzungsspeicher sich widersprechen [#wenn-datei-und-übersetzungsspeicher-sich-widersprechen] Der Speicher des Projekts gewinnt: Eine importierte Übersetzung, die von einer vorhandenen abweicht, wird abgelehnt und als behalten gezählt, außer du gibst `--overwrite` an. Innerhalb einer Datei gewinnt die erste Einheit zu einer Quelle, spätere Wiederholungen zählen als Duplikate, ein zweiter Import derselben Datei schreibt also nichts. `--overwrite` ersetzt Übersetzungen, die der Speicher schon hat, und spätere Läufe verwenden die Ersetzungen wieder. Führe es zuerst mit `--dry-run` aus, um die Zahl `overwritten` zu sehen. Importierte Einheiten werden unter dem aktuellen Konfigurations-Fingerprint des Projekts gespeichert, also genau so lange wiederverwendet, wie Provider, Modell, Tonalität, die Glossarbegriffe, die verbatra senden würde, und `localeMap` gleich bleiben. Importiere die Datei nach einer solchen Änderung erneut. Eine Speicherdatei, die ein neueres verbatra geschrieben hat, bleibt unberührt; die Zahlen werden trotzdem gemeldet, wie bei einem Dry Run. ### Importierte Einheiten und unscharfe Wiederverwendung [#importierte-einheiten-und-unscharfe-wiederverwendung] Der Quelltext einer angenommenen Einheit landet im Index, gegen den die [unscharfe Wiederverwendung](https://verbatra.kreitz-webdev.de/de/docs/the-cache.md) geänderte Strings bewertet, sodass eine importierte Quelle, die von einem deiner Strings abweicht, für ihn verwendet werden kann. Eine solche Wiederverwendung besteht trotzdem das Integritäts-Gate gegen deinen echten Eintrag und trägt das Review-Flag `FUZZY_CACHE_REUSE`. Eine importierte Quelle, die einem deiner Strings gleicht, aber anders gehasht wird (dein Eintrag hat eine Beschreibung oder Bedeutung, die TMX nicht tragen kann), wird nie wiederverwendet. Eine Pluralform wird über ihren Text gefunden: Der Import übernimmt das Plural-Flag aus deiner Quelldatei, sodass sich `cart.items_one` und `cart.items_other` wie jeder andere Key aus dem Speicher füllen. Lass `fuzzyCache` aus deiner Config weg, um nur exakte Treffer zuzulassen. ### Was der Export schreibt [#was-der-export-schreibt] Ein `tu` pro eindeutigem Quellstring, mit dem Quellsegment und einem Zielsegment pro exportierter Locale, unter einem TMX-1.4b-Header (`srclang`, `creationtool`, `creationtoolversion`, `segtype`, `o-tmf`). Geschrieben werden nur Einträge unter dem aktuellen Konfigurations-Fingerprint; Einträge, die unter einer früheren Provider-, Modell-, Ton- oder Glossar-Konfiguration gespeichert sind, werden ausgelassen und als `otherConfiguration` gezählt, mit einer eigenen Zeile in der Zusammenfassung. Sprach-Tags erscheinen in BCP-47-Form (`en_US` wird `en-US`), Zeichen, die XML 1.0 nicht darstellen kann, werden entfernt und gezählt, und ein leerer Speicher ergibt eine gültige, leere Datei. Einträge ohne gespeicherten Quelltext, übernommen aus einem älteren Cache, werden ausgelassen und gezählt. Die Zusammenfassung zählt in der Summe `tu`-Elemente und pro Locale Zielsegmente, daher ergeben die Zahlen pro Locale zusammen mehr als die Summe, sobald ein String in mehrere Locales übersetzt ist. Jedes Zielsegment trägt `` (`machine`, `human`, `import` oder `unknown`) aus `verbatra.provenance.json`, ein `machine`-Segment außerdem `` (`approved`, `unreviewed` oder `rejected`). Lässt sich die Provenance- oder Lock-Datei nicht lesen, wird keine Eigenschaft geschrieben, und das Ergebnis meldet `provenanceMarkers: "unavailable"`. Siehe [Nachweise zur maschinellen Übersetzung](https://verbatra.kreitz-webdev.de/de/docs/provenance-evidence.md#tmx). Die Datei wird nur innerhalb der Projektwurzel geschrieben. Ein Pfad, der keine Datei benennt, aus der Projektwurzel herausführt oder eine Datei trifft, von der das Projekt abhängt (eine Locale-Datei, die Lock-, Provenance- oder Cache-Datei, eine Config-Datei, die Glossardatei), wird mit `TMX_OUTPUT_CONFLICT` abgelehnt, bevor der Speicher gelesen wird, auch nach dem Auflösen symbolischer Links. Scheitert das Schreiben auf der Platte, stoppt der Lauf mit `TMX_UNWRITABLE` und nennt die Datei und den Dateisystem-Code. ### JSON-Ausgabe [#json-ausgabe] Schema: [`tmx-envelope.json`](https://verbatra.kreitz-webdev.de/schema/v1/tmx-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 [JSON-Envelope](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#json-ausgabe) das Ergebnis des Imports oder Exports: ```ts // tmx import { dryRun: boolean; file: string; units: number; locales: ImportTmxLocaleResult[]; unmatchedLanguages: TmxLanguageReport[]; ambiguousLanguages: TmxLanguageReport[]; memoryWritable: boolean; /* plus the skipped, unmatched and conflicting unit counts */ } // tmx export { path: string; units: number; locales: { locale: string; units: number }[]; withoutSource: number; otherConfiguration?: number; illegalCharactersRemoved: number; provenanceMarkers: "written" | "unavailable" } ``` Jede Import-Locale meldet die Zähler `added`, `unchanged`, `overwritten`, `kept`, `duplicates`, `conflicting`, `rejected` nach Grund sowie die Liste `refusals`. ### Rückmeldung im Terminal [#rückmeldung-im-terminal] Beide Richtungen zeigen eine Fortschrittszeile auf stderr. `tmx import` schlägt danach `verbatra translate` vor, nach einem Dry Run den echten Import; dieser Vorschlag behält Datei, `--overwrite`, `--locales`, `--cwd` und `--config`. `tmx export` schlägt nichts vor: ```text output verbatra: importing legacy.tmx into the memory... done (0.2s) next: verbatra translate (reuses the imported memory before calling a provider) ``` `--quiet` unterdrückt diese Zeilen. Siehe [Terminalausgabe](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#terminalausgabe). ## Exit-Codes [#exit-codes] | Code | Bedeutung | | --- | --- | | `0` | die Datei wurde gelesen oder geschrieben; übersprungene oder abgelehnte Einheiten werden gemeldet, sind aber kein Fehler | | `2` | konnte nicht laufen: ein Config-Fehler, eine fehlende oder unlesbare TMX-Datei (`SOURCE_UNREADABLE`), eine zu große oder nicht parsbare oder eine Quell-Locale-Datei, die sich nicht parsen lässt (`SOURCE_INVALID`), ein abgelehnter Exportpfad (`TMX_OUTPUT_CONFLICT`), ein gescheiterter Schreibvorgang (`TMX_UNWRITABLE`, `MEMORY_UNWRITABLE`) oder ein Bedienfehler | Bei einer ungültigen Datei nennt die Meldung Zeile, Spalte und Einheit, an der sie scheiterte; Entity-Deklarationen und interne DTD-Subsets werden sofort abgelehnt, ein externer Doctype wird verworfen und nie abgerufen. Siehe [den Exit-Code-Vertrag](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#exit-codes). ## Siehe auch [#siehe-auch] - [Der Cache](https://verbatra.kreitz-webdev.de/de/docs/the-cache.md) erklärt den Übersetzungsspeicher und wie er geschlüsselt ist. - [Manuelle Übersetzung](https://verbatra.kreitz-webdev.de/de/docs/manual-translation.md) beschreibt die Übergabe offener Strings an einen Menschen als xlsx, CSV und TSV. - [Übersetzungssicherheit](https://verbatra.kreitz-webdev.de/de/docs/translation-safety.md) erklärt die Prüfungen, die eine importierte Einheit besteht. - [`tmxErrorLocation`](https://verbatra.kreitz-webdev.de/de/docs/sdk/exchange.md#tmxerrorlocation) liest im SDK die Stelle eines TMX-Fehlers aus.