Preguntas frecuentes

Respuestas rápidas, cada una fundada en cómo se comporta verbatra de verdad. Para ayuda a partir de síntomas con mensajes de error, consulta Solución de problemas.

¿Cómo controlo el coste?

Cuatro palancas, todas libres de llamadas al proveedor hasta que tú decidas lo contrario:

• Las ejecuciones son incrementales por defecto: solo se envían al proveedor las claves faltantes o cuyo origen cambió desde la línea base del bloqueo. Volver a ejecutar un proyecto sin cambios no cuesta nada.
• --dry-run (o translate({ config, dryRun: true })) previsualiza exactamente qué se enviaría, sin llamada al proveedor y sin escrituras.
• maxTokens en la configuración fija un techo de tokens para toda la ejecución, y budgetBehavior decide qué pasa al alcanzarlo: "warn" (por defecto) lo señala y continúa, "stop" retiene cada clave aún no intentada; las claves retenidas se reintentan automáticamente en la siguiente ejecución.
• Gemini tiene un nivel de API gratuito de verdad, y el proveedor openai-compatible corre contra un modelo local a coste de API cero.

¿Cuánto cuesta realmente una ejecución?

Un ejemplo resuelto, para poner un orden de magnitud. Un proyecto con 400 claves a traducir a 3 idiomas, con el maxBatchSize por defecto de 50, envía 8 peticiones por idioma, 24 en total. Grosso modo 4 caracteres por token, con valores de origen de 40 caracteres y nombres de clave de 20, eso son unos 32.400 tokens de entrada y 22.800 de salida, es decir unos 55.000 tokens para toda la ejecución. En gemini-2.5-flash, con una tarifa ilustrativa de $0.10 por millón de tokens de entrada y $0.40 por millón de tokens de salida, salen unos 1,2 céntimos.

Las suposiciones detrás de esa cifra, para que la reescales a tu propio proyecto: 400 claves por idioma y 3 idiomas; valores de 40 caracteres y nombres de clave de 20; sin description, meaning, glosario ni tono; maxBatchSize en su valor por defecto; 4 caracteres por token; traducciones de longitud parecida a su origen. La tarifa es un marcador que hace concreta la aritmética, no un precio citado: consulta la real en la página de precios de tu proveedor, porque verbatra no sigue las tarifas de los proveedores y estas cambian.

Dos cosas pesan en la factura real más que el número de claves. Cada petición lleva una sobrecarga constante de unos 350 tokens (las reglas del sistema fijas y el esquema de salida), así que un maxBatchSize mayor reparte esa constante entre más claves y uno menor cuesta proporcionalmente más. Y esa cifra es solo el coste de la primera ejecución: las ejecuciones son incrementales, así que en el día a día pagas por el puñado de cadenas que cambiaste, no por el archivo entero. DeepL no encaja en esta fórmula en absoluto, ya que factura caracteres de origen en lugar de tokens.

Consulta Estimar el coste para el método, el caso de la traducción automática y cómo calibrar contra una ejecución real medida.

¿Con qué proveedor empiezo?

Gemini: tiene un nivel de API gratuito, así que puedes traducir un proyecto entero sin coste, y cambiar más tarde es editar un solo id en la configuración. Anthropic y OpenAI son las opciones de calidad de LLM de pago, DeepL y Google Cloud Translation son las opciones dedicadas de traducción automática, y openai-compatible mantiene todo en tu propio hardware. Consulta Proveedores para la comparación completa.

¿Puedo usar un modelo local?

Sí. El proveedor openai-compatible apunta verbatra a cualquier servidor que hable la API de chat de OpenAI, como LM Studio, Ollama o vLLM, a través de su opción baseUrl. La mayoría de los servidores locales no necesitan clave de API: cuando ni una variable nombrada por apiKeyEnvVar ni OPENAI_COMPATIBLE_API_KEY están definidas, verbatra envía el marcador fijo "local". Si tu servidor sí necesita una clave, nombra su variable de entorno con apiKeyEnvVar.

¿Cómo conservan las claves su orden?

