---
title: "Editar"
description: "Escribe un valor corregido, o previsualiza y aplica una búsqueda y sustitución literal sobre los valores de tus locales de destino."
type: "reference"
---
# Editar
Escribe un valor corregido, o previsualiza y aplica una búsqueda y sustitución literal sobre los valores de tus locales de destino.
## Editar una clave [#editar-una-clave]
### editEntry [#editentry]
Escribe una corrección tecleada por un humano para una clave y un locale. El valor candidato pasa por la
misma puerta de integridad que una traducción del proveedor antes de que nada llegue
al disco; al aceptarse, el archivo de locale y la entrada del bloqueo de esa clave se actualizan dentro
del bloqueo de escritura del locale. Nunca llama a un proveedor.
```ts title="Firma"
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. |
**Devuelve:** `EditEntryResult`
**Lanza:** [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#unknown_format), [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#unknown_locale), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#source_invalid), [`UNKNOWN_KEY`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#unknown_key), [`KEY_PINNED`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#key_pinned), [`LOCK_CONTENDED`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#lock_contended), [`RUN_CANCELLED`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#run_cancelled), [`TARGET_UNWRITABLE`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#target_unwritable), [`LOCALE_STATE_NOT_CARRIED_OVER`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#locale_state_not_carried_over), [`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#lock_timeout_invalid), [`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#lock_file_invalid), [`PROVENANCE_FILE_INVALID`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#provenance_file_invalid)
**Ejemplo:** [Edita y retraduce una sola clave](https://verbatra.kreitz-webdev.de/es/docs/programmatic-api.md#edita-y-retraduce-una-sola-clave)
Devuelve `{ accepted: true, value }`, o
`{ accepted: false, reason: "placeholder" | "markup" | "icu" | "degenerate" | "empty", value }` sin
escribir nada ([la puerta de integridad](https://verbatra.kreitz-webdev.de/es/docs/translation-safety.md#la-puerta-de-integridad)).
Construye cualquier esquema sobre los motivos a partir de la tupla exportada `INTEGRITY_GATE_REASONS`.
`"empty"` rechaza un valor vacío para un origen con texto; vacía una clave con el centinela
`[[CLEAR]]` del libro. Un rechazo `placeholder` o `markup` lleva además `details`: cada marcador o
etiqueta causante, con `-` si la candidata lo perdió o `+` si lo inventó.
El valor queda registrado en `verbatra.provenance.json` con el origen `human`; pasa
`actor: "agent"` cuando lo escribió un agente de IA, para que el registro lo diga (lo afirma quien
llama, nada lo verifica); cualquier otro `actor` lanza un `TypeError` antes de leer nada. Un archivo de procedencia corrupto lanza `PROVENANCE_FILE_INVALID` antes
de pasar el valor por la puerta y no se escribe nada; uno de un verbatra más nuevo, o uno que el
registro haría crecer por encima de lo que verbatra vuelve a leer, se deja intacto y el valor se
escribe sin registro.
Con `actor: "agent"`, una clave que coincide con los `pinnedKeys` de la configuración lanza `KEY_PINNED` antes de escribir nada. La edición de una clave fijada por parte de una persona se acepta.
`lockAcquireTimeoutMs` limita la espera del bloqueo de escritura del locale antes de que la llamada falle con `LOCK_CONTENDED` (diez minutos por defecto), `onLockWait` informa de esa espera, y un límite no válido falla con `LOCK_TIMEOUT_INVALID` antes de leer nada.
## Reemplazar entre locales [#reemplazar-entre-locales]
Una búsqueda y sustitución literal sobre los valores de tus locales de destino, en dos pasos. `previewValueReplace` lista qué cambiaría y por qué algunos valores no cambiarían. `applyValueReplace` cambia los que eliges y decide cada uno otra vez bajo el bloqueo de escritura. Ninguna de las dos busca coincidencias en el locale de origen y ninguna llama a un proveedor.
### previewValueReplace [#previewvaluereplace]
Lista los valores de destino que contienen `find`, con un estado para cada uno. La coincidencia es literal: sin sintaxis de patrones, sin normalización Unicode (un `find` en NFD no coincide con un valor en NFC) y sin traducción de finales de línea. `replace` se inserta tal como lo escribes, así que `$&` y `$1` no significan nada especial. `caseSensitive` es `true` por defecto. Una coincidencia nunca empieza ni termina dentro de un par sustituto, y un `find` vacío, uno de más de 20.000 caracteres, o un `find` o `replace` con un sustituto suelto lanza `FIND_TEXT_INVALID`. Solo lectura.
```ts title="Firma"
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`. |
**Devuelve:** `ValueReplacePreview`
**Lanza:** [`FIND_TEXT_INVALID`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#find_text_invalid), [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#unknown_format), [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#unknown_locale), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#locale_path_collision), [`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#source_unreadable), [`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#source_invalid)
Cada entrada tiene un estado. `ready` y `stale-source` se pueden aplicar; `stale-source` marca una clave cuyo texto de origen cambió desde que se registró su traducción. `gate-refused` lleva el `reason` que rompería el valor reemplazado: se contrasta con el texto de origen actual en [la misma puerta de integridad](https://verbatra.kreitz-webdev.de/es/docs/translation-safety.md#la-puerta-de-integridad) que una edición. En los formatos ICU (next-intl y ARB) un reemplazo también se rechaza con el motivo `icu` si cambia lo que hace un argumento: su tipo, un estilo o esqueleto de número o fecha, o el número de `#` de una rama plural, comparado con el valor actual o con el texto de origen cuando el valor actual no es ICU válido. Un argumento renombrado alejándose del texto de origen se rechaza como `placeholder`. `details` nombra cada diferencia, `-` para el valor comparado y `+` para el reemplazado. `too-long` es un valor que superaría los 20.000 caracteres; no es un rechazo de integridad y no tiene `reason`. `pinned` es una clave que coincide con `pinnedKeys`. `protected` es un valor que escribió o importó una persona, un valor cambiado fuera de verbatra, o cualquier valor cuando no se puede leer el archivo de procedencia, también uno de una versión más nueva de verbatra; vale sea cual sea `humanEdits`. Una clave que es ambas cosas aparece como `pinned` con `protected: true` y necesita `includePinned` e `includeProtected`. `no-source-entry` es una clave sin texto de origen con el que contrastar, y `unchanged` es un valor que el reemplazo deja como está.
Se listan como máximo 1.000 valores, en el orden de los `targetLocales` de la configuración, sea cual sea el orden en que `locales` los nombre. `truncated` indica cuándo coincidieron más, y `before` y `after` se cortan a 200 caracteres alrededor de la primera coincidencia. `valueHash` es el hash que guarda el registro de procedencia para el valor actual; devuélvelo a `applyValueReplace`. `baselineUnavailable: true` indica que no se pudo leer el archivo de bloqueo, así que ningún valor se comparó con su texto de origen registrado y ninguno es `stale-source`.
### applyValueReplace [#applyvaluereplace]
Reemplaza `find` en los valores que elegiste, recalculando cada valor nuevo a partir del texto en disco dentro del bloqueo de escritura del locale. Nunca toma un valor calculado de quien llama, y la vista previa es solo orientativa: cada entrada se decide otra vez.
```ts title="Firma"
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`. |
**Devuelve:** `ApplyValueReplaceResult`
**Lanza:** [`FIND_TEXT_INVALID`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#find_text_invalid), [`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#unknown_format), [`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#unknown_locale), [`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#locale_layout_invalid), [`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#locale_path_collision), [`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#lock_timeout_invalid), [`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#lock_file_invalid), [`PROVENANCE_FILE_INVALID`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#provenance_file_invalid)
Cada entrada termina como `applied`, `skipped` (con su motivo), `refused` (con el motivo de integridad), `changed` o `too-long`. `changed` significa que el valor ya no coincide con su `valueHash`, ya no contiene `find` o ha desaparecido, y no se escribió nada para él. El hash ignora la normalización Unicode y los finales de línea; un valor que solo difiere así de la vista previa se reemplaza si `find` aún coincide, y es `changed` si ya no. Una clave fijada se omite salvo que se active `includePinned` y `actor` sea `human`, y un valor protegido se omite salvo que se active `includeProtected`; una clave que es ambas cosas necesita las dos. Con un archivo de procedencia de una versión más nueva de verbatra, todo valor cuenta como protegido; `includeProtected` aun así lo cambia, pero el archivo queda intacto y el valor no recibe registro. Si el mismo `locale` y `key` aparecen más de una vez, decide el primero, sea cual sea su `valueHash`, y cada posterior se omite como `duplicate-entry`.
Los locales se procesan uno tras otro, en el orden en que aparecen por primera vez en `entries`, cada uno bajo su propio bloqueo, con una escritura del archivo de locale, una actualización del archivo de bloqueo y del de procedencia, y una actualización de la memoria de traducción. Una clave obsoleta conserva su hash antiguo en el bloqueo, así que `check` la sigue marcando como desactualizada, y su valor no entra en la memoria de traducción. Cada valor escrito recibe un registro de procedencia nuevo con `actor` como origen y sin decisión de revisión. `actor` es obligatorio, y un valor distinto de `human` o `agent` lanza un `TypeError` antes de leer nada.
Un locale que falla no detiene a los demás. `localeFailures` lista cada uno con su `code` y `message`, como `LOCK_CONTENDED` cuando su bloqueo de escritura no queda libre dentro de `lockAcquireTimeoutMs`, `TARGET_UNWRITABLE`, `SOURCE_INVALID` o un error del adaptador. Una entrada que la puerta de integridad rechazó sigue devolviéndose como `refused`, y una que una comprobación había resuelto antes del fallo conserva su resultado; las demás se omiten como `locale-failed` y para ellas no se escribió nada. Cuando el fallo lleva `fileWritten: true`, ocurrió después de escribir el archivo del locale, al actualizar el archivo de bloqueo o el de procedencia, o al liberar el bloqueo de escritura: las entradas aceptadas son `applied`, sus valores están en disco y el bloqueo o la procedencia pueden ir atrasados, así que revisa el locale antes de reintentar. No vuelvas a ejecutar un reemplazo cuyo `find` aparece en su `replace` sin comprobarlo. La espera del propio guard del archivo de bloqueo usa el valor por defecto de diez minutos, no `lockAcquireTimeoutMs`.