Referencia del SDK

@verbatra/sdk es el motor sobre el que corre el comando verbatra. La CLI es una envoltura fina, así que todo lo que hace la línea de comandos lo puedes hacer en código. Esta página cataloga toda la superficie pública, agrupada por la tarea que hace cada punto de entrada. Para ejemplos de principio a fin, consulta Recetas del SDK.

Instalación

npm install --save-dev @verbatra/sdk
# pnpm
pnpm add -D @verbatra/sdk
# yarn
yarn add -D @verbatra/sdk

Requiere Node.js >=22.14.0.

La línea de pnpm instala bien, pero sale con 1 y ERR_PNPM_IGNORED_BUILDS: pnpm bloquea los scripts de instalación del SDK de Gemini incluido y de su protobufjs, y deja un pnpm-workspace.yaml sin responder con el que cualquier comando pnpm posterior del proyecto falla igual. Ejecuta pnpm approve-builds una vez y no apruebes ninguna de las dos entradas, o consulta la Solución de problemas para la solución no interactiva. Aquí no hay atajo con npx como en la CLI, porque estás importando una biblioteca, no ejecutando un binario.

Cada punto de entrada toma un objeto de entrada cuyo primer campo es la config validada (de loadConfig), salvo donde se indica. La mayoría también acepta un segundo argumento opcional deps que inyecta un registro, un constructor de proveedor o un sistema de archivos; puedes ignorarlo en el uso normal. Consulta El punto de inyección de dependencias para ver hasta dónde llega deps.fs.

Ejecuta traducciones

translate

El flujo de una sola pasada: leer el origen, comparar cada locale de destino con la línea base del bloqueo, enviar al proveedor las claves faltantes y modificadas, ejecutar las comprobaciones de integridad, escribir los archivos de locale y actualizar el bloqueo. Úsalo para scripts, pasos de build y jobs de CI.

Entrada: { config, cwd?, locales?, dryRun?, prune?, generatePlurals?, concurrency?, cache?, onProgress?, onLockWait?, lockAcquireTimeoutMs? }.

• locales restringe la ejecución a un subconjunto de los locales de destino configurados, igual que en check y diff. Un locale no configurado lanza UNKNOWN_LOCALE antes de leer o gastar nada. Omítelo para cubrir todos los locales de destino.
• dryRun lee, compara e informa sin construir ni llamar al proveedor y sin escribir nada.
• prune elimina del archivo escrito y del bloqueo las claves huérfanas (claves de destino ausentes del origen). generatePlurals sintetiza las formas de plural CLDR que faltan (solo i18next-JSON con un proveedor LLM). Ambos están desactivados por defecto; cuando se definen, cada uno anula la opción de configuración correspondiente para esa ejecución.
• concurrency traduce hasta ese número de locales de destino a la vez (por defecto 1, estrictamente en serie). Un valor menor que 1 lanza CONCURRENCY_INVALID; en una ejecución real, un valor mayor que 1 con maxTokens configurado lanza CONCURRENCY_BUDGET_CONFLICT (un dry-run queda exento). Un error de toda la ejecución que se levanta cuando ya hay locales en marcha impide que se arranque ningún locale más, y los locales en vuelo terminan y liberan sus bloqueos de escritura antes de que translate rechace, así que el rechazo llega después del más lento en vez de al instante.
• cache está activado por defecto y reutiliza la caché de memoria de traducción local (verbatra.cache.json, exportada también como CACHE_FILE_NAME); ponlo en false para omitir la caché en la ejecución (el --no-cache de la CLI).
• onProgress se llama a medida que avanza la ejecución (por inicio y fin de cada locale, y por sub-lote del proveedor), y onLockWait se dispara mientras el bloqueo de escritura de un locale está en disputa. Ambos son callbacks de notificación; el SDK no escribe nada por sí mismo. lockAcquireTimeoutMs anula cuánto tiempo reintenta un bloqueo de escritura en disputa antes de fallar con LOCK_CONTENDED.
• maxBatchSize, maxTokens y budgetBehavior son solo de configuración; no hay anulación por ejecución.

