Edita y revisa

Operaciones de una sola claveCopiar enlace a esta sección

Estos son los puntos de integración que usa Verbatra Studio; úsalos para construir tu propia herramienta de revisión. Las que reciben locale y key los resuelven de nuevo en cada llamada y lanzan UNKNOWN_LOCALE o UNKNOWN_KEY cuando alguno no existe.

keyValue Disponible a partir de 0.5.0Copiar enlace a esta sección

Lee el valor de origen actual de una clave y, cuando existe, su valor de destino actual para un locale. Solo lectura.

function keyValue(
  input: KeyValueInput,
  deps?: KeyValueDeps,
): Promise<KeyValueResult>;

Devuelve: KeyValueResult

Lanza: UNKNOWN_FORMAT, UNKNOWN_LOCALE, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, UNKNOWN_KEY

Ejemplo: Edita y retraduce una sola clave

Devuelve { source, target? }; target está ausente exactamente cuando la clave todavía no existe en ese locale y, cuando está, llega con provenance, la KeyProvenance interpretada de la clave: { origin, provider?, model?, reviewState, reviewer? }.

El resultado también lleva description cuando el archivo de origen le da una a la clave: una @key.description de ARB, una nota de XLIFF o un comentario de gettext, .strings de Apple o .resx de .NET.

keyContext Disponible a partir de 0.12.0Copiar enlace a esta sección

Lee lo que necesita quien traduce para escribir una clave en un locale de destino: todo lo que devuelve keyValue, más los términos del glosario que se aplican al texto de origen y el maxLength de la clave. Pasa un draft para comprobarlo contra esos términos. Solo lectura. Para volver a leer del disco un glosario basado en archivo, recibe loaded de loadConfigWithMeta, no una configuración sin más.

function keyContext(
  input: KeyContextInput,
  deps?: KeyContextDeps,
): Promise<KeyContext>;

Devuelve: KeyContext

Lanza: UNKNOWN_FORMAT, UNKNOWN_LOCALE, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, UNKNOWN_KEY

Un glosario ilegible no lanza: glossary queda vacío y glossaryNotice lleva el código y el mensaje redactado del error. draftCheck indica, por término aplicable, si el borrador usa la traducción exigida y qué variantes prohibidas usa.

localeHistory Disponible a partir de 0.12.0Copiar enlace a esta sección

Lista los commits de git recientes que cambiaron el archivo de origen o uno de destino, del más nuevo al más antiguo. Solo lectura; ejecuta git log mediante el execFile inyectable.

function localeHistory(
  input: LocaleHistoryInput,
  deps?: LocaleHistoryDeps,
): Promise<LocaleHistoryResult>;

Devuelve: LocaleHistoryResult

Lanza: LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION

Cada commit lleva hash, author (el nombre tras .mailmap, nunca el correo), authorDate, subject y touchedPaths. limit vale LOCALE_HISTORY_LIMIT_DEFAULT (50) por defecto, como máximo LOCALE_HISTORY_LIMIT_CAP (200), redondeado hacia abajo y al menos 1. Los caracteres de control y de formato bidireccional se quitan de author y subject; un commit con metadatos ilegibles se omite. Sin git o sin repositorio, o si git log supera LOCALE_HISTORY_TIMEOUT_MS o LOCALE_HISTORY_MAX_OUTPUT_BYTES, el resultado es { available: false, reason }, un motivo de LOCALE_HISTORY_UNAVAILABLE_REASONS. Consulta Studio y MCP.

editEntry Disponible a partir de 0.5.0Copiar 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). 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.

retranslateEntry Disponible a partir de 0.5.0Copiar enlace a esta sección

Vuelve a ejecutar el proveedor para exactamente una clave y un locale por la misma ruta de proveedor y la misma puerta de integridad que translate, y al aceptarse escribe el archivo de locale y la entrada del bloqueo solo para esa clave.

