Ejecuta traducciones

Traduce y vigilaCopiar enlace a esta sección

translateCopiar enlace a esta sección

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.

function translate(
  input: TranslateInput,
  deps?: TranslateDeps,
): Promise<RunSummary>;

Devuelve: RunSummary

Lanza: UNKNOWN_LOCALE, LOCALE_UNSUPPORTED_BY_PROVIDER, UNKNOWN_FORMAT, CONCURRENCY_INVALID, CONCURRENCY_BUDGET_CONFLICT, MAX_TOKENS_INVALID, LOCK_TIMEOUT_INVALID, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, PROVIDER_CONSTRUCTION_FAILED, NETWORK_POLICY_VIOLATION, CONFIG_INVALID, LOCK_FILE_INVALID, PROVENANCE_FILE_INVALID

Ejemplo: Traduce y lee el resumen

Lo que la tabla no cubre:

• cache es la caché de memoria de traducción local (verbatra.cache.json, exportada también como CACHE_FILE_NAME).
• humanEdits (desde 0.12.0): por defecto, las claves obsoletas cuyo valor escribió, importó o cambió una persona fuera de verbatra se conservan y se listan en LocaleSummary.protected. Consulta Proteger traducciones humanas.
• onProgress recibe los eventos de progreso descritos abajo.
• maxBatchSize y budgetBehavior son solo de configuración; no hay anulación por ejecución.

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. Consulta la anatomía de RunSummary.

Eventos de progreso Disponible a partir de 0.12.0Copiar enlace a esta sección

onProgress recibe un ProgressEvent, una unión discriminada por type. Una versión menor puede añadir tipos, así que ignora un type que no reconozcas.

provider-retry no nombra ningún locale, porque un solo proveedor atiende toda la ejecución. Gemini informa de la espera y del estado, Anthropic, OpenAI, OpenCode y openai-compatible informan del intento cuando su cliente lo inicia, y DeepL, Google Cloud Translation y LibreTranslate no informan de nada. Un dry run y una estimación solo emiten locale-started, locale-finished y run-finished. Los registros de progreso --json de la CLI se limitan a los cuatro tipos originales: locale-started, sub-batch, locale-finished y run-finished.

extract, diff con unused y doctor con literals aceptan su propio onProgress. Recibe un ScanProgressEvent, { type: "files-scanned", scanned, total }, una vez tras cada archivo de código de la aplicación que lee el escaneo.

Un CreateProvider propio recibe un tercer argumento, CreateProviderHooks, siempre que una ejecución informa de progreso. Llama a su onRetry con { attempt, delayMs?, status? } y los reintentos de tu proveedor aparecerán como eventos provider-retry.

resolveDryRun Disponible a partir de 0.11.0Copiar enlace a esta sección

Responde si un conjunto de opciones de ejecución se resuelve como un dry run. Toma el dryRun y el estimate que estás a punto de pasar a translate y devuelve si esa ejecución construirá un proveedor, escribirá un archivo o gastará algo. Es el único sitio donde se decide que estimate implica dryRun, así que recurre a él siempre que algo alrededor de una ejecución tenga que saberlo de antemano, en lugar de repetir la implicación y acabar desviándote de ella.

function resolveDryRun(input: {
  readonly dryRun?: boolean | undefined;
  readonly estimate?: boolean | undefined;
}): boolean;

Devuelve: boolean

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

declare const config: VerbatraConfig;

const options = { dryRun: false, estimate: true };
resolveDryRun(options); // true

const summary = await translate({ config, ...options });

watchCopiar enlace a esta sección

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.

function watch(
  input: WatchInput,
  deps?: WatchDeps,
): Promise<WatchController>;

Devuelve: WatchController

Lanza: UNKNOWN_LOCALE, LOCALE_UNSUPPORTED_BY_PROVIDER, CONCURRENCY_INVALID, LOCK_TIMEOUT_INVALID, CONCURRENCY_BUDGET_CONFLICT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, NETWORK_POLICY_VIOLATION, PROVIDER_CONSTRUCTION_FAILED, CONFIG_INVALID

Ejemplo: Vigila en un proceso de larga duración

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, causeCode?, hint? } }, donde causeCode nombra el error con código que envuelve el fallo y hint es el siguiente paso que da errorHint. onReady se llama una vez, cuando pasan las comprobaciones de arranque y justo antes de la ejecución inicial, para que puedas anunciar la sesión antes de la salida de esa ejecución. Si onReady lanza, el watcher se cierra y watch rechaza con ese error antes de que empiece ninguna ejecución. 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. Cada código de la línea Lanza se rechaza al arrancar, antes de que el watcher exista, así que watch mismo rechaza en lugar de devolver un controlador. Dos de ellos pesan más en una sesión que en una sola ejecución: un concurrency mayor que 1 contra una configuración que fija maxTokens lanza siempre CONCURRENCY_BUDGET_CONFLICT, porque no existe un watch en dry run, y, desde 0.12.0, un proveedor que no se puede construir, por ejemplo porque falta su variable de API key, lanza PROVIDER_CONSTRUCTION_FAILED una sola vez en lugar de hacer fallar cada ejecución. Todo fallo posterior al arranque se comunica a través de onRun y la vigilancia continúa.

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