Los adaptadores de la familia JSON, YAML y ARB hacen el viaje de ida y vuelta de los archivos en el orden exacto del documento: las claves existentes conservan sus posiciones (incluidas las claves con pinta de entero), y las claves nuevas se añaden en el orden del origen. Un archivo traducido produce un diff limpio contra su versión anterior. Consulta Formatos.

¿Por qué una traducción quedó marcada para revisión?

Las traducciones aceptadas pasan por heurísticas de revisión que marcan resultados sospechosos sin retenerlos: una longitud muy desproporcionada respecto al origen (LENGTH_RATIO_OUTLIER), una traducción idéntica al origen (EQUALS_SOURCE), un término del glosario que se perdió (GLOSSARY_TERM_MISSED), marcadores de posición reordenados (INTEGRITY_REORDERED) o una ruta de proveedor degradada (PROVIDER_DEGRADED). Las señales aterrizan en la lista needsReview del resumen de la ejecución y en la cola de revisión de Studio. Consulta Seguridad de la traducción.

¿Funciona verbatra en un monorepo?

Sí. La búsqueda de configuración empieza en el directorio de trabajo actual y sube, así que ejecutar desde el directorio de un paquete encuentra la configuración de ese paquete. Desde cualquier otro sitio, pasa --cwd <dir> (todos los comandos lo soportan) o apunta a un archivo concreto con --config <path>. En el SDK, los mismos mandos son cwd y configPath en loadConfig. El files.pattern y el archivo de bloqueo se resuelven contra el directorio de trabajo.

¿Qué debo confirmar?

Confirma tus archivos de locale y verbatra.lock.json: el bloqueo registra, por clave, el hash del contenido de origen del que salió cada traducción, y confirmarlo es lo que hace que las ejecuciones incrementales y la detección de desfase funcionen en todas partes, incluido CI. No confirmes .env, .env.local, .verbatra-local/ ni verbatra.cache.json; verbatra init añade los cuatro a .gitignore, y translate, watch e import completan un .gitignore existente al que le falte alguno. Consulta El archivo de bloqueo.

¿Cómo lo retraduzco todo?

Borrar el archivo de bloqueo no lo consigue: sin línea base, las claves que existen tanto en el origen como en el destino cuentan como al día, así que una ejecución tras borrar el bloqueo no traduce nada. Para reconstruir un locale desde cero, borra el archivo de ese locale y ejecuta verbatra translate: entonces cada clave es faltante y se traduce de nuevo. Para una sola clave, usa la acción de retraducir de Studio o retranslateEntry del SDK. Para retraducir claves cuyo texto de origen cambió, simplemente ejecuta translate: esa es la ruta incremental normal.

¿Usar la CLI implica instalar el SDK?

@verbatra/cli depende de @verbatra/sdk, así que instalar la CLI trae el SDK consigo automáticamente; no hay nada extra que instalar. Lo inverso también vale: el SDK funciona solo en tus propios scripts sin la CLI. Solo @verbatra/studio es una instalación aparte y opcional, cargada dinámicamente por el comando studio.

¿Dónde viven las claves de API?

Solo en variables de entorno: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, DEEPL_API_KEY o GOOGLE_TRANSLATE_API_KEY, más la variable que tú nombres para openai-compatible. translate, watch, doctor y studio cargan .env y .env.local desde el directorio de trabajo (las variables del entorno real ganan). El esquema de configuración rechaza las claves desconocidas precisamente para que un secreto no pueda acabar en un archivo confirmado, y los mensajes de error nombran la variable pero nunca un valor. Consulta Proveedores.

¿Qué comprueba realmente verbatra doctor?

Cinco cosas, todas sin llamar al proveedor, sin petición de red y sin leer el valor de una clave de API:

• Configuration: la configuración carga y pasa la validación.
• Format adapter: el format configurado se resuelve a un adaptador de archivo.
• Provider: el provider.id configurado se resuelve a una factory de proveedor.
• API key environment variable: la variable de entorno de la que ese proveedor lee su clave está definida (comprobada solo por nombre, nunca por valor).
• Source locale file: el archivo de la locale de origen existe en su ruta resuelta, es un archivo regular y se parsea bajo el formato configurado.