Devuelve un RunSummary (consulta su anatomía más abajo). Los problemas de toda la ejecución lanzan un SdkError; que falle un solo locale nunca lanza y queda como status: "failed" en la entrada de ese locale mientras la ejecución continúa.

watch

Vigila el archivo del locale de origen y vuelve a ejecutar translate en cada cambio asentado por el anti-rebote. Dispara una ejecución inicial inmediatamente al arrancar, y luego una ejecución por cambio asentado. Las ejecuciones se serializan: los cambios durante una ejecución se colapsan en un único seguimiento.

Entrada: { config, cwd?, locales?, debounceMs?, onRun, concurrency?, cache?, onProgress?, onLockWait?, lockAcquireTimeoutMs? }. debounceMs es 300 por defecto. onRun se llama una vez por ejecución con un WatchRunResult: { status: "succeeded", summary } o { status: "failed", error: { code, message } }. El SDK no registra nada; onRun es la única salida. concurrency, cache, onProgress, onLockWait y lockAcquireTimeoutMs se pasan a cada ejecución y se comportan igual que en translate. locales acota cada ejecución de la sesión a ese subconjunto y se valida una sola vez al arrancar, no en cada ciclo.

Devuelve un WatchController con un solo método, stop(), que cierra el watcher y espera la ejecución en curso. Tres problemas se rechazan al arrancar, antes de que el watcher exista, así que watch mismo rechaza en lugar de devolver un controlador: un concurrency que no es un entero de al menos 1 lanza CONCURRENCY_INVALID, un concurrency mayor que 1 contra una configuración que fija maxTokens lanza CONCURRENCY_BUDGET_CONFLICT (no hay watch en seco, así que el conflicto de presupuesto siempre aplica), y un archivo de origen ausente lanza SOURCE_UNREADABLE. Todo fallo posterior al arranque se comunica a través de onRun y la vigilancia continúa.

Inspecciona el estado sin escribir

Ninguna de estas llama a un proveedor, escribe un archivo ni muta el bloqueo.

doctor

Valida la configuración del proyecto y no gasta nada: no construye ningún proveedor, no hace ninguna petición de red y nunca lee el valor de una clave de API. Se ejecutan cinco comprobaciones, cada una con su propio veredicto pass, fail o skipped: la config carga y valida, el formato configurado resuelve a un adaptador, el ID de proveedor configurado resuelve a una fábrica, la variable de entorno de la que ese proveedor lee su clave está definida, y el archivo de locale fuente se puede leer. Todas las comprobaciones se ejecutan aunque una anterior haya fallado, así que una sola llamada informa de cada problema independiente. La clave de API se comprueba solo por nombre. La comprobación del archivo fuente lo lee y lo parsea en lugar de solo sondear su existencia, así que un directorio en su lugar, un archivo vacío y contenido malformado se informan todos aquí.

Entrada: { cwd?, configPath? }. No necesita una config ya cargada: doctor la carga por sí mismo, así que un proyecto sin config alguna sigue obteniendo un informe en lugar de un error lanzado. Devuelve un DoctorResult cuyo ok es true exactamente cuando ninguna comprobación falló. Lanza CONFIG_NOT_FOUND solo para un configPath explícito que no existe.

check

Informa del desfase por locale como contadores: missing (en el origen, ausente del destino), stale (el origen cambió desde la última traducción) y upToDate. Úsalo como puerta de CI.

Entrada: { config, cwd?, locales? }. Devuelve un CheckSummary cuyo inSync es true exactamente cuando cada locale comprobado no tiene nada faltante ni obsoleto.

diff

El hermano detallado de check: el mismo cálculo, pero devuelve las listas de claves por locale (missing, changed, orphaned) en lugar de contadores. Las claves huérfanas son solo informativas y nunca activan hasPendingChanges, porque una ejecución por defecto no elimina claves.

Entrada: { config, cwd?, locales? }. Devuelve un DiffSummary.