Elimina todos los bloqueos de escritura que tiene el proceso actual, para un proceso que va a terminar sin dejar que acaben sus ejecuciones en curso: la CLI lo llama cuando una interrupción detiene translate o import, y cuando una segunda interrupción fuerza la parada de watch. Las ejecuciones que tomaron esos bloqueos pierden su protección, así que llámalo solo justo antes de que el proceso termine. No recibe argumentos y rechaza con un AggregateError que nombra las rutas de los bloqueos solo cuando un bloqueo retenido no se pudo borrar, tras intentarlo con cada bloqueo. Un bloqueo que una operación aún en curso está tomando, o intenta tomar, mientras se ejecuta se rechaza con RUN_CANCELLED y no deja ningún archivo; espera como máximo tres segundos a esa adquisición.

function releaseHeldLocks(): Promise<void>;

Devuelve: void

Un bloqueo que queda atrás de todos modos, porque un proceso se mató de golpe, no lo necesita: una ejecución en espera en la misma máquina ve que el proceso registrado ya no existe y recupera el bloqueo por sí misma. Consulta el bloqueo de escritura.

PseudolocalizaciónCopiar enlace a esta sección

pseudolocalize Disponible a partir de 0.11.0Copiar enlace a esta sección

Construye un locale falso solo con las cadenas de origen, de modo que los recortes de maquetación y las cadenas que nunca se extrajeron para traducir aparezcan antes de que exista clave de API alguna. Cada valor se acentúa, se expande alrededor de un tercio de su longitud traducible y se envuelve en los marcadores de límite [ y ], mientras que los placeholders quedan intactos en todas las sintaxis que reconocen los adaptadores, incluidas las ramas plural y select de ICU, las etiquetas de marcado y las secuencias de escape. No construye ningún proveedor, no lee ninguna clave de API y no hace ninguna petición de red.

function pseudolocalize(
  input: PseudolocalizeInput,
  deps?: PseudolocalizeDeps,
): Promise<PseudolocalizeResult>;

Devuelve: PseudolocalizeResult

Lanza: PSEUDO_OUTPUT_CONFLICT, UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, TARGET_UNWRITABLE

Ejemplo: Construye un pseudolocale

Cada valor generado pasa por la misma puerta de integridad que debe superar la traducción de un proveedor. Uno que no la superaría se copia literalmente del origen y se nombra en copied en lugar de escribirse roto, así que la entrada sigue presente y sigue renderizándose.

mode elige la transformación de PSEUDO_MODES: accented, la de por defecto, o bidi, que en su lugar envuelve cada palabra de texto traducible en una marca y una anulación de derecha a izquierda y deja fuera los placeholders, la sintaxis ICU, el marcado, los dígitos y la puntuación, sin acentuar nada. En modo bidi, locale es ar-XB por defecto, un código que se resuelve con dirección de derecha a izquierda; consulta verbatra pseudo para ver cómo sus reglas de plural del árabe encajan con las formas de plural de tu origen.

locale es en-XA por defecto y out es .verbatra-local/pseudo, que verbatra init ya añade a .gitignore; el files.pattern configurado se expande dentro, así que el archivo conserva la disposición que espera la aplicación. Un pseudolocale que nombre un locale configurado, o que aterrizaría sobre un archivo de locale configurado, se rechaza con PSEUDO_OUTPUT_CONFLICT antes de leer o escribir nada, así que no puede sobrescribir una traducción real ni hacerse pasar por una; lo mismo ocurre con un out absoluto, que se salga de cwd o que nombre el propio cwd, como ., y, cuando deps.fs implementa realpath como el valor por defecto, con uno que acaba así, en el directorio de un archivo de locale configurado o sobre otro archivo del que depende el proyecto, una vez resueltos los enlaces simbólicos. Como el archivo vive fuera de files.pattern, translate nunca gasta en él y check y diff nunca informan de él como desfasado.

Devuelve un PseudolocalizeResult: el locale, el mode, el path absoluto, cuántas entries se procesaron, cuántas se transformed, las claves que se copied y si se escribió algo (written). La transformación es determinista, así que una segunda ejecución sobre un origen sin cambios no reescribe nada e informa de written como false. Para xliff y apple-xcstrings, cuyos escritores solo parchean un documento que ya existe, la salida se vuelve a copiar desde el origen en cada escritura, así que una clave añadida al origen después de la primera ejecución sigue llegando al pseudolocale, y a un XLIFF copiado se le reescribe su target-language al pseudolocale.

