Editar

Editar una claveCopiar enlace a esta sección

editEntryCopiar enlace a esta sección

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.

function editEntry(
  input: EditEntryInput,
  deps?: EditEntryDeps,
): Promise<EditEntryResult>;

Devuelve: EditEntryResult

Lanza: UNKNOWN_FORMAT, UNKNOWN_LOCALE, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, UNKNOWN_KEY, KEY_PINNED, LOCK_CONTENDED, RUN_CANCELLED, TARGET_UNWRITABLE, LOCALE_STATE_NOT_CARRIED_OVER, LOCK_TIMEOUT_INVALID, LOCK_FILE_INVALID, PROVENANCE_FILE_INVALID

Ejemplo: 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). 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 localesCopiar enlace a esta sección

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.

previewValueReplaceCopiar enlace a esta sección

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.

function previewValueReplace(
  input: PreviewValueReplaceInput,
  deps?: ValueReplaceDeps,
): Promise<ValueReplacePreview>;

Devuelve: ValueReplacePreview

Lanza: FIND_TEXT_INVALID, UNKNOWN_FORMAT, UNKNOWN_LOCALE, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, 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 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.

applyValueReplaceCopiar enlace a esta sección

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.

function applyValueReplace(
  input: ApplyValueReplaceInput,
  deps?: ValueReplaceDeps,
): Promise<ApplyValueReplaceResult>;

Devuelve: ApplyValueReplaceResult

Lanza: FIND_TEXT_INVALID, UNKNOWN_FORMAT, UNKNOWN_LOCALE, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, LOCK_TIMEOUT_INVALID, LOCK_FILE_INVALID, 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.