keyIntegrity

Informa, para las claves modificadas de cada locale, de si el valor de destino actual sigue coincidiendo con los marcadores de posición del origen y de si es ICU válido. Cada entrada lleva key, hasPlaceholders, matches, los tokens de marcador missing y extra en una discrepancia, e icuValid. Las entradas nunca llevan un valor de cadena de origen o destino. Este es el informe de integridad por clave que muestra Studio.

Entrada: { config, cwd?, locales?, keys? }. keys acota la comprobación; solo se comprueban las claves que están "modificadas" para un locale. Devuelve un LocaleKeyIntegrity por locale comprobado.

lockState

Informa de la existencia del archivo de bloqueo, su versión y el desfase por locale (número de claves de la línea base más contadores de faltantes, obsoletas y al día). exists viene de una sonda explícita, así que "todavía no hay archivo de bloqueo" y "un archivo de bloqueo vacío pero presente" siguen siendo distinguibles. Cuando el archivo está ausente el resultado es { exists: false } y no se lee nada más.

Entrada: { config, cwd?, locales? }. Devuelve un LockStateResult.

loadLockFile

Lee el propio archivo de bloqueo (verbatra.lock.json, exportado también como LOCK_FILE_NAME) y devuelve su forma parseada: { version, locales }, donde cada locale asigna claves al hash del contenido de origen desde el que se tradujeron por última vez. Un archivo ausente degrada a un bloqueo vacío, el mismo comportamiento de primera ejecución en el que se apoya translate; usa lockState cuando necesites distinguir la ausencia.

Entrada: { cwd? }. No necesita configuración. Devuelve un LockFile.

runStatus

Lee la instantánea de señales de revisión y uso de tokens que la ejecución más reciente de translate o watch (no en seco) persistió en .verbatra-local/run-status.json. Nunca lanza: un archivo ausente, corrupto o no reconocido degrada a { available: false }. Este archivo es telemetría de mejor esfuerzo, no una línea base de corrección.

Entrada: { cwd? }. No necesita configuración. Devuelve { available: false } o { available: true, version, generatedAt, usage?, budget?, locales }.

Operaciones de una sola clave

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

keyValue

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

Entrada: { config, cwd?, locale, key }. Devuelve { source, target? }; target está ausente exactamente cuando la clave todavía no existe en ese locale.

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.

Entrada: { config, cwd?, locale, key, value }. Devuelve un resultado de dos ramas: { accepted: true, value }, o { accepted: false, reason: "placeholder" | "icu" | "degenerate" | "empty", value } sin escribir nada. "empty" cubre un valor vacío o solo con espacios para un origen que sí tiene texto: una edición no puede expresar el vaciado de una clave, así que usa para eso el centinela [[CLEAR]] del libro.

retranslateEntry

Vuelve a ejecutar el proveedor para exactamente una clave y un locale: una llamada de una sola entrada a través de la misma ruta de proveedor que usa translate, protegida por las mismas comprobaciones de integridad. Al aceptarse escribe el archivo de locale y la entrada del bloqueo solo para esa clave.

Entrada: { config, cwd?, locale, key }. Devuelve { accepted: true, value, reviewReasons } (los códigos de motivo de revisión, si los hay, que aplican al nuevo valor) o { accepted: false, reason: "placeholder" | "icu" | "degenerate" | "empty", value }. A diferencia de translate, aquí un fallo del proveedor lanza: un ProviderError de @verbatra/ai-providers con un código estable como RATE_LIMITED o AUTH_FAILED.

Lecturas de contenido en bloque

localeValues

Lee el texto de origen y de destino actual de cada clave, en cada locale de destino solicitado, en un solo paso sobre los archivos que ya están en disco. Es la contraparte en bloque de keyValue: úsala cuando necesites contenido de traducción en bloque, por ejemplo para buscar o recorrer valores en lugar de solo nombres de clave, ya que keyValue solo responde para una clave a la vez. Solo lectura.