function retranslateEntry(
  input: RetranslateEntryInput,
  deps?: RetranslateEntryDeps,
): Promise<RetranslateEntryResult>;

Devuelve: RetranslateEntryResult

Lanza: MACHINE_TRANSLATION_DISABLED, LOCK_TIMEOUT_INVALID, UNKNOWN_FORMAT, UNKNOWN_LOCALE, LOCALE_UNSUPPORTED_BY_PROVIDER, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, UNKNOWN_KEY, KEY_PINNED, KEY_PROTECTED, PROVIDER_CONSTRUCTION_FAILED, NETWORK_POLICY_VIOLATION, CONFIG_INVALID, LOCK_CONTENDED, RUN_CANCELLED, TARGET_UNWRITABLE, LOCALE_STATE_NOT_CARRIED_OVER, LOCK_FILE_INVALID, PROVENANCE_FILE_INVALID, SENSITIVE_CONTENT_WITHHELD

Ejemplo: Edita y retraduce una sola clave

Devuelve { accepted: true, value, reviewReasons } (los códigos de motivo de revisión del nuevo valor) o el rechazo que devuelve editEntry. A diferencia de translate, aquí un fallo del proveedor lanza: un ProviderError, exportado desde @verbatra/sdk, con un code estable como RATE_LIMITED o AUTH_FAILED. Con provider: { id: "none" } lanza primero MACHINE_TRANSLATION_DISABLED, antes de leer o bloquear nada.

El nuevo valor queda registrado en verbatra.provenance.json como machine, con el id del proveedor que respondió y el modelo configurado. Un proveedor de tu propio createProvider queda registrado con su propio id, y sin el modelo cuando ese id no coincide con el configurado. Un archivo de procedencia corrupto lanza PROVENANCE_FILE_INVALID antes de llamar al proveedor.

Una clave cuyo valor escribió, importó o cambió una persona fuera de verbatra lanza KEY_PROTECTED dentro del bloqueo de escritura, antes de llamar al proveedor, salvo que pases includeHuman: true o la configuración fije humanEdits: "overwrite"; con un archivo de procedencia de un verbatra más nuevo, cualquier valor existente cuenta como protegido. Una clave que coincide con pinnedKeys lanza KEY_PINNED antes de construir el proveedor, incluso con includeHuman.

approveEntry Disponible a partir de 0.12.0Copiar enlace a esta sección

Registra que una persona revisó el valor actual de una clave en un locale y lo acepta. Solo escribe verbatra.provenance.json, nunca un archivo de locale ni el archivo de bloqueo, y no llama a ningún proveedor. La aprobación también guarda el hash de origen de la clave en el archivo de bloqueo, así que vuelve a contar como sin revisar en cuanto cambia el origen; cualquier escritura posterior que cambie el valor empieza un registro nuevo, sin revisar.

function approveEntry(
  input: ReviewDecisionInput,
  deps?: ReviewDecisionDeps,
): Promise<ReviewDecisionResult>;

Devuelve: ReviewDecisionResult

Lanza: REVIEWER_INVALID, LOCK_TIMEOUT_INVALID, UNKNOWN_FORMAT, UNKNOWN_LOCALE, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, UNKNOWN_KEY, LOCK_CONTENDED, RUN_CANCELLED, REVIEW_VALUE_CHANGED, LOCALE_STATE_NOT_CARRIED_OVER, REVIEW_SOURCE_CHANGED, LOCK_FILE_INVALID, PROVENANCE_FILE_INVALID, PROVENANCE_FILE_UNWRITABLE

Ejemplo: Recorre la cola de revisión

expectedValue es el texto que vio quien revisa, o pasa expectedValueHash con el valueMarker que lo generó: la llamada lanza REVIEW_VALUE_CHANGED cuando la clave no tiene valor o tiene otro, y REVIEW_SOURCE_CHANGED cuando el origen cambió desde que se escribió el valor. reviewer es texto libre opcional de 1 a 64 caracteres y sin caracteres de control (si no, REVIEWER_INVALID), se guarda en el archivo con commit y verbatra nunca lo rellena. Devuelve { locale, key, provenance }. Un valor sin registro previo, o uno cambiado fuera de verbatra, se registra con el origen unknown.