Cada comprobación se ejecuta incluso si una anterior falló, así que una sola ejecución informa de todos los problemas independientes a la vez; la excepción es la propia configuración: si falla al cargar, se omiten las cuatro comprobaciones que la necesitan.

verbatra doctor

Recurre a él en un checkout recién hecho, justo después de verbatra init, o cuando otro comando haya fallado y quieras la lista completa en lugar de solo el primer error. Consulta verbatra doctor para ver la tabla completa de comprobaciones y los códigos de salida.

¿Puede un agente de IA configurar o manejar verbatra por mí?

Cuatro superficies distintas para cuatro trabajos distintos. Configura verbatra con un agente de IA es un prompt listo para copiar y pegar en Claude Code, Cursor o cualquier agente de código que pueda leer tu proyecto y ejecutar comandos de shell: inspecciona una configuración de i18n existente, instala la CLI, genera una configuración a medida, ejecuta doctor, check, diff y translate --dry-run para mostrar el trabajo, y luego se detiene y te pide confirmación antes de llamar de verdad a un proveedor. Recetas para agentes y scripts es la referencia para construir tu propio bucle de agente sobre el mismo envoltorio --json y los mismos códigos de salida que usan esos comandos. Opera Studio con un agente del navegador es otra superficie distinta: un flag opcional --expose-agent-tools en verbatra studio que registra herramientas WebMCP para que un agente de IA en el navegador pueda manejar un proyecto ya configurado desde una pestaña abierta y autenticada del panel; no está pensado para la configuración inicial. verbatra mcp es la cuarta: un servidor MCP por stdio para un cliente MCP alojado en terminal o headless (Claude Desktop, Claude Code, Cursor) que quiere las mismas herramientas de estado, glosario y edición sin ningún navegador.

Ninguna de las cuatro le da a un agente la manera de gastar sin un humano en el bucle. translate en sí no tiene ninguna barrera de gasto propia, así que cada superficie orientada a agentes coloca un paso de confirmación, o un flag --allow-spend, entre el agente y una llamada real al proveedor.

¿Este sitio publica algo para agentes de IA y rastreadores?

Sí, tres archivos estáticos, generados en tiempo de build y siempre en inglés, sin importar qué locale estés viendo:

• /llms.txt: un índice curado con el título y la descripción de cada página de la documentación, agrupado igual que la barra lateral, como enlaces en Markdown.
• /llms-full.txt: toda la documentación en un solo archivo, el contenido renderizado de cada página concatenado en orden, para un agente que ingiere el contenido directamente en lugar de seguir enlaces.
• /.well-known/ai.txt: una política de uso que le dice a los rastreadores de IA que este proyecto tiene licencia MIT y que rastrear, indexar y citar este contenido es bienvenido.

Los tres están enlazados desde la columna del pie de página para agentes de IA.

¿El contenido de este sitio está traducido por IA?

Sí, las dos mitades, por dos mecanismos distintos. El texto de la interfaz (etiquetas de navegación, botones, el pie de página, el texto de la landing, las preguntas frecuentes de la landing) vive en messages/en.json y sus hermanos de, es y fr; esos se traducen automáticamente con verbatra mismo, contra el formato next-intl-json, a través del proveedor Gemini, ejecutado por pnpm i18n cada vez que cambia la fuente en inglés. Es el propio proyecto usando su propia herramienta (dogfooding). La prosa de la documentación que estás leyendo ahora mismo, cada guía y cada página de referencia incluida esta, es MDX con sufijo de locale (page.mdx, page.de.mdx, page.es.mdx, page.fr.mdx) y también está traducida con IA, solo que fuera de esa canalización automatizada: pnpm i18n solo traduce archivos JSON, XLIFF, YAML, ARB y properties, nunca Markdown, así que nunca toca estas páginas. Traducir una página de documentación es un paso aparte y manual cada vez que cambia la fuente en inglés.

Si algo en alemán, español o francés suena raro, abre un issue en cualquiera de los dos casos: el texto de la interfaz se corrige en la fuente en inglés y pnpm i18n lo retraduce automáticamente; para la prosa de la documentación, edita el archivo MDX directamente y envía un pull request.