Entrada: { config, cwd?, locales? }; un locales omitido cubre cada locale de destino configurado. Devuelve un array de { locale, values }, una entrada por locale, donde values asigna cada clave a { source?, target? }. Un target ausente significa que la clave todavía no se ha traducido en ese locale; una source ausente significa que la clave está huérfana, presente en el locale de destino pero ya no en el origen.

Instantáneas de archivos de locale

Los bloques con los que se construye un vigilante de actualización en vivo como el de Studio: captura el estado de un archivo de locale y luego cuenta qué cambió desde entonces.

readLocaleFileSnapshot

Lee un archivo de locale (el locale de origen o cualquier locale de destino) y lo reduce a un hash de contenido por clave. Un archivo que todavía no existe se lee como una instantánea vacía en lugar de lanzar.

Entrada: { config, locale, cwd? }. Devuelve { locale, hashes }.

diffLocaleSnapshots

Compara dos instantáneas del mismo archivo, tomadas en momentos distintos, y cuenta las claves añadidas, modificadas y eliminadas entre ambas. Una función síncrona normal: diffLocaleSnapshots(previous, current) devuelve { added, changed, removed }. Solo contadores, nunca nombres de claves.

Rutas de locale

createLocalePathResolver

Resuelve la correspondencia entre locales y rutas del proyecto en ambos sentidos, a partir de files.pattern, los locales configurados y files.localeStyle. createLocalePathResolver(cwd, config) devuelve { pathFor, localeFor }: pathFor(locale) es la ruta absoluta del archivo de un locale, y localeFor(path) es el locale al que pertenece una ruta, o undefined para una ruta que este proyecto no posee. Todos los puntos de entrada del SDK resuelven rutas a través de él, así que un watcher o un panel construido sobre el SDK ve exactamente las rutas que escribe una ejecución.

Todas las comprobaciones se ejecutan al crear el resolver, antes de leer ningún archivo: un patrón y un estilo que no se pueden combinar, o un locale para el que el estilo no tiene una escritura correcta, lanzan LOCALE_LAYOUT_INVALID, y dos locales que resuelven a la misma ruta lanzan LOCALE_PATH_COLLISION.

El par de libro

La entrega para traductores humanos, como libro de Excel o como texto delimitado; consulta Traducción humana.

exportWorkbook

Escribe las cadenas que todavía necesitan traducción (claves faltantes y modificadas por locale; añade las sin cambios con includeUnchanged) en un libro .xlsx con estilos. Las filas llevan la misma señal de revisión que calcula una ejecución de translate. Sin llamada al proveedor, sin escritura del bloqueo.

Entrada: { config, cwd?, out?, locales?, includeUnchanged?, format? }. format es xlsx por defecto; csv y tsv escriben en su lugar un <locale>.csv o <locale>.tsv por locale, así que out nombra un directorio para ellos (creado si falta) y una ruta de archivo para xlsx. out es por defecto DEFAULT_WORKBOOK_PATH (verbatra-translations.xlsx) o DEFAULT_DELIMITED_PATH (verbatra-translations), ambos exportados como constantes. Los valores aceptados se exportan como EXCHANGE_FORMATS y el valor por defecto como DEFAULT_EXCHANGE_FORMAT, para que una herramienta que envuelve el SDK pueda validar un argumento de formato sin fijar la lista en el código. Devuelve { path, locales }: la ruta absoluta escrita y un número de filas por locale.

importWorkbook

Lee un libro rellenado de vuelta a los archivos de locale, ejecutando las mismas comprobaciones de desfase del origen e integridad que translate. Solo las filas aceptadas avanzan su línea base del bloqueo; una fila en blanco o rechazada se sigue exportando hasta que se resuelve de verdad.

Entrada: { config, workbook, cwd?, dryRun?, format? }. Con csv o tsv, workbook es un solo archivo de entrega o el directorio que contiene uno por locale, y la locale viene del nombre del archivo. Devuelve la misma forma RunSummary que translate (con needsReview siempre vacío, ya que no interviene ningún proveedor). Una hoja de un locale que no es un destino configurado hace fallar ese locale con CONFIG_INVALID como dato en el resumen, no como excepción.

