--- title: "Der Übersetzungs-Cache" description: "Was verbatra.cache.json wiederverwendet, wie ein Fingerprint jeden Eintrag an seine Konfiguration bindet und warum der Cache nie einen Lauf scheitern lässt." type: "concept" --- # Der Übersetzungs-Cache Was verbatra.cache.json wiederverwendet, wie ein Fingerprint jeden Eintrag an seine Konfiguration bindet und warum der Cache nie einen Lauf scheitern lässt. Der Übersetzungs-Cache, `verbatra.cache.json`, ist ein lokales Translation Memory, das nach Inhalt geordnet ist: Er merkt sich die Übersetzung eines Quelltexts, egal welcher Key ihn hält, sodass derselbe Text nie zweimal bezahlt wird. [Die Lock-Datei](https://verbatra.kreitz-webdev.de/de/docs/the-lock-file.md) beantwortet "Ist dieser Key aktuell?"; der Cache beantwortet "Haben wir diesen Text schon einmal übersetzt?". ## Was er wiederverwendet [#was-er-wiederverwendet] Bevor ein Key zum Provider geht, schlägt verbatra den Hash seines aktuellen Quelleintrags nach: der Text samt Beschreibung, Bedeutung, Plural-Flag und Platzhaltern. Ein Treffer ist kostenlos. Weil nach Inhalt gesucht wird, übersteht die Wiederverwendung, was die Lock-Datei nicht sehen kann: - **Ein umbenannter Key.** Verschieb `home.title` nach `landing.title`, und seine Übersetzung wird wiederverwendet. - **Doppelter Inhalt.** Zwei Keys mit demselben Quelltext und Kontext teilen sich eine Übersetzung. Einem wiederverwendeten Wert wird nicht blind vertraut. Er durchläuft dasselbe [Integritäts-Gate](https://verbatra.kreitz-webdev.de/de/docs/translation-safety.md#das-integritäts-gate) gegen die aktuelle Quelle wie eine frische Übersetzung, und einer, der nicht mehr passt, wird verworfen und neu übersetzt. Cache-Treffer werden pro Locale gemeldet, getrennt von den Keys, die in diesem Lauf übersetzt wurden. Ein Wert, den ein Reviewer [abgelehnt](https://verbatra.kreitz-webdev.de/de/docs/the-lock-file.md#review-entscheidungen) hat, wird für diesen Key nie wiederverwendet: Die Herkunftsdatei behält einen Hash des abgelehnten Texts, und ein Lauf überspringt jeden Treffer, der dazu passt. Die einzige Lücke ist eine Herkunftsdatei, die der Lauf nicht lesen kann (eine von einer neueren verbatra-Version oder eine beschädigte unter `humanEdits: "overwrite"`); dann kennt der Lauf keine Ablehnung. ## Der Fingerprint [#der-fingerprint] Jeder Eintrag ist auf den Kontext beschränkt, in dem er entstanden ist: einen Fingerprint über den Provider, das Modell, den Tonfall, die Glossarbegriffe dieser Locale und die [`localeMap`](https://verbatra.kreitz-webdev.de/de/docs/providers.md#an-den-provider-gesendete-locale-codes) des Providers, wenn sie Einträge hat. Ändert sich einer davon, passen frühere Einträge nicht mehr, sodass ein neuer Tonfall oder ein bearbeitetes Glossar neu übersetzt statt ein veraltetes Ergebnis zu liefern. Der Glossaranteil sind die Begriffe, die verbatra an den Provider senden würde, nach einer `sensitiveData`-Einstellung, die einen Begriff zurückhält oder schwärzt, und zwar unabhängig davon, ob der konfigurierte Provider Glossarbegriffe verwendet (DeepL, Google Cloud Translation und LibreTranslate ignorieren sie), sodass ein bearbeiteter Begriff trotzdem neu übersetzt. Das `caseSensitive`-Flag eines Begriffs gehört nicht dazu. Jede Locale hat ihren eigenen Fingerprint, das Bearbeiten nur der deutschen Übersetzung eines Glossarbegriffs lässt die französischen Einträge also passend. Das Format ist nicht Teil des Fingerprints; das Integritäts-Gate bei jedem Treffer fängt einen Wert ab, der nicht mehr passt. Mit dem Provider `none` landet jeder Eintrag in einem einzigen Bereich für reine Handarbeit, den Tonfall und Glossar nicht beeinflussen. ## Unscharfe Wiederverwendung [#unscharfe-wiederverwendung] Ein exakter Treffer braucht einen Quelltext, der zum selben Wert hasht wie vorher, also macht schon ein geändertes Zeichen einen Fehltreffer daraus. [`fuzzyCache`](https://verbatra.kreitz-webdev.de/de/docs/config-file.md#fuzzycache) ist ein optionaler Rückfall für genau diesen Fall: Wenn ein Key nicht trifft, bewertet verbatra seine Quelle gegen die anderen Einträge derselben Locale und desselben Fingerprints und verwendet den nächsten wieder, der `threshold` erreicht oder übertrifft. Der Wert ist eins minus die Zeichen-Editierdistanz geteilt durch die Länge des längeren Strings, `1` heißt also identisch. ### Der Schwellwert ist keine Sicherheitseinstellung [#der-schwellwert-ist-keine-sicherheitseinstellung] Zeichenabstand ist keine Bedeutung. Ein gestrichenes "nicht", "kann nicht" statt "kann" oder ein ausgetauschter Markenname sind kleine Änderungen, die über `0.9` liegen und umkehren, was der Satz sagt. Der Schwellwert entscheidet, wie viel Provider-Ausgaben du dir sparst, nicht, wie sicher eine Wiederverwendung ist. Sicherheit kommt aus Regeln, die nicht von der Zahl abhängen: - **Es ist aus, bis du es einschaltest.** - **Jede unscharfe Wiederverwendung wird zum Review markiert**, mit [`FUZZY_CACHE_REUSE`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#fuzzy_cache_reuse), bei jedem Lauf, ganz gleich wie sie bewertet wurde. Wenn niemand die [Review-Warteschlange](https://verbatra.kreitz-webdev.de/de/docs/review-in-studio.md) abarbeitet, lass es aus. - **Geänderte Ziffern verhindern die Wiederverwendung.** Unterscheiden sich die Ziffern der beiden Quellen in Anzahl, Wert oder Reihenfolge, ist der Eintrag kein Kandidat. Das gilt für jedes numerische Unicode-Zeichen (`m²` zu `m³`, `½` zu `¼`), aber nicht für ausgeschriebene Zahlen. - **Eine Wiederverwendung erledigt den Key nicht.** Die Lock-Datei behält die alte Baseline des Keys, er bleibt also geändert: Jeder spätere Lauf bietet ihn ohne Provider-Kosten erneut an, und [`check`](https://verbatra.kreitz-webdev.de/de/docs/cli/check.md) meldet ihn weiter, bis eine echte Übersetzung ankommt. - **Ein unveränderter Quelltext erreicht die unscharfe Ebene nie.** Wer nur eine Beschreibung oder ein Plural-Flag ändert, schickt den Key wie gewohnt an den Provider. ### Was eine unscharfe Wiederverwendung trotzdem nicht ist [#was-eine-unscharfe-wiederverwendung-trotzdem-nicht-ist] Eine unscharfe Wiederverwendung ist die Übersetzung eines Texts, der nicht mehr die Quelle ist, deshalb wird sie nie als exakter Treffer ausgegeben: - Sie durchläuft das Integritäts-Gate wie jeder andere Kandidat; ein naher Treffer, dessen Platzhalter nicht mehr passen, wird abgelehnt, und der Key geht zum Provider. - Sie wird getrennt von exakten Treffern gemeldet, als `fuzzy-reused`, mit Key, Wert und dem früheren Quelltext; das SDK trägt dasselbe in `LocaleSummary.fuzzyHits`. - Sie wird nie in den Cache zurückgeschrieben, sodass ein späterer Lauf sie nicht für einen exakten Treffer halten kann. Die Bewertung bleibt innerhalb eines Fingerprints und ist begrenzt: höchstens 256 Kandidaten pro Key, und Quelltext mit mehr als 2000 Zeichen wird übersprungen. Mit dem Provider `none` wird ein unscharfer Treffer nie angewendet. ## Die Datei [#die-datei] `verbatra.cache.json` ist eine lokale, wiederherstellbare Datei neben deiner Lock-Datei. Halte sie aus der Versionskontrolle heraus: Sie ist eine Kostenoptimierung, keine gemeinsame Baseline. `verbatra init` trägt sie in die `.gitignore` ein, und `translate`, `watch`, `import`, `tmx import` und `pseudo` ergänzen den Eintrag in einer vorhandenen `.gitignore`, der er fehlt, und sagen das auf stderr. Der Cache lässt nie einen Lauf scheitern. Eine fehlende, beschädigte oder zu große Datei wird zu einem leeren Cache und neu aufgebaut. Eine Datei von einer neueren verbatra-Version wird für den Lauf ebenfalls als leer behandelt, bleibt aber mit einem Hinweis unangetastet auf der Platte. Um neu anzufangen, lösch die Datei. Für die unscharfe Bewertung speichert die Datei jeden Quell-String neben seinen Übersetzungen, sie wächst also ungefähr auf die Größe deines Quelltexts. ## Einen Übersetzungsspeicher zwischen Tools bewegen [#einen-übersetzungsspeicher-zwischen-tools-bewegen] [`verbatra tmx`](https://verbatra.kreitz-webdev.de/de/docs/cli/tmx.md) importiert eine TMX-Datei aus einem anderen Übersetzungstool in den Cache und exportiert den Cache als TMX. Importierte Einheiten werden unter dem aktuellen Fingerprint gespeichert, passen also wie alles andere nicht mehr, wenn sich Provider, Modell, Tonfall, die Glossarbegriffe, die verbatra senden würde, oder `localeMap` ändern. Ein Vorbehalt zu "lösch sie und sie baut sich neu auf": Ein importierter Speicher lässt sich nur so gut wiederherstellen wie die TMX-Datei, aus der er kam, also behalte diese Datei. ## Den Cache umgehen [#den-cache-umgehen] `--no-cache` bei [`translate`](https://verbatra.kreitz-webdev.de/de/docs/cli/translate.md) oder [`watch`](https://verbatra.kreitz-webdev.de/de/docs/cli/watch.md) (`cache: false` im SDK) macht genau die Provider-Aufrufe, die ein Lauf ohne Cache machen würde, unscharfe Wiederverwendung eingeschlossen, und lässt die Datei unangetastet. Um die exakte Wiederverwendung zu behalten und nur den unscharfen Rückfall abzuschalten, lass `fuzzyCache` in der Konfiguration weg. Ein Probelauf schreibt den Cache nie und liest ihn nur mit dem Provider `none`, damit dieser Plan zu einem echten Lauf passt. ## Einschränkung [#einschränkung] Pluralformen, die `generatePlurals` erzeugt, werden nicht gecacht und kommen deshalb immer vom Provider. ## Siehe auch [#siehe-auch] - [`fuzzyCache`](https://verbatra.kreitz-webdev.de/de/docs/config-file.md#fuzzycache): der Konfigurationsschlüssel und sein Bereich. - [`verbatra tmx`](https://verbatra.kreitz-webdev.de/de/docs/cli/tmx.md): den Speicher als TMX importieren und exportieren. - [Wie ein Lauf funktioniert](https://verbatra.kreitz-webdev.de/de/docs/how-it-works.md): wo das Nachschlagen im Cache in der Pipeline sitzt. - [Kosten vor einem Lauf schätzen](https://verbatra.kreitz-webdev.de/de/docs/estimating-cost.md): was der Cache spart, bevor du Geld ausgibst.