---
title: "Modifier"
description: "Écris une valeur corrigée, ou prévisualise puis applique une recherche et un remplacement littéraux sur les valeurs de tes locales cibles."
type: "reference"
---
# Modifier
Écris une valeur corrigée, ou prévisualise puis applique une recherche et un remplacement littéraux sur les valeurs de tes locales cibles.
## Modifier une clé [#modifier-une-clé]
### editEntry [#editentry]
Écrit une correction saisie par un humain pour une clé et une locale. La valeur candidate passe la même barrière d'intégrité qu'une traduction de fournisseur avant que quoi que ce soit n'atteigne le disque ; à l'acceptation, le fichier de locale et l'entrée de verrou de cette clé sont mis à jour sous le verrou d'écriture de la locale. N'appelle jamais de fournisseur.
```ts title="Signature"
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. |
**Renvoie :** `EditEntryResult`
**Lève :** [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_format), [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_locale), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_invalid), [`UNKNOWN_KEY`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_key), [`KEY_PINNED`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#key_pinned), [`LOCK_CONTENDED`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#lock_contended), [`RUN_CANCELLED`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#run_cancelled), [`TARGET_UNWRITABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#target_unwritable), [`LOCALE_STATE_NOT_CARRIED_OVER`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_state_not_carried_over), [`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#lock_timeout_invalid), [`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#lock_file_invalid), [`PROVENANCE_FILE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#provenance_file_invalid)
**Exemple :** [Modifier et retraduire une seule clé](https://verbatra.kreitz-webdev.de/fr/docs/programmatic-api.md#modifier-et-retraduire-une-seule-clé)
Renvoie `{ accepted: true, value }`, ou `{ accepted: false, reason: "placeholder" | "markup" | "icu" | "degenerate" | "empty", value }` sans rien écrire ([la barrière d'intégrité](https://verbatra.kreitz-webdev.de/fr/docs/translation-safety.md#la-barrière-dintégrité)). Construis tout schéma sur les raisons à partir du tuple exporté `INTEGRITY_GATE_REASONS`. `"empty"` refuse une valeur vide pour une source qui a du texte ; efface une clé avec la sentinelle `[[CLEAR]]` du classeur. Un refus `placeholder` ou `markup` porte en plus `details` : chaque placeholder ou balise en cause, préfixé de `-` quand la valeur candidate l'a supprimé ou de `+` quand elle l'a inventé.
La valeur est enregistrée dans `verbatra.provenance.json` avec l'origine `human` ; passe `actor: "agent"` quand un agent d'IA l'a écrite, pour que l'enregistrement le dise (l'appelant l'affirme, rien ne le vérifie) ; tout autre `actor` lève une `TypeError` avant toute lecture. Un fichier de provenance corrompu lève `PROVENANCE_FILE_INVALID` avant que la valeur ne passe le contrôle, et rien n'est écrit ; celui d'un verbatra plus récent, ou celui que l'enregistrement ferait dépasser la taille que verbatra relit, est laissé intact et la valeur est écrite sans enregistrement.
Avec `actor: "agent"`, une clé qui correspond aux `pinnedKeys` de la config lève `KEY_PINNED` avant toute écriture. La modification d'une clé épinglée par une personne est acceptée.
`lockAcquireTimeoutMs` borne l'attente du verrou d'écriture de la locale avant que l'appel échoue avec `LOCK_CONTENDED` (dix minutes par défaut), `onLockWait` signale cette attente, et une borne invalide échoue avec `LOCK_TIMEOUT_INVALID` avant toute lecture.
## Remplacer entre locales [#remplacer-entre-locales]
Une recherche et un remplacement littéraux sur les valeurs de tes locales cibles, en deux étapes. `previewValueReplace` liste ce qui changerait et pourquoi certaines valeurs ne changeraient pas. `applyValueReplace` modifie celles que tu choisis et décide chacune de nouveau sous le verrou d'écriture. Aucune des deux ne cherche de correspondance dans la locale source, et aucune n'appelle de fournisseur.
### previewValueReplace [#previewvaluereplace]
Liste les valeurs cibles qui contiennent `find`, avec un statut pour chacune. La correspondance est littérale : pas de syntaxe de motif, pas de normalisation Unicode (un `find` en NFD ne correspond pas à une valeur en NFC) et pas de conversion des fins de ligne. `replace` est inséré tel que tu l'écris, donc `$&` et `$1` n'ont aucun sens particulier. `caseSensitive` vaut `true` par défaut. Une correspondance ne commence ni ne finit jamais au milieu d'une paire de substituts, et un `find` vide, un `find` de plus de 20 000 caractères, ou un `find` ou `replace` avec un substitut isolé lève `FIND_TEXT_INVALID`. Lecture seule.
```ts title="Signature"
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`. |
**Renvoie :** `ValueReplacePreview`
**Lève :** [`FIND_TEXT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#find_text_invalid), [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_format), [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_locale), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#source_invalid)
Chaque entrée a un statut. `ready` et `stale-source` peuvent être appliquées ; `stale-source` marque une clé dont le texte source a changé depuis l'enregistrement de sa traduction. `gate-refused` porte le `reason` que la valeur remplacée enfreindrait : elle est vérifiée contre le texte source actuel par [la même barrière d'intégrité](https://verbatra.kreitz-webdev.de/fr/docs/translation-safety.md#la-barrière-dintégrité) qu'une modification. Pour les formats ICU (next-intl et ARB), un remplacement est aussi refusé avec la raison `icu` s'il change ce que fait un argument : son type, un style ou un squelette de nombre ou de date, ou le nombre de `#` d'une branche plurielle, comparé à la valeur actuelle ou au texte source quand la valeur actuelle n'est pas de l'ICU valide. Un argument renommé en s'éloignant du texte source est refusé comme `placeholder`. `details` nomme chaque différence, `-` pour la valeur comparée et `+` pour la valeur remplacée. `too-long` est une valeur qui dépasserait 20 000 caractères ; ce n'est pas un refus d'intégrité et elle n'a pas de `reason`. `pinned` est une clé qui correspond à `pinnedKeys`. `protected` est une valeur qu'une personne a écrite ou importée, une valeur modifiée hors de verbatra, ou toute valeur quand le fichier de provenance est illisible, y compris celui d'une version plus récente de verbatra ; cela vaut quel que soit `humanEdits`. Une clé qui est les deux apparaît comme `pinned` avec `protected: true` et exige `includePinned` et `includeProtected`. `no-source-entry` est une clé sans texte source à comparer, et `unchanged` est une valeur que le remplacement laisse telle quelle.
Au plus 1 000 valeurs sont listées, dans l'ordre des `targetLocales` de la configuration, quel que soit l'ordre dans lequel `locales` les nomme. `truncated` indique quand davantage correspondaient, et `before` et `after` sont coupés à 200 caractères autour de la première correspondance. `valueHash` est le hachage que l'enregistrement de provenance stocke pour la valeur actuelle ; renvoie-le à `applyValueReplace`. `baselineUnavailable: true` indique que le fichier de verrou n'a pas pu être lu : aucune valeur n'a été comparée à son texte source enregistré et aucune n'est `stale-source`.
### applyValueReplace [#applyvaluereplace]
Remplace `find` dans les valeurs que tu as choisies, en recalculant chaque nouvelle valeur à partir du texte sur le disque sous le verrou d'écriture de la locale. Elle ne prend jamais de valeur calculée de l'appelant, et l'aperçu n'est qu'indicatif : chaque entrée est décidée de nouveau.
```ts title="Signature"
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`. |
**Renvoie :** `ApplyValueReplaceResult`
**Lève :** [`FIND_TEXT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#find_text_invalid), [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_format), [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#unknown_locale), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#locale_path_collision), [`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#lock_timeout_invalid), [`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#lock_file_invalid), [`PROVENANCE_FILE_INVALID`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#provenance_file_invalid)
Chaque entrée finit comme `applied`, `skipped` (avec sa raison), `refused` (avec la raison d'intégrité), `changed` ou `too-long`. `changed` signifie que la valeur ne correspond plus à son `valueHash`, ne contient plus `find` ou a disparu, et que rien n'a été écrit pour elle. Le hachage ignore la normalisation Unicode et les fins de ligne ; une valeur qui ne diffère de l'aperçu que par là est remplacée si `find` correspond encore, et est `changed` sinon. Une clé épinglée est ignorée sauf si `includePinned` est activé et que `actor` vaut `human`, et une valeur protégée est ignorée sauf si `includeProtected` est activé ; une clé qui est les deux exige les deux. Avec un fichier de provenance d'une version plus récente de verbatra, toute valeur compte comme protégée ; `includeProtected` la modifie quand même, mais le fichier reste intact et la valeur n'a pas d'enregistrement. Quand les mêmes `locale` et `key` apparaissent plusieurs fois, la première décide, quel que soit son `valueHash`, et chaque suivante est ignorée comme `duplicate-entry`.
Les locales sont traitées l'une après l'autre, dans l'ordre où elles apparaissent d'abord dans `entries`, chacune sous son propre verrou, avec une écriture du fichier de locale, une mise à jour du fichier de verrou et du fichier de provenance, et une mise à jour de la mémoire de traduction. Une clé périmée garde son ancien hachage de verrou, donc `check` la signale toujours comme périmée, et sa valeur n'entre pas dans la mémoire de traduction. Chaque valeur écrite reçoit un nouvel enregistrement de provenance avec `actor` pour origine et sans décision de relecture. `actor` est obligatoire, et une valeur autre que `human` ou `agent` lève une `TypeError` avant toute lecture.
Une locale qui échoue n'arrête pas les autres. `localeFailures` liste chacune avec son `code` et son `message`, comme `LOCK_CONTENDED` quand son verrou d'écriture n'est pas libre dans `lockAcquireTimeoutMs`, `TARGET_UNWRITABLE`, `SOURCE_INVALID` ou une erreur d'adaptateur. Une entrée que la barrière d'intégrité a refusée reste `refused`, et une qu'une vérification avait réglée avant l'échec garde son résultat ; les autres sont ignorées comme `locale-failed`, et rien n'a été écrit pour elles. Quand l'échec porte `fileWritten: true`, il est survenu après l'écriture du fichier de la locale, pendant la mise à jour du fichier de verrou ou du fichier de provenance, ou la libération du verrou d'écriture : les entrées acceptées sont `applied`, leurs valeurs sont sur le disque et le verrou ou la provenance peuvent être en retard, donc relis la locale avant de réessayer. Ne relance pas un remplacement dont le `find` apparaît dans son `replace` sans vérifier. L'attente du garde du fichier de verrou utilise la valeur par défaut de dix minutes, pas `lockAcquireTimeoutMs`.