Configuración

loadConfig

Encuentra, carga y valida la configuración del proyecto, devolviendo una VerbatraConfig. Opciones: { cwd?, configPath?, configOverride? }, con precedencia de configOverride (validar un objeto en memoria) sobre configPath (cargar un archivo explícito) sobre la búsqueda. La búsqueda empieza en cwd y cubre verbatra.config.ts (también .js/.cjs), la familia .verbatrarc (.json, .yaml, .yml, .js, .cjs, .ts) y una propiedad "verbatra" en package.json. Un glossary dado como ruta de archivo se lee y valida aquí, así que el código posterior siempre ve un registro plano.

Lanza CONFIG_NOT_FOUND cuando no se encuentra nada, CONFIG_INVALID cuando se encuentra una configuración pero es inválida. Consulta Archivo de configuración para el esquema.

loadConfigWithMeta

La misma carga, más la procedencia: devuelve { config, source, glossary }, donde source dice si la configuración vino de un acierto de búsqueda, de una ruta explícita o de una anulación en memoria (con el filepath absoluto cuando lo hay), y glossary registra si el glosario estaba ausente, en línea o resuelto desde un archivo. Úsalo cuando necesites mostrar de dónde salió la configuración.

readGlossaryFile

Lee un glosario respaldado por archivo directamente del disco y lo devuelve como un mapa plano de términos. Recibe { glossary }, la GlossaryProvenance de loadConfigWithMeta, de modo que el archivo que lee siempre es el que nombra la configuración; no hay ningún argumento de ruta. Úsalo en una herramienta de larga duración que deba mostrar el glosario tal como está ahora y no como estaba cuando se cargó la configuración.

Lanza GLOSSARY_NOT_FILE_BACKED cuando el glosario está en línea o ausente, y CONFIG_INVALID cuando el archivo falta, es demasiado grande, no es UTF-8, no es JSON válido o no es un mapa plano de cadenas.

updateGlossaryTerm

Añade, reemplaza o elimina exactamente un término de un glosario respaldado por archivo y devuelve el glosario tal como queda. Recibe { glossary, cwd?, term, translation }, donde translation es el texto nuevo o null para eliminar el término. El resto del archivo conserva su orden de claves y su sangría, la escritura es atómica y todo el ciclo de leer, modificar y escribir se mantiene bajo un bloqueo de glosario para todo el proyecto, así que dos ediciones simultáneas se serializan en vez de entrelazarse.

Un glosario en línea se rechaza con GLOSSARY_NOT_FILE_BACKED en lugar de convertirse: vive dentro de un módulo de configuración ejecutable. Un término o una traducción en blanco, y una edición cuyo resultado superaría el límite de 1 MiB del glosario, se rechazan con CONFIG_INVALID; una escritura fallida es GLOSSARY_UNWRITABLE.

defineConfig

Un ayudante identidad para escribir un verbatra.config.ts tipado: devuelve su argumento sin cambios y existe puramente para la inferencia de tipos y el autocompletado del editor, incluido el completado de los IDs de modelo conocidos del proveedor seleccionado. La restricción de modelos es solo al escribir; en tiempo de ejecución cualquier cadena no vacía pasa la validación.

verbatraConfigSchema

El esquema zod con el que valida loadConfig, exportado para que tu propia herramienta pueda validar un objeto de configuración igual que lo hace el SDK. Las claves desconocidas de nivel superior se rechazan, así que un secreto extraviado no puede esconderse en la configuración. La única excepción es $schema, una cadena opcional que se acepta para que una configuración JSON o YAML pueda apuntar a un editor hacia el documento JSON Schema que el paquete publica como @verbatra/sdk/config-schema.json. Se ignora en tiempo de ejecución.

scaffoldingMetadata