rejectEntry Disponible a partir de 0.12.0Copiar enlace a esta sección

Registra que una persona revisó el valor actual de una clave en un locale y lo rechaza, y lo quita del archivo de locale y del archivo de bloqueo, así que check y diff la reportan como faltante y el siguiente translate la vuelve a llenar (con provider: { id: "none" } sigue faltando hasta que alguien escriba uno). El registro de procedencia se queda como rejected con un hash del texto eliminado y la entrada de memoria correspondiente de esta máquina se borra; un translate posterior omite cualquier acierto exacto o difuso de la memoria para la clave que coincida con ese hash, así que ninguna memoria de ninguna máquina devuelve el texto. No llama a ningún proveedor.

function rejectEntry(
  input: ReviewDecisionInput,
  deps?: ReviewDecisionDeps,
): Promise<ReviewDecisionResult>;

Devuelve: ReviewDecisionResult

Lanza: REVIEWER_INVALID, LOCK_TIMEOUT_INVALID, UNKNOWN_FORMAT, UNKNOWN_LOCALE, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, UNKNOWN_KEY, LOCK_CONTENDED, RUN_CANCELLED, REVIEW_VALUE_CHANGED, LOCALE_STATE_NOT_CARRIED_OVER, TARGET_UNWRITABLE, REVIEW_REJECT_UNSUPPORTED, REVIEW_RESTORE_FAILED, LOCK_FILE_INVALID, PROVENANCE_FILE_INVALID, PROVENANCE_FILE_UNWRITABLE

Ejemplo: Recorre la cola de revisión

La entrada se comprueba como en approveEntry, salvo que un origen desactualizado no impide un rechazo. Devuelve { locale, key, provenance }. Un formato que conserva una clave que no recibió, XLIFF, lanza REVIEW_REJECT_UNSUPPORTED después de restaurar el archivo.

Ambas llamadas toman el bloqueo de escritura del locale con lockAcquireTimeoutMs y onLockWait como en editEntry; LOCK_TIMEOUT_INVALID indica que el límite no es un número entero de milisegundos de al menos 0. El tiempo de espera no limita el bloqueo del archivo de bloqueo que se toma para registrar la decisión, que siempre admite los diez minutos por defecto.

Ninguna informa de una decisión que no pudo guardar: un archivo de procedencia de un verbatra más nuevo, o uno que la decisión haría crecer por encima del tamaño que verbatra vuelve a leer, lanza PROVENANCE_FILE_UNWRITABLE antes de escribir nada.

createValueMarker Disponible a partir de 0.12.0Copiar enlace a esta sección

Crea la marca con la que una superficie muestra un valor sin su texto: mark(value) devuelve [redacted length=<n> hash=<h>], y hash(value) devuelve h, un HMAC hexadecimal de 16 dígitos con una sal aleatoria (o la salt indicada), así que un hash solo coincide con la misma marca. Pásala como valueMarker a approveEntry o rejectEntry para aceptar expectedValueHash en lugar de expectedValue. verbatra mcp --redact-values crea una en cada arranque del servidor.

function createValueMarker(salt?: Uint8Array): ValueMarker;

Devuelve: ValueMarker

Lecturas de contenido en bloque Disponible a partir de 0.10.0Copiar enlace a esta sección

localeValuesCopiar enlace a esta sección

Lee el texto de origen y de destino actual de cada clave en los locales de destino solicitados en una sola pasada sobre los archivos en disco, por ejemplo para buscar valores en lugar de nombres de clave: la contraparte en bloque de keyValue. Solo lectura.

function localeValues(
  input: LocaleValuesInput,
  deps?: LocaleValuesDeps,
): Promise<readonly LocaleValues[]>;

