---
title: "Bearbeiten"
description: "Schreibe einen korrigierten Wert oder zeige ein wörtliches Suchen und Ersetzen über die Werte deiner Ziel-Locales als Vorschau und wende es an."
type: "reference"
---
# Bearbeiten
Schreibe einen korrigierten Wert oder zeige ein wörtliches Suchen und Ersetzen über die Werte deiner Ziel-Locales als Vorschau und wende es an.
## Einen Key bearbeiten [#einen-key-bearbeiten]
### editEntry [#editentry]
Schreibt eine von Hand getippte Korrektur für einen Key und eine Locale. Der Kandidatenwert
durchläuft dasselbe Integritäts-Gate wie eine Provider-Übersetzung, bevor irgendetwas die Platte
erreicht; bei Annahme werden die Locale-Datei und der Lock-Eintrag für diesen Key innerhalb der
Schreibsperre dieser Locale aktualisiert. Ruft nie einen Provider auf.
```ts title="Signatur"
function editEntry(
input: EditEntryInput,
deps?: EditEntryDeps,
): Promise;
```
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` is resolved against. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `locale` | `string` | yes | The target locale to write to. Must be a configured target locale. |
| `key` | `string` | yes | The key to edit. Must exist in the source resource. |
| `value` | `string` | yes | The new translation. It is accepted only if it passes the integrity gate. |
| `actor` | `EditEntryActor` | no | Who wrote the value, recorded as its origin in the provenance file: `human` for a person, `agent` for an AI agent acting through a tool. Defaults to `human`. The calling surface asserts it; nothing verifies it. |
| `onLockWait` | `LockWaitListener` | no | Called while waiting on another process's write lock for the locale, so a caller can explain a stall instead of appearing to hang. Never called for a lock this process holds itself. |
| `lockAcquireTimeoutMs` | `number` | no | How long, in milliseconds, to wait for the locale's write lock before failing with `LOCK_CONTENDED`. Defaults to ten minutes. It does not bound the lock-file guard taken to record the written value, which always allows the ten-minute default. |
**Rückgabe:** `EditEntryResult`
**Wirft:** [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#unknown_format), [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#unknown_locale), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#source_invalid), [`UNKNOWN_KEY`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#unknown_key), [`KEY_PINNED`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#key_pinned), [`LOCK_CONTENDED`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#lock_contended), [`RUN_CANCELLED`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#run_cancelled), [`TARGET_UNWRITABLE`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#target_unwritable), [`LOCALE_STATE_NOT_CARRIED_OVER`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#locale_state_not_carried_over), [`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#lock_timeout_invalid), [`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#lock_file_invalid), [`PROVENANCE_FILE_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#provenance_file_invalid)
**Beispiel:** [Einen einzelnen Key bearbeiten und neu übersetzen](https://verbatra.kreitz-webdev.de/de/docs/programmatic-api.md#einen-einzelnen-key-bearbeiten-und-neu-übersetzen)
Gibt `{ accepted: true, value }` zurück oder
`{ accepted: false, reason: "placeholder" | "markup" | "icu" | "degenerate" | "empty", value }`,
wobei nichts geschrieben wird ([das Integritäts-Gate](https://verbatra.kreitz-webdev.de/de/docs/translation-safety.md#das-integritäts-gate)).
Baue jedes Schema über die Gründe aus dem exportierten Tupel `INTEGRITY_GATE_REASONS`. `"empty"`
lehnt einen leeren Wert für eine Quelle mit Text ab; leere einen Key stattdessen mit dem
`[[CLEAR]]`-Sentinel der Arbeitsmappe. Eine `placeholder`- oder `markup`-Ablehnung trägt zusätzlich
`details`: jeden betroffenen Platzhalter oder Tag, mit `-`, wenn der Kandidat ihn weggelassen, oder
`+`, wenn er ihn erfunden hat.
Der Wert wird in `verbatra.provenance.json` mit der Herkunft `human` festgehalten; übergib
`actor: "agent"`, wenn ein KI-Agent ihn geschrieben hat, damit der Eintrag das sagt (der Aufrufer
behauptet es, geprüft wird es nicht); jeder andere `actor` wirft einen `TypeError`, bevor etwas gelesen wird. Eine beschädigte Herkunftsdatei wirft
`PROVENANCE_FILE_INVALID`, bevor der Wert das Gate durchläuft, und nichts wird geschrieben; eine von
einem neueren verbatra, oder eine, die der Eintrag über die Größe wachsen ließe, die verbatra
zurückliest, bleibt unangetastet und der Wert wird ohne Eintrag geschrieben.
Mit `actor: "agent"` wirft ein Key, der auf die `pinnedKeys` der Konfiguration passt, `KEY_PINNED`, bevor etwas geschrieben wird. Die Bearbeitung eines gepinnten Keys durch einen Menschen wird angenommen.
`lockAcquireTimeoutMs` begrenzt die Wartezeit auf die Schreibsperre der Locale, bevor der Aufruf mit `LOCK_CONTENDED` scheitert (standardmäßig zehn Minuten), `onLockWait` meldet diese Wartezeit, und eine ungültige Grenze scheitert mit `LOCK_TIMEOUT_INVALID`, bevor etwas gelesen wird.
## Über Locales hinweg ersetzen [#über-locales-hinweg-ersetzen]
Ein wörtliches Suchen und Ersetzen über die Werte deiner Ziel-Locales, in zwei Schritten. `previewValueReplace` listet auf, was sich ändern würde und warum manche Werte sich nicht ändern würden. `applyValueReplace` ändert die Werte, die du auswählst, und entscheidet jeden davon unter der Schreibsperre noch einmal. Keine der beiden liest die Quell-Locale nach Treffern, und keine ruft einen Provider auf.
### previewValueReplace [#previewvaluereplace]
Listet die Zielwerte auf, die `find` enthalten, mit einem Status je Wert. Der Abgleich ist wörtlich: keine Muster-Syntax, keine Unicode-Normalisierung (ein NFD-`find` trifft keinen NFC-Wert) und keine Umrechnung von Zeilenenden. `replace` wird so eingefügt, wie du es schreibst, `$&` und `$1` haben also keine besondere Bedeutung. `caseSensitive` ist standardmäßig `true`. Ein Treffer beginnt oder endet nie mitten in einem Surrogatpaar, und ein leeres `find`, eines über 20.000 Zeichen oder ein `find` oder `replace` mit einem einzelnen Surrogat ohne Partner wirft `FIND_TEXT_INVALID`. Nur lesend.
```ts title="Signatur"
function previewValueReplace(
input: PreviewValueReplaceInput,
deps?: ValueReplaceDeps,
): Promise;
```
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `locales` | `readonly string[]` | no | The target locales to search. Defaults to every configured target locale. |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` is resolved against. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `find` | `string` | yes | The text to find, matched literally in target values only: 1 to 20,000 characters, with no unpaired surrogate. |
| `replace` | `string` | yes | The text to put in its place, inserted exactly as given, with no unpaired surrogate. `$&`, `$1` and the like have no special meaning. |
| `caseSensitive` | `boolean` | no | Whether letter case must match. Defaults to `true`. |
**Rückgabe:** `ValueReplacePreview`
**Wirft:** [`FIND_TEXT_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#find_text_invalid), [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#unknown_format), [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#unknown_locale), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#source_invalid)
Jeder Eintrag hat genau einen Status. `ready` und `stale-source` lassen sich anwenden; `stale-source` markiert einen Key, dessen Quelltext sich geändert hat, seit seine Übersetzung festgehalten wurde. `gate-refused` trägt den `reason`, den der ersetzte Wert verletzt: Er wird gegen den aktuellen Quelltext am [selben Integritäts-Gate](https://verbatra.kreitz-webdev.de/de/docs/translation-safety.md#das-integritäts-gate) gemessen wie eine Bearbeitung. Bei den ICU-Formaten (next-intl und ARB) wird eine Ersetzung außerdem mit dem Grund `icu` abgelehnt, wenn sie ändert, was ein Argument tut: seinen Typ, einen Zahlen- oder Datumsstil oder ein Skeleton oder die Anzahl der `#` in einem Plural-Zweig, verglichen mit dem aktuellen Wert oder mit dem Quelltext, wenn der aktuelle Wert kein gültiges ICU ist. Ein Argument, das vom Quelltext weg umbenannt wird, wird als `placeholder` abgelehnt. `details` nennen jeden Unterschied, `-` für den verglichenen und `+` für den ersetzten Wert. `too-long` ist ein Wert, der über 20.000 Zeichen wüchse; das ist keine Integritätsablehnung und hat keinen `reason`. `pinned` ist ein Key, der auf `pinnedKeys` passt. `protected` ist ein Wert, den ein Mensch geschrieben oder importiert hat, ein außerhalb von verbatra geänderter Wert oder jeder Wert, wenn die Herkunftsdatei nicht gelesen werden kann, auch eine Datei einer neueren verbatra-Version; das gilt unabhängig von `humanEdits`. Ein Key, der beides ist, steht als `pinned` mit `protected: true` in der Liste und braucht `includePinned` und `includeProtected`. `no-source-entry` ist ein Key ohne Quelltext zum Abgleichen, und `unchanged` ist ein Wert, den die Ersetzung so lässt, wie er ist.
Höchstens 1.000 Werte werden aufgelistet, in der Reihenfolge der `targetLocales` der Konfiguration, egal in welcher Reihenfolge `locales` sie nennt. `truncated` sagt, wenn mehr getroffen haben, und `before` und `after` sind auf 200 Zeichen um den ersten Treffer gekürzt. `valueHash` ist der Hash, den der Herkunftseintrag für den aktuellen Wert speichert; gib ihn an `applyValueReplace` zurück. `baselineUnavailable: true` sagt, dass die Lock-Datei nicht gelesen werden konnte; dann wurde kein Wert mit seinem festgehaltenen Quelltext verglichen, und keiner ist `stale-source`.
### applyValueReplace [#applyvaluereplace]
Ersetzt `find` in den Werten, die du ausgewählt hast, und berechnet jeden neuen Wert unter der Schreibsperre der Locale aus dem Text auf der Platte neu. Sie übernimmt nie einen berechneten Wert vom Aufrufer, und die Vorschau ist nur beratend: Jeder Eintrag wird noch einmal entschieden.
```ts title="Signatur"
function applyValueReplace(
input: ApplyValueReplaceInput,
deps?: ValueReplaceDeps,
): Promise;
```
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `entries` | `readonly ValueReplaceEntryRef[]` | yes | The values to change, as previewValueReplace listed them. Their locales must be configured target locales. |
| `includePinned` | `boolean` | no | Also change keys that match the config's `pinnedKeys`. Ignored when `actor` is `agent`. Defaults to `false`. |
| `includeProtected` | `boolean` | no | Also change values a person wrote, imported, or changed outside verbatra. Defaults to `false`. |
| `actor` | `EditEntryActor` | yes | Who is making the change, recorded as the origin of every changed value in the provenance file. The calling surface asserts it; nothing verifies it. |
| `onLockWait` | `LockWaitListener` | no | Called while waiting on another process's write lock for a locale. |
| `lockAcquireTimeoutMs` | `number` | no | How long, in milliseconds, to wait for each locale's write lock before failing with `LOCK_CONTENDED`. Defaults to ten minutes. |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` is resolved against. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `find` | `string` | yes | The text to find, matched literally in target values only: 1 to 20,000 characters, with no unpaired surrogate. |
| `replace` | `string` | yes | The text to put in its place, inserted exactly as given, with no unpaired surrogate. `$&`, `$1` and the like have no special meaning. |
| `caseSensitive` | `boolean` | no | Whether letter case must match. Defaults to `true`. |
**Rückgabe:** `ApplyValueReplaceResult`
**Wirft:** [`FIND_TEXT_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#find_text_invalid), [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#unknown_format), [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#unknown_locale), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#locale_path_collision), [`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#lock_timeout_invalid), [`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#lock_file_invalid), [`PROVENANCE_FILE_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#provenance_file_invalid)
Jeder Eintrag endet als `applied`, `skipped` (mit Grund), `refused` (mit dem Integritätsgrund), `changed` oder `too-long`. `changed` heißt: Der Wert passt nicht mehr zu seinem `valueHash`, enthält `find` nicht mehr oder ist verschwunden, und für ihn wurde nichts geschrieben. Der Hash ignoriert Unicode-Normalisierung und Zeilenenden; ein Wert, der sich von der Vorschau nur so unterscheidet, wird ersetzt, wenn `find` noch passt, und ist `changed`, wenn nicht. Ein gepinnter Key wird übersprungen, außer `includePinned` ist gesetzt und `actor` ist `human`, und ein geschützter Wert wird übersprungen, außer `includeProtected` ist gesetzt; ein Key, der beides ist, braucht beides. Bei einer Herkunftsdatei einer neueren verbatra-Version gilt jeder Wert als geschützt; `includeProtected` ändert ihn trotzdem, aber die Datei bleibt unberührt und der Wert bekommt keinen Eintrag. Kommen dieselben `locale` und `key` mehrfach vor, entscheidet der erste, egal welchen `valueHash` er trägt, und jeder spätere wird als `duplicate-entry` übersprungen.
Die Locales werden nacheinander verarbeitet, in der Reihenfolge, in der sie in `entries` zuerst vorkommen, jede unter ihrer eigenen Sperre, mit einem Schreibvorgang für die Locale-Datei, einer Aktualisierung von Lock-Datei und Herkunftsdatei und einer Aktualisierung des Übersetzungsspeichers. Ein veralteter Key behält seinen alten Lock-Hash, `check` meldet ihn also weiter als veraltet, und sein Wert kommt nicht in den Übersetzungsspeicher. Jeder geschriebene Wert bekommt einen neuen Herkunftseintrag mit `actor` als Herkunft und ohne Review-Entscheidung. `actor` ist Pflicht, und ein anderer Wert als `human` oder `agent` wirft einen `TypeError`, bevor etwas gelesen wird.
Eine Locale, die scheitert, hält die anderen nicht auf. `localeFailures` listet jede mit `code` und `message`, etwa `LOCK_CONTENDED`, wenn ihre Schreibsperre nicht innerhalb von `lockAcquireTimeoutMs` frei wird, `TARGET_UNWRITABLE`, `SOURCE_INVALID` oder ein Adapter-Fehler. Ein Eintrag, den das Integritäts-Gate abgelehnt hat, kommt weiterhin als `refused` zurück, und einer, den eine Prüfung vor dem Fehler entschieden hatte, behält sein Ergebnis; die übrigen werden als `locale-failed` übersprungen, und für sie wurde nichts geschrieben. Trägt der Fehler `fileWritten: true`, kam er, nachdem die Locale-Datei geschrieben war, beim Aktualisieren der Lock-Datei oder der Herkunftsdatei oder beim Freigeben der Schreibsperre: Die angenommenen Einträge sind `applied`, ihre Werte stehen auf der Platte, und Lock oder Herkunft können hinterherhinken; prüfe die Locale also, bevor du es erneut versuchst. Führe keine Ersetzung noch einmal aus, deren `find` in ihrem `replace` vorkommt, ohne das zu prüfen. Das Warten auf den eigenen Guard der Lock-Datei nutzt den Standard von zehn Minuten, nicht `lockAcquireTimeoutMs`.