Metadatos de solo lectura de los que el comando init de la CLI deriva sus preguntas: providerEnv (de id de proveedor a la variable de entorno de la que se lee su clave), scaffoldModels (un modelo de scaffold por defecto por proveedor LLM), providerTokenLimitKeys (la clave de opción bajo la que cada proveedor LLM recibe su límite de tokens de salida) y supportedFormats (el conjunto cerrado de ids de formato). Lee la clave del límite de tokens de providerTokenLimitKeys en lugar de suponer una: Anthropic la llama maxTokens y los demás maxOutputTokens, el esquema valida estrictamente las opciones de cada proveedor, y DeepL no tiene entrada porque no recibe límite de tokens. El tipo ScaffoldableProviderId cubre los cuatro proveedores alojados; openai-compatible queda excluido porque no tiene una única variable de entorno obligatoria.

Redacción de secretos

redact

Elimina de una cadena las formas de clave API de proveedor y el valor exacto actual de cualquier variable de entorno de proveedor configurada, reemplazando cada coincidencia por [REDACTED]. @verbatra/studio y @verbatra/mcp la aplican ambos a cada valor que devuelven a un llamador que ellos mismos no generaron, como un término del glosario, una ruta de archivo o un mensaje de error de un sistema previo, así una clave ya presente en tu entorno o escrita en un archivo del proyecto nunca puede llegar a una pestaña del navegador, un agente ni una línea de log.

El punto de inyección de dependencias

deps.fs sustituye el puerto de sistema de archivos por el que viaja la propia I/O del SDK, con el tipo SdkFs. El punto de inyección es completo: el archivo de estado de la ejecución, el archivo de bloqueo, el glosario de la configuración, la I/O de libros e intercambio y los propios archivos de locale pasan todos por él, porque los adaptadores de formato leen y escriben a través de un puerto construido con ese mismo objeto. Así una ejecución entera se puede mantener en memoria, que es como las pruebas del propio SDK evitan tocar el disco y como una aplicación anfitriona puede respaldar parte de un proyecto con algo que no sea un disco local.

import { translate, type SdkFs } from "@verbatra/sdk";

const summary = await translate({ config }, { fs: inMemoryFs satisfies SdkFs });

Una implementación debe honrar dos puntos del contrato. Las lecturas están acotadas por tamaño: readFileBounded y readBytesBounded reciben un límite de bytes y reportan missing o too-large como estado en lugar de lanzar, que es lo que impide que un archivo hostil o accidentalmente enorme agote la memoria. Las escrituras deben ser atómicas, de modo que una caída a mitad de escritura nunca deje un archivo a medio escribir, y createExclusive debe ser atómica frente a otros procesos porque es la primitiva detrás del bloqueo de escritura por locale. Crear directorios es tarea de quien llama.

Lo único que deps.fs no alcanza es un deps.adapterRegistry suministrado por quien llama. Esos adaptadores los construyó quien llama, así que su acceso a archivos es el que quien llama haya cableado en ellos. Suministrar ambos significa que quien llama es dueño de ese cableado.

La anatomía de RunSummary

translate, importWorkbook y cada ejecución exitosa de watch resuelven a un RunSummary:

interface RunSummary {
  dryRun: boolean;          // true when nothing was written and no provider was called
  locales: LocaleSummary[]; // one entry per target locale, in config order
  succeeded: string[];      // locales whose run succeeded
  partial: string[];        // locales written with keys still missing; the CLI exits 1 on these
  failed: string[];         // locales whose run failed
  usage?: UsageSummary;     // summed input/output tokens; absent when no call reported usage
  budget?: RunBudget;       // present only when maxTokens is configured
}