Catálogos tipadosCopiar enlace a esta sección

generateTypes Disponible a partir de 0.11.0Copiar enlace a esta sección

Declara el catálogo de origen de un proyecto como TypeScript: una unión de todas las claves que contiene y, por clave, los argumentos que interpola su mensaje. Tipa una función de traducción contra el resultado y una clave mal escrita o un argumento de interpolación que falta pasa a ser un error de compilación en lugar de un fallo de búsqueda en tiempo de ejecución. No gasta nada: no se construye ningún proveedor, no se lee ninguna variable de entorno con una clave de API y no se hace ninguna petición de red.

function generateTypes(
  input: GenerateTypesInput,
  deps?: GenerateTypesDeps,
): Promise<GenerateTypesResult>;

Devuelve: GenerateTypesResult

Lanza: TYPES_OUTPUT_CONFLICT, TYPES_UNWRITABLE, UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID

Ejemplo: Genera un catálogo tipado

Lee un archivo (el catálogo del locale de origen) y escribe un archivo (la declaración); nunca toca un archivo de locale de destino. Las claves son exactamente lo que el adaptador de formato ya produjo, en orden del documento, así que dos ejecuciones sobre un catálogo sin cambios escriben bytes idénticos. Los argumentos vienen de los tokens de placeholder que el adaptador extrajo, salvo en los formatos de mensajes ICU (next-intl-json y arb), donde cada mensaje se lee con el mismo parser ICU que usa el adaptador. Cada clave se emite como un literal de cadena entrecomillado, así que una con un punto, una palabra reservada, un dígito inicial, una comilla, o incluso la clave vacía, se declara tal cual en lugar de descartarse o volver a partirse, y una clave que el adaptador informó en excludedLeafPaths no se declara en absoluto.

Lo que se niega a afirmar importa tanto como lo que declara. Un mensaje sin placeholders recibe una forma que convierte en error de tipo pasar cualquier argumento; uno cuyos placeholders nombran sus argumentos recibe una forma de objeto; uno con placeholders numerados o anónimos recibe una tupla readonly. Un argumento ICU que solo usan algunas ramas select o plural se declara como miembro opcional. Los tipos de argumento vienen solo de lo que el catálogo registra: number para un argumento ICU number, plural o selectordinal y para un formateador o una conversión numéricos, Date | number para un argumento ICU date o time y un formateador datetime de i18next, string para un argumento ICU select y una conversión printf de cadena, y un alias de string | number en los demás casos, nunca un any permisivo. Una interpolación sin escapar de i18next ({{- name}}) se declara con el nombre detrás de su prefijo. Un mensaje que el adaptador informó como inválido, uno que parece nombrar y numerar sus argumentos a la vez, y uno con un índice de placeholder fuera de rango se declaran con sus argumentos informados en unresolved en lugar de declararse en silencio como si no tomaran ninguno. Los hermanos de plural nunca se agrupan: cada uno se declara por su cuenta, y los que el adaptador marcó como plurales se listan.

out toma por defecto DEFAULT_TYPES_PATH (verbatra-types.d.ts). Antes de leer o escribir nada, TYPES_OUTPUT_CONFLICT rechaza un out que no nombra ningún archivo (también uno que termina en un separador de ruta), es absoluto, se sale de cwd con .., nombra el propio cwd (.) o no termina en .ts, .mts o .cts, y uno que nombra un archivo de locale configurado, el archivo de bloqueo, el archivo de procedencia, la caché de memoria de traducción, un archivo donde verbatra busca su configuración, configPath, el archivo de configuración desde el que se cargó config, o glossaryPath, el archivo de glosario al que apunta; los nombres se comparan sin distinguir mayúsculas de minúsculas, y cuando deps.fs implementa realpath, como hace el valor por defecto, las mismas comprobaciones se repiten sobre el sitio donde cae la ruta una vez resueltos los enlaces simbólicos. Una ejecución que genera también se niega, con el mismo código, a reemplazar un archivo existente que no empieza con la línea de cabecera que escribe verbatra, y deja ese archivo intacto. La lista completa está en la página de verbatra types. Con check activado no se escribe nada en absoluto, no se rechaza nada por su contenido, y la ejecución solo informa de si el archivo confirmado sigue coincidiendo, que es justo lo que quiere una puerta de CI.

Devuelve un GenerateTypesResult: el path absoluto, el sourcePath del que se construyó, cuántas keys se declararon y cuántas de ellas toman al menos un argumento que verbatra pudo determinar (withArguments, que nunca cuenta una clave de unresolved), las claves unresolved y las excluded y plural, si se escribió algo (written), si el archivo en disco estaba stale al arrancar la ejecución, si faltaba del todo (missing, un archivo que falta también está stale), y si esta fue una ejecución de check.