Devuelve: readonly LocaleValues[]

Lanza: UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, UNKNOWN_LOCALE

Ejemplo: Lee todos los valores de golpe

Un locales omitido cubre cada locale de destino configurado. Devuelve un { locale, keys, values } por locale: keys lista cada clave en el orden de origen, luego las que solo están en el destino, y values asigna cada clave a { source?, target? }. Sin target, todavía no está traducida ahí; sin source, está huérfana (ya no está en el origen). values no tiene prototipo: cada clave, incluso __proto__ o constructor, es una propiedad propia, y una clave ausente se lee como undefined.

Cada par con un target lleva además provenance, la misma KeyProvenance que informa keyValue.

localeValuesPage Disponible a partir de 0.12.0Copiar enlace a esta sección

Lee una página de localeValues, acotada si quieres a keys exactas o a una query que se compara con la clave, el texto de origen y el de destino sin distinguir mayúsculas, y devuelve un cursor para la página siguiente. El servidor MCP y la herramienta de agente verbatra_locale_values de Studio paginan con ella. Solo lectura.

function localeValuesPage(
  input: LocaleValuesPageInput,
  deps?: LocaleValuesDeps,
): Promise<LocaleValuesPage>;

Devuelve: LocaleValuesPage

Lanza: UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, UNKNOWN_LOCALE, PAGE_CURSOR_INVALID, PAGE_LIMIT_INVALID

Devuelve { locales, nextCursor? }: cada locale con una entrada en la página lleva entries, cada una { key, source?, target?, provenance? } como la informa localeValues, ordenadas por locale y luego por clave. Una página tiene como mucho limit entradas: PAGE_LIMIT_DEFAULT (200) por defecto, PAGE_LIMIT_CAP (1000) como máximo. Pasa nextCursor como cursor, con los mismos filtros, hasta que falte. Cada llamada vuelve a leer los archivos, así que un cursor cuya clave se movió o ya no existe se rechaza en vez de saltar o repetir entradas.

Un cursor tiene como mucho PAGE_CURSOR_MAX_LENGTH (512) caracteres. El servidor MCP y Studio aceptan una query de como mucho LOCALE_VALUES_QUERY_MAX_LENGTH (500) caracteres.

Revisión y retraducción por lotes Disponible a partir de 0.12.0Copiar enlace a esta sección

Cada una de estas llamadas ejecuta la llamada de una sola clave correspondiente una vez por entrada, en orden, y devuelve { results } con un resultado por entrada. Una entrada fallida no detiene el lote: su resultado es { locale, key, ok: false, code, message }, con el código del SdkError, del error de adaptador o del ProviderError y un mensaje censurado. Cualquier otro error detiene el lote con un BatchInterruptedError. Una lista entries vacía devuelve results vacío.

approveEntriesCopiar enlace a esta sección

Ejecuta approveEntry por entrada con las mismas comprobaciones; reviewer se aplica a todas las entradas. Un resultado correcto es { ok: true, locale, key, provenance }. lockAcquireTimeoutMs limita la espera de cada entrada por el bloqueo de escritura de su locale, y onLockWait informa de esa espera. Una entrada cuyo bloqueo sigue ocupado pasado el tiempo límite falla con LOCK_CONTENDED, y cada entrada posterior que necesita el mismo bloqueo recibe { locale, key, ok: false, skipped: true, code: "LOCK_CONTENDED", message } en lugar de volver a esperar; las entradas de otros locales se siguen decidiendo.

function approveEntries(
  input: ReviewEntriesInput,
  deps?: ReviewDecisionDeps,
): Promise<ReviewEntriesResult>;

Devuelve: ReviewEntriesResult

Lanza: LOCK_TIMEOUT_INVALID

rejectEntriesCopiar enlace a esta sección

Ejecuta rejectEntry por entrada y elimina cada valor rechazado. Un resultado correcto es { ok: true, locale, key, provenance }. Un tiempo límite de bloqueo omite las entradas posteriores que necesitan ese bloqueo, como en approveEntries.