interface LocaleSummary {
  locale: string;
  status: "succeeded" | "partial" | "failed";
  translated: string[];          // keys translated this run (in dry-run, keys that would be)
  cacheHits: string[];           // keys served from the translation-memory cache this run
  unchanged: string[];           // keys already up to date
  orphaned: string[];            // target keys with no matching source key (always reported)
  pruned: string[];              // orphaned keys removed this run; empty unless pruning is on
  invalidIcuSource: string[];    // source keys skipped for invalid ICU
  integrityMismatches: string[]; // translations withheld for a placeholder mismatch
  providerFailures: string[];    // keys withheld because nothing was translated for them
  budgetWithheld: string[];      // keys never sent because a "stop" budget already tripped
  generated: string[];           // CLDR plural forms synthesized this run
  unfilled: string[];            // import only: blank rows whose key still needs a translation
  malformedRows: { row: number; line?: number; column: string }[]; // import only: rows the reader could not parse
  duplicateKeys: { key: string; row: number; line?: number }[];    // import only: later rows for a duplicated key
  notices: LocaleNotice[];       // provider notices and SDK notices for this locale
  needsReview: { key: string; reasons: string[] }[]; // accepted keys flagged for a second look
  usage?: UsageSummary;          // this locale's summed tokens; absent if nothing reported usage
  error?: { code: string; message: string }; // present only when status is "failed"
}

Las partes que conviene conocer:

• needsReview lista claves aceptadas y escritas que las heurísticas de revisión marcaron, cada una con sus códigos de motivo: LENGTH_RATIO_OUTLIER, EQUALS_SOURCE, GLOSSARY_TERM_MISSED, INTEGRITY_REORDERED y PROVIDER_DEGRADED. Una señal de revisión es consultiva y nunca retiene una clave, así que una clave nunca aparece a la vez en needsReview y en integrityMismatches. Consulta Seguridad de la traducción para saber qué significa cada código y Revisión en Studio para trabajar la cola.
• notices vive por locale, nunca en el nivel superior. Cubre avisos del proveedor (por ejemplo, una degradación de DeepL) y avisos del SDK con los códigos PLURAL_CATEGORIES_INCOMPLETE, SUB_BATCH_FAILED, BLANK_ROW_BASELINE_RETAINED, BUDGET_TOKENS_EXCEEDED y CACHE_VERSION_UNRECOGNIZED. El aviso de caché es de toda la ejecución (un solo archivo, compartido por cada locale), así que se adjunta a cada locale de la ejecución.
• usage es undefined, nunca un cero inventado, siempre que nada en ese ámbito informara de uso: una ejecución en seco nunca llama a un proveedor, y DeepL nunca informa de tokens. RunSummary.usage es la suma sobre los locales.
• budget aparece solo cuando maxTokens está configurado: { maxTokens, behavior, supported, tokensUsed, exceeded }. Frente a un proveedor sin tokens o una ejecución en seco sigue presente con supported: false, así que la barrera es visiblemente inerte en lugar de dispararse en falso.
• error.code en un locale fallido es una cadena preservada (el código subyacente del proveedor o del adaptador, con LOCALE_FAILED solo como reserva), así que no lo trates como un conjunto cerrado.
• cacheHits lista las claves servidas desde la caché de memoria de traducción en lugar del proveedor. unfilled, malformedRows y duplicateKeys solo los rellena importWorkbook (una ejecución de translate los deja vacíos): una fila en blanco cuya clave todavía necesita traducción en el momento de la importación (tanto si se exportó como new como si se exportó como changed), una fila del libro que el lector no pudo parsear y una clave duplicada cuya primera aparición ganó. El line opcional de las dos últimas es la línea del archivo en la que empieza el registro, y solo está presente en una importación delimitada (csv o tsv).

El modelo de errores

Los fallos de toda la ejecución lanzan un SdkError: una sola clase, un code estable y un message sin secretos. Ramifica sobre el código, no sobre el mensaje. Los fallos por locale, los avisos del proveedor y los hallazgos de integridad se comunican como datos en el RunSummary, nunca se lanzan.

Dos excepciones a la regla de una sola clase de error: retranslateEntry relanza el ProviderError propio del proveedor cuando la llamada única falla, y runStatus no lanza nunca. Para cómo estos códigos se corresponden con los códigos de salida de la CLI, consulta CI y códigos de salida; para ayuda a partir del síntoma, consulta Solución de problemas.