---
title: "Bearbeiten und prüfen"
description: "Einen Key lesen, bearbeiten, freigeben, ablehnen oder neu übersetzen, Werte gesammelt oder seitenweise lesen, oder viele Keys auf einmal prüfen."
type: "reference"
---
# Bearbeiten und prüfen
Einen Key lesen, bearbeiten, freigeben, ablehnen oder neu übersetzen, Werte gesammelt oder seitenweise lesen, oder viele Keys auf einmal prüfen.
## Operationen auf einzelnen Keys [#operationen-auf-einzelnen-keys]
Das sind die Nahtstellen, an denen Verbatra Studio ansetzt; nutze sie, um dein eigenes
Review-Tooling zu bauen. Die Funktionen, die `locale` und `key` nehmen, lösen beide bei jedem Aufruf frisch auf und werfen
`UNKNOWN_LOCALE` oder `UNKNOWN_KEY`, wenn eines von beiden nicht existiert.
### keyValue [#keyvalue]
Liest den aktuellen Quellwert eines Keys und, falls vorhanden, seinen aktuellen Zielwert für eine
Locale. Nur lesend.
```ts title="Signatur"
function keyValue(
input: KeyValueInput,
deps?: KeyValueDeps,
): 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 read the translation from. Must be a configured target locale. |
| `key` | `string` | yes | The key to read. Must exist in the source resource. |
**Rückgabe:** `KeyValueResult`
**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)
**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 `{ source, target? }` zurück; `target` fehlt genau dann, wenn der Key in dieser Locale noch
nicht existiert, und kommt, wenn vorhanden, mit `provenance`, der ausgewerteten `KeyProvenance` des
Keys: `{ origin, provider?, model?, reviewState, reviewer? }`.
Das Ergebnis trägt außerdem `description`, wenn die Quelldatei dem Key eine gibt: eine
ARB-`@key.description`, eine XLIFF-Notiz oder einen Kommentar in gettext, Apples `.strings` oder
.NET-`.resx`.
### keyContext [#keycontext]
Liest, was eine Übersetzerin braucht, um einen Key in einer Ziel-Locale zu schreiben: alles, was `keyValue` liefert, dazu die Glossarbegriffe, die auf den Quelltext zutreffen, und das `maxLength` des Keys. Gib einen `draft` mit, um ihn gegen diese Begriffe zu prüfen. Nur lesend. Um ein dateibasiertes Glossar neu von der Platte zu lesen, nimmt er `loaded` aus `loadConfigWithMeta`, keine bloße Konfiguration.
```ts title="Signatur"
function keyContext(
input: KeyContextInput,
deps?: KeyContextDeps,
): Promise;
```
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `loaded` | `GlossaryConfig` | yes | The loaded config, as loadConfigWithMeta returns it, so a file-backed glossary is read. |
| `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 the key is about to be written in. Must be a configured target locale. |
| `key` | `string` | yes | The key to read. Must exist in the source resource. |
| `draft` | `string` | no | A value the caller intends to write, checked against the applying glossary terms when given. |
**Rückgabe:** `KeyContext`
**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)
Ein nicht lesbares Glossar wirft nicht: `glossary` ist leer und `glossaryNotice` trägt den Code und die geschwärzte Meldung des Fehlers. `draftCheck` sagt pro zutreffendem Begriff, ob der Entwurf die geforderte Übersetzung nutzt und welche verbotenen Varianten er verwendet.
### localeHistory [#localehistory]
Listet die letzten Git-Commits, die die Quell- oder eine Ziel-Locale-Datei geändert haben, neueste zuerst. Nur lesend; es führt `git log` über das injizierbare `execFile` aus.
```ts title="Signatur"
function localeHistory(
input: LocaleHistoryInput,
deps?: LocaleHistoryDeps,
): 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 and git runs in. 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. |
| `limit` | `number` | no | The most commits to list. Rounded down and clamped to between 1 and LOCALE_HISTORY_LIMIT_CAP; defaults to LOCALE_HISTORY_LIMIT_DEFAULT when omitted or not a finite number. |
**Rückgabe:** `LocaleHistoryResult`
**Wirft:** [`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)
Jeder Commit trägt `hash`, `author` (der Name nach `.mailmap`, nie die E-Mail), `authorDate`, `subject` und `touchedPaths`. `limit` ist standardmäßig `LOCALE_HISTORY_LIMIT_DEFAULT` (`50`), höchstens `LOCALE_HISTORY_LIMIT_CAP` (`200`), abgerundet und mindestens 1. Steuer- und bidirektionale Formatierungszeichen fliegen aus `author` und `subject`; ein Commit mit unlesbaren Metadaten fehlt. Ohne Git oder Repository, oder wenn `git log` `LOCALE_HISTORY_TIMEOUT_MS` oder `LOCALE_HISTORY_MAX_OUTPUT_BYTES` überschreitet, ist das Ergebnis `{ available: false, reason }`, ein Grund aus `LOCALE_HISTORY_UNAVAILABLE_REASONS`. Siehe [Studio und MCP](https://verbatra.kreitz-webdev.de/de/docs/data-handling.md#studio-und-mcp).
### 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). 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.
### retranslateEntry [#retranslateentry]
Lässt den Provider für genau einen Key und eine Locale über denselben Provider-Pfad und dasselbe
Integritäts-Gate wie `translate` neu laufen und schreibt bei Annahme die Locale-Datei und den
Lock-Eintrag nur für diesen Key.
```ts title="Signatur"
function retranslateEntry(
input: RetranslateEntryInput,
deps?: RetranslateEntryDeps,
): 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 retranslate into. Must be a configured target locale. |
| `key` | `string` | yes | The key to retranslate. Must exist in the source resource. |
| `includeHuman` | `boolean` | no | Replace the key's value even when a person wrote it: its origin is `human` or `import`, or it changed outside verbatra. Without it such a key is refused with `KEY_PROTECTED`, unless the config sets `humanEdits: "overwrite"`. A key matching `pinnedKeys` is refused whatever this says. Defaults to false. |
| `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`. The wait happens before the provider is called, so a timed-out call has spent nothing. 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. |
| `signal` | `AbortSignal` | no | Cancels the call when aborted before the provider has answered: a wait for the write lock stops, an in-flight provider request is abandoned, and the call rejects with `RUN_CANCELLED` having written nothing. An abort after the answer arrived does not stop the write. Defaults to none. |
**Rückgabe:** `RetranslateEntryResult`
**Wirft:** [`MACHINE_TRANSLATION_DISABLED`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#machine_translation_disabled), [`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#lock_timeout_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_UNSUPPORTED_BY_PROVIDER`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#locale_unsupported_by_provider), [`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), [`KEY_PROTECTED`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#key_protected), [`PROVIDER_CONSTRUCTION_FAILED`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#provider_construction_failed), [`NETWORK_POLICY_VIOLATION`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#network_policy_violation), [`CONFIG_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#config_invalid), [`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_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), [`SENSITIVE_CONTENT_WITHHELD`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#sensitive_content_withheld)
**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, reviewReasons }` zurück (die Review-Grund-Codes des neuen Werts)
oder die Ablehnung, die `editEntry` liefert. Anders als bei `translate` wirft ein Provider-Fehlschlag hier: ein `ProviderError`, exportiert aus
`@verbatra/sdk`, mit einem stabilen `code` wie `RATE_LIMITED` oder `AUTH_FAILED`. Unter `provider: { id: "none" }` wirft es zuerst `MACHINE_TRANSLATION_DISABLED`, bevor es irgendetwas liest oder sperrt.
Der neue Wert wird in `verbatra.provenance.json` als `machine` festgehalten, mit der `id` des
Providers, der geantwortet hat, und dem konfigurierten Modell. Ein Provider aus deinem eigenen
`createProvider` wird unter seiner eigenen `id` festgehalten, und ohne Modell, wenn diese `id` von der
konfigurierten abweicht. Eine beschädigte Herkunftsdatei wirft `PROVENANCE_FILE_INVALID`, bevor der
Provider aufgerufen wird.
Ein Key, dessen Wert ein Mensch geschrieben, importiert oder außerhalb von verbatra geändert hat, wirft `KEY_PROTECTED` innerhalb der Schreibsperre, bevor der Provider aufgerufen wird, außer du übergibst `includeHuman: true` oder die Konfiguration setzt `humanEdits: "overwrite"`; bei einer Provenienz-Datei von einem neueren verbatra zählt jeder vorhandene Wert als geschützt. Ein Key, der auf `pinnedKeys` passt, wirft `KEY_PINNED`, bevor der Provider gebaut wird, auch mit `includeHuman`.
### approveEntry [#approveentry]
Hält fest, dass eine Person den aktuellen Wert eines Keys in einer Locale geprüft hat und ihn
übernimmt. Schreibt nur `verbatra.provenance.json`, nie eine Locale-Datei oder die Lock-Datei, und
ruft keinen Provider auf. Die Freigabe speichert zusätzlich den Quell-Hash des Keys aus der
Lock-Datei, sodass sie wieder als ungeprüft gilt, sobald sich die Quelle ändert; jeder spätere
Schreibvorgang, der den Wert ändert, beginnt einen frischen, ungeprüften Eintrag.
```ts title="Signatur"
function approveEntry(
input: ReviewDecisionInput,
deps?: ReviewDecisionDeps,
): 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 the reviewed value belongs to. Must be a configured target locale. |
| `key` | `string` | yes | The key whose value was reviewed. Must exist in the source resource. |
| `expectedValue` | `string` | no | The translation the reviewer saw. The decision is refused when the key's current value is a different one, so a value nobody looked at is never approved or rejected. Pass exactly one of `expectedValue` and `expectedValueHash`. |
| `expectedValueHash` | `string` | no | The hash of the translation the reviewer saw, as the `valueMarker` dependency's ValueMarker.hash produced it, for a caller that only ever saw the value's redaction marker. The decision is refused when the key's current value hashes differently. |
| `reviewer` | `string` | no | Free text naming the reviewer, 1 to 64 characters with no control characters. It is stored in the committed provenance file, so it is public. When it is left out no new name is recorded, and a reviewer already recorded for the same decision on the same value is kept. |
| `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 decision, which always allows the ten-minute default. |
**Rückgabe:** `ReviewDecisionResult`
**Wirft:** [`REVIEWER_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#reviewer_invalid), [`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#lock_timeout_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), [`UNKNOWN_KEY`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#unknown_key), [`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), [`REVIEW_VALUE_CHANGED`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#review_value_changed), [`LOCALE_STATE_NOT_CARRIED_OVER`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#locale_state_not_carried_over), [`REVIEW_SOURCE_CHANGED`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#review_source_changed), [`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), [`PROVENANCE_FILE_UNWRITABLE`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#provenance_file_unwritable)
**Beispiel:** [Die Review-Warteschlange abarbeiten](https://verbatra.kreitz-webdev.de/de/docs/programmatic-api.md#die-review-warteschlange-abarbeiten)
`expectedValue` ist der Text,
den die prüfende Person gesehen hat, oder du übergibst `expectedValueHash` mit dem `valueMarker`, der ihn erzeugt hat: Der Aufruf wirft `REVIEW_VALUE_CHANGED`, wenn der Key keinen
oder einen anderen Wert hat, und `REVIEW_SOURCE_CHANGED`, wenn sich die Quelle geändert hat, seit
der Wert geschrieben wurde. `reviewer` ist optionaler Freitext mit 1 bis 64 Zeichen ohne
Steuerzeichen (sonst `REVIEWER_INVALID`), landet in der committeten Datei und wird nie von verbatra
ausgefüllt. Gibt `{ locale, key, provenance }` zurück. Ein Wert ohne bisherigen Eintrag, oder einer,
der außerhalb von verbatra geändert wurde, wird mit der Herkunft `unknown` festgehalten.
### rejectEntry [#rejectentry]
Hält fest, dass eine Person den aktuellen Wert eines Keys in einer Locale geprüft hat und ihn
ablehnt, und entfernt ihn aus der Locale-Datei und der Lock-Datei, sodass `check` und `diff` ihn als
fehlend melden und der nächste `translate`-Lauf ihn wieder füllt (unter `provider: { id: "none" }`
bleibt er fehlend, bis jemand einen schreibt). Der Herkunftseintrag bleibt als `rejected` mit einem
Hash des entfernten Texts, und der passende Memory-Eintrag auf diesem Rechner wird gelöscht; ein
späteres `translate` überspringt jeden exakten oder unscharfen Memory-Treffer für den Key, der zu
diesem Hash passt, sodass kein Memory eines Rechners den Text zurückbringt. Ruft keinen Provider auf.
```ts title="Signatur"
function rejectEntry(
input: ReviewDecisionInput,
deps?: ReviewDecisionDeps,
): 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 the reviewed value belongs to. Must be a configured target locale. |
| `key` | `string` | yes | The key whose value was reviewed. Must exist in the source resource. |
| `expectedValue` | `string` | no | The translation the reviewer saw. The decision is refused when the key's current value is a different one, so a value nobody looked at is never approved or rejected. Pass exactly one of `expectedValue` and `expectedValueHash`. |
| `expectedValueHash` | `string` | no | The hash of the translation the reviewer saw, as the `valueMarker` dependency's ValueMarker.hash produced it, for a caller that only ever saw the value's redaction marker. The decision is refused when the key's current value hashes differently. |
| `reviewer` | `string` | no | Free text naming the reviewer, 1 to 64 characters with no control characters. It is stored in the committed provenance file, so it is public. When it is left out no new name is recorded, and a reviewer already recorded for the same decision on the same value is kept. |
| `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 decision, which always allows the ten-minute default. |
**Rückgabe:** `ReviewDecisionResult`
**Wirft:** [`REVIEWER_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#reviewer_invalid), [`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#lock_timeout_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), [`UNKNOWN_KEY`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#unknown_key), [`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), [`REVIEW_VALUE_CHANGED`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#review_value_changed), [`LOCALE_STATE_NOT_CARRIED_OVER`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#locale_state_not_carried_over), [`TARGET_UNWRITABLE`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#target_unwritable), [`REVIEW_REJECT_UNSUPPORTED`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#review_reject_unsupported), [`REVIEW_RESTORE_FAILED`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#review_restore_failed), [`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), [`PROVENANCE_FILE_UNWRITABLE`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#provenance_file_unwritable)
**Beispiel:** [Die Review-Warteschlange abarbeiten](https://verbatra.kreitz-webdev.de/de/docs/programmatic-api.md#die-review-warteschlange-abarbeiten)
Die Eingabe wird wie bei `approveEntry` geprüft,
nur dass eine veraltete Quelle eine Ablehnung nicht verhindert. Gibt `{ locale, key, provenance }`
zurück. Ein Format, das einen Key behält, den es nicht übergeben bekommt, XLIFF, wirft
`REVIEW_REJECT_UNSUPPORTED`, nachdem es die Datei wiederhergestellt hat.
Beide Aufrufe nehmen die Schreibsperre der Locale mit `lockAcquireTimeoutMs` und `onLockWait` wie
bei `editEntry`; `LOCK_TIMEOUT_INVALID` heißt, die Grenze ist keine ganze Zahl von mindestens 0
Millisekunden. Die Wartezeit begrenzt nicht die Sperre der Lock-Datei, die zum Festhalten der
Entscheidung genommen wird: Die erlaubt immer die zehn Minuten des Standards.
Keiner meldet eine Entscheidung, die er nicht speichern konnte: Eine Herkunftsdatei aus einem
neueren verbatra, oder eine, die durch die Entscheidung über die Größe wachsen würde, die verbatra
wieder einliest, wirft `PROVENANCE_FILE_UNWRITABLE`, bevor etwas geschrieben wird.
### createValueMarker [#createvaluemarker]
Erzeugt die Markierung, mit der eine Oberfläche einen Wert ohne seinen Text zeigt: `mark(value)`
liefert `[redacted length= hash=]`, und `hash(value)` liefert `h`, einen 16-stelligen
Hex-HMAC mit zufälligem Salt (oder dem übergebenen `salt`), sodass ein Hash nur unter derselben
Markierung passt. Übergib sie als `valueMarker` an `approveEntry` oder `rejectEntry`, damit
`expectedValueHash` statt `expectedValue` gilt. `verbatra mcp --redact-values` erzeugt eine pro
Serverstart.
```ts title="Signatur"
function createValueMarker(salt?: Uint8Array): ValueMarker;
```
**Rückgabe:** `ValueMarker`
## Inhalte in großen Mengen lesen [#inhalte-in-großen-mengen-lesen]
### localeValues [#localevalues]
Liest den aktuellen Quell- und Zielwert jedes Keys über die angefragten Ziel-Locales in einem
Durchgang über die Dateien auf der Platte, etwa um Werte statt Key-Namen zu durchsuchen: das
Gegenstück zu `keyValue` für große Mengen. Nur lesend.
```ts title="Signatur"
function localeValues(
input: LocaleValuesInput,
deps?: LocaleValuesDeps,
): 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. |
| `locales` | `readonly string[]` | no | Restrict the report to these target locales. Defaults to every configured target locale. |
**Rückgabe:** `readonly LocaleValues[]`
**Wirft:** [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#unknown_format), [`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_LOCALE`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#unknown_locale)
**Beispiel:** [Alle Werte auf einmal lesen](https://verbatra.kreitz-webdev.de/de/docs/programmatic-api.md#alle-werte-auf-einmal-lesen)
Ein weggelassenes `locales` deckt jedes konfigurierte
Ziel-Locale ab. Gibt ein `{ locale, keys, values }` pro Locale zurück: `keys` listet jeden Key in
Quellreihenfolge, danach die nur im Ziel vorhandenen, und `values` bildet jeden Key auf
`{ source?, target? }` ab. Ohne `target` ist er dort noch nicht übersetzt; ohne `source` ist er
verwaist (aus der Quelle verschwunden). `values` hat keinen Prototyp: Jeder Key, auch `__proto__`
oder `constructor`, ist eine eigene Eigenschaft, und ein fehlender Key ergibt `undefined`.
Jedes Paar mit einem `target` trägt außerdem `provenance`, dieselbe `KeyProvenance`, die `keyValue`
meldet.
### localeValuesPage [#localevaluespage]
Liest eine Seite von `localeValues`, optional eingegrenzt auf exakte `keys` oder auf eine `query`, die ohne Rücksicht auf Groß- und Kleinschreibung gegen Key, Quell- und Zieltext geprüft wird, und gibt einen Cursor für die nächste Seite zurück. Der MCP-Server und das Agent-Tool `verbatra_locale_values` in Studio blättern damit. Nur lesend.
```ts title="Signatur"
function localeValuesPage(
input: LocaleValuesPageInput,
deps?: LocaleValuesDeps,
): Promise;
```
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `keys` | `readonly string[]` | no | Keep only these exact key names. |
| `query` | `string` | no | Keep only keys whose name, source text, or target text contains this text, ignoring case. |
| `limit` | `number` | no | The most entries the page holds, a whole number from 1 to PAGE_LIMIT_CAP. Defaults to PAGE_LIMIT_DEFAULT. |
| `cursor` | `string` | no | The `nextCursor` of the previous page. Omit it to read the first page. |
| `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. |
| `locales` | `readonly string[]` | no | Restrict the report to these target locales. Defaults to every configured target locale. |
**Rückgabe:** `LocaleValuesPage`
**Wirft:** [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#unknown_format), [`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_LOCALE`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#unknown_locale), [`PAGE_CURSOR_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#page_cursor_invalid), [`PAGE_LIMIT_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#page_limit_invalid)
Gibt `{ locales, nextCursor? }` zurück: Jede Locale mit einem Eintrag auf der Seite trägt `entries`, jeweils `{ key, source?, target?, provenance? }` wie bei `localeValues`, sortiert nach Locale und dann nach Key. Eine Seite hält höchstens `limit` Einträge: standardmäßig `PAGE_LIMIT_DEFAULT` (200), höchstens `PAGE_LIMIT_CAP` (1000). Gib `nextCursor` mit denselben Filtern als `cursor` zurück, bis er fehlt. Jeder Aufruf liest die Dateien neu, deshalb wird ein Cursor, dessen Key verschoben wurde oder fehlt, abgelehnt, statt Einträge zu überspringen oder zu wiederholen.
Ein `cursor` ist höchstens `PAGE_CURSOR_MAX_LENGTH` (512) Zeichen lang. Der MCP-Server und Studio nehmen eine `query` mit höchstens `LOCALE_VALUES_QUERY_MAX_LENGTH` (500) Zeichen an.
## Review und Neuübersetzung im Stapel [#review-und-neuübersetzung-im-stapel]
Jeder dieser Aufrufe führt den passenden Einzel-Key-Aufruf einmal pro Eintrag in Reihenfolge aus
und gibt `{ results }` mit einem Ergebnis pro Eintrag zurück. Ein gescheiterter Eintrag hält den
Stapel nicht an: Sein Ergebnis ist `{ locale, key, ok: false, code, message }` mit dem Code des
`SdkError`, Adapter-Fehlers oder `ProviderError` und einer geschwärzten Nachricht. Jeder andere
Fehler stoppt den Stapel mit einem `BatchInterruptedError`. Eine leere `entries`-Liste ergibt leere
`results`.
### approveEntries [#approveentries]
Führt `approveEntry` pro Eintrag mit denselben Prüfungen aus; `reviewer` gilt für jeden Eintrag. Ein
erfolgreiches Ergebnis ist `{ ok: true, locale, key, provenance }`. `lockAcquireTimeoutMs` begrenzt
das Warten jedes Eintrags auf die Schreibsperre seiner Locale, und `onLockWait` meldet dieses
Warten. Ein Eintrag, dessen Sperre über das Timeout hinaus belegt bleibt, scheitert mit
`LOCK_CONTENDED`, und jeder spätere Eintrag, der dieselbe Sperre braucht, bekommt
`{ locale, key, ok: false, skipped: true, code: "LOCK_CONTENDED", message }`, statt erneut zu
warten; Einträge anderer Locales werden weiter entschieden.
```ts title="Signatur"
function approveEntries(
input: ReviewEntriesInput,
deps?: ReviewDecisionDeps,
): 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. |
| `entries` | `readonly ReviewBatchEntry[]` | yes | The entries to decide on, in the order they are carried out. |
| `reviewer` | `string` | no | Free text naming the reviewer, applied to every entry, with the rules of ReviewDecisionInput.reviewer. |
| `onLockWait` | `LockWaitListener` | no | Called while an entry waits on another process's write lock for its locale. Never called for a lock this process holds itself. |
| `lockAcquireTimeoutMs` | `number` | no | How long, in milliseconds, each entry waits for its locale's write lock before it fails with `LOCK_CONTENDED`, as ReviewDecisionInput.lockAcquireTimeoutMs does for one entry. Defaults to ten minutes per entry. |
**Rückgabe:** `ReviewEntriesResult`
**Wirft:** [`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#lock_timeout_invalid)
### rejectEntries [#rejectentries]
Führt `rejectEntry` pro Eintrag aus und entfernt jeden
abgelehnten Wert. Ein erfolgreiches Ergebnis ist `{ ok: true, locale, key, provenance }`. Ein
Sperr-Timeout überspringt die späteren Einträge, die diese Sperre brauchen, wie bei
`approveEntries`.
```ts title="Signatur"
function rejectEntries(
input: ReviewEntriesInput,
deps?: ReviewDecisionDeps,
): 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. |
| `entries` | `readonly ReviewBatchEntry[]` | yes | The entries to decide on, in the order they are carried out. |
| `reviewer` | `string` | no | Free text naming the reviewer, applied to every entry, with the rules of ReviewDecisionInput.reviewer. |
| `onLockWait` | `LockWaitListener` | no | Called while an entry waits on another process's write lock for its locale. Never called for a lock this process holds itself. |
| `lockAcquireTimeoutMs` | `number` | no | How long, in milliseconds, each entry waits for its locale's write lock before it fails with `LOCK_CONTENDED`, as ReviewDecisionInput.lockAcquireTimeoutMs does for one entry. Defaults to ten minutes per entry. |
**Rückgabe:** `ReviewEntriesResult`
**Wirft:** [`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#lock_timeout_invalid)
### approveLocale [#approvelocale]
Gibt die ganze Review-Warteschlange einer Locale frei, oder nur ihre Werte mit einer der `origins`,
in einem Schreibvorgang von `verbatra.provenance.json` unter der Schreibsperre der Locale, jede so
festgehalten, wie `approveEntry` eine festhält. Sie nimmt keinen erwarteten Wert und gibt frei, was
beim Aufruf in der Warteschlange steht, zeig der prüfenden Person die Warteschlange also vorher.
Gibt `{ locale, approved, sourceChanged }` zurück: die freigegebenen Keys und die Keys aus der
Warteschlange, die ungeprüft bleiben, weil sich ihr Quelltext seit dem Schreiben geändert hat. Ruft
keinen Provider auf und scheitert mit `PROVENANCE_FILE_UNWRITABLE`, statt Freigaben zu melden, die
sie nicht speichern konnte.
```ts title="Signatur"
function approveLocale(
input: ApproveLocaleInput,
deps?: ApproveLocaleDeps,
): 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 whose review queue is approved. Must be a configured target locale. |
| `origins` | `array` | no | Approve only the queued values with one of these origins, for a reviewer who has looked at, say, every fuzzy match. Defaults to every MachineClassOrigin. |
| `reviewer` | `string` | no | Free text naming the reviewer, with the rules of ReviewDecisionInput.reviewer. It is stored on every approved record. |
| `onLockWait` | `LockWaitListener` | no | Called while waiting on another process's write lock for the locale. 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. |
**Rückgabe:** `ApproveLocaleResult`
**Wirft:** [`REVIEWER_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#reviewer_invalid), [`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#lock_timeout_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), [`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), [`LOCALE_STATE_NOT_CARRIED_OVER`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#locale_state_not_carried_over), [`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), [`PROVENANCE_FILE_UNWRITABLE`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#provenance_file_unwritable)
### retranslateEntries [#retranslateentries]
Führt `retranslateEntry` pro Eintrag aus und macht damit bis zu einen Provider-Aufruf pro Eintrag.
Es ist kein `translate`-Lauf: `maxTokens` und `budgetBehavior` gelten nicht, und die Zahl der
Einträge ist die einzige Grenze für die Kosten. Ein abgeschlossenes Ergebnis ist
`{ ok: true, locale, key, result }`, wobei `result` das ist, was `retranslateEntry` zurückgegeben
hat, auch ein Wert, den das Integritäts-Gate abgelehnt hat. Ein Wert, den ein Mensch geschrieben
hat, scheitert mit `KEY_PROTECTED`, außer du übergibst `includeHuman: true`. Die Sperroptionen
wirken wie bei `approveEntries`, und das Warten endet vor dem Provider-Aufruf.
```ts title="Signatur"
function retranslateEntries(
input: RetranslateEntriesInput,
deps?: RetranslateEntryDeps,
): 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. |
| `entries` | `readonly BatchEntry[]` | yes | The entries to retranslate, in the order they are carried out. |
| `includeHuman` | `boolean` | no | Replace values a person wrote too, as RetranslateEntryInput.includeHuman does for one entry. Defaults to false. |
| `onLockWait` | `LockWaitListener` | no | Called while an entry waits on another process's write lock for its locale. Never called for a lock this process holds itself. |
| `lockAcquireTimeoutMs` | `number` | no | How long, in milliseconds, each entry waits for its locale's write lock before it fails with `LOCK_CONTENDED`, as RetranslateEntryInput.lockAcquireTimeoutMs does for one entry. The wait happens before the provider is called. Defaults to ten minutes per entry. |
**Rückgabe:** `RetranslateEntriesResult`
**Wirft:** [`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#lock_timeout_invalid)
Ein Fehler, an dem jeder Eintrag gleich scheitern würde, beendet die Provider-Aufrufe:
`MISSING_API_KEY`, `AUTH_FAILED`, `RATE_LIMITED` (auch ein erschöpftes Kontingent),
`NETWORK_POLICY_VIOLATION`, `PROVIDER_CONSTRUCTION_FAILED`, `CONFIG_INVALID` oder
`MACHINE_TRANSLATION_DISABLED`. Der Eintrag, der ihn ausgelöst hat, scheitert wie gewohnt, und jeder
Eintrag danach bekommt `{ locale, key, ok: false, skipped: true, code, message }` mit diesem Code,
ohne weiteren Provider-Aufruf.
Ein Sperr-Timeout überspringt die späteren Einträge, die diese Sperre brauchen, mit
`LOCK_CONTENDED`, wie bei `approveEntries`; bei einem Format, das alle Locales in einer Datei hält,
ist das jeder spätere Eintrag.
### BatchInterruptedError [#batchinterruptederror]
Wird von `approveEntries`, `rejectEntries` und `retranslateEntries` geworfen, wenn ein Fehler, der
kein Ergebnis eines einzelnen Eintrags ist, etwa ein unerwarteter Dateisystemfehler, einen Stapel
mittendrin stoppt. `results` enthält die Ergebnisse der vorher abgeschlossenen Einträge in ihrer
Reihenfolge, deren Schreibvorgänge auf der Platte bleiben; `entry` nennt das laufende
`{ locale, key }`, und `cause` ist der ursprüngliche Fehler.
Einträge nach `entry` sind nicht gelaufen.
```ts title="Signatur"
class BatchInterruptedError extends Error
```
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `results` | `readonly R[]` | yes | The outcomes of the entries completed before the batch stopped, in the order given. |
| `entry` | `BatchEntry` | yes | The entry the batch was carrying out when it stopped. |