function rejectEntries(
  input: ReviewEntriesInput,
  deps?: ReviewDecisionDeps,
): Promise<ReviewEntriesResult>;

Devuelve: ReviewEntriesResult

Lanza: LOCK_TIMEOUT_INVALID

approveLocale Disponible a partir de 0.12.0Copiar enlace a esta sección

Aprueba toda la cola de revisión de un locale, o solo sus valores con uno de los origins, en una sola escritura de verbatra.provenance.json con el bloqueo de escritura del locale, cada aprobación registrada igual que la registra approveEntry. No recibe ningún valor esperado y aprueba lo que la cola contiene cuando se ejecuta, así que enséñale antes la cola a quien revisa. Devuelve { locale, approved, sourceChanged }: las claves aprobadas y las claves de la cola que quedan sin revisar porque su origen cambió desde que se escribieron. No llama a ningún proveedor y falla con PROVENANCE_FILE_UNWRITABLE en lugar de informar de aprobaciones que no pudo guardar.

function approveLocale(
  input: ApproveLocaleInput,
  deps?: ApproveLocaleDeps,
): Promise<ApproveLocaleResult>;

Devuelve: ApproveLocaleResult

Lanza: REVIEWER_INVALID, LOCK_TIMEOUT_INVALID, UNKNOWN_FORMAT, UNKNOWN_LOCALE, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, LOCK_CONTENDED, RUN_CANCELLED, LOCALE_STATE_NOT_CARRIED_OVER, LOCK_FILE_INVALID, PROVENANCE_FILE_INVALID, PROVENANCE_FILE_UNWRITABLE

retranslateEntriesCopiar enlace a esta sección

Ejecuta retranslateEntry por entrada, así que hace hasta una llamada al proveedor por entrada. No es una ejecución de translate: maxTokens y budgetBehavior no se aplican, y el número de entradas es el único límite de lo que gasta. Un resultado completado es { ok: true, locale, key, result }, donde result es lo que devolvió retranslateEntry, incluido un valor que la puerta de integridad rechazó. Un valor que escribió una persona falla con KEY_PROTECTED salvo que pases includeHuman: true. Las opciones de bloqueo funcionan como en approveEntries, y la espera termina antes de llamar al proveedor.

function retranslateEntries(
  input: RetranslateEntriesInput,
  deps?: RetranslateEntryDeps,
): Promise<RetranslateEntriesResult>;

Devuelve: RetranslateEntriesResult

Lanza: LOCK_TIMEOUT_INVALID

Un error que haría fallar igual a todas las entradas detiene las llamadas al proveedor: MISSING_API_KEY, AUTH_FAILED, RATE_LIMITED (que incluye una cuota agotada), NETWORK_POLICY_VIOLATION, PROVIDER_CONSTRUCTION_FAILED, CONFIG_INVALID o MACHINE_TRANSLATION_DISABLED. La entrada que lo provocó falla como siempre, y cada entrada posterior recibe { locale, key, ok: false, skipped: true, code, message } con ese código, sin otra llamada al proveedor.

Un tiempo límite de bloqueo omite con LOCK_CONTENDED las entradas posteriores que necesitan ese bloqueo, como en approveEntries; en un formato que guarda todos los locales en un solo archivo, son todas las entradas posteriores.

BatchInterruptedError Disponible a partir de 0.12.0Copiar enlace a esta sección

Lo lanzan approveEntries, rejectEntries y retranslateEntries cuando un error que no es el resultado de una sola entrada, como un fallo inesperado del sistema de archivos, detiene un lote a medias. results contiene los resultados de las entradas completadas antes, en orden, cuyas escrituras siguen en disco; entry nombra el { locale, key } que se estaba ejecutando y cause es el error original. Las entradas posteriores a entry no se ejecutaron.

class BatchInterruptedError<R = ReviewBatchOutcome | RetranslateBatchOutcome> extends Error