Proveedores

Selecciona un proveedor por id en el bloque provider de tu configuración. Anthropic, OpenAI, Gemini, OpenCode y openai-compatible son modelos de lenguaje; DeepL, Google Cloud Translation y LibreTranslate son servicios de traducción automática; none desactiva la traducción automática. La cobertura de idiomas está en Idiomas y locales, y qué recibe cada proveedor en Tratamiento de datos y privacidad.

¿Cuál elijo?Copiar enlace a esta sección

Cualquier proveedor funciona con cualquier formato y comando, y cambiar más tarde significa editar un solo id.

Las claves vienen del entornoCopiar enlace a esta sección

verbatra nunca lee una clave de la configuración. Cada proveedor alojado lee una variable:

Defínela en .env (que verbatra init añade a .gitignore), en tu shell o en el almacén de secretos de tu CI, y nunca la confirmes. Una variable no definida o vacía falla con MISSING_API_KEY, nombrando la variable pero nunca un valor. openai-compatible y libretranslate normalmente no necesitan clave.

AnthropicCopiar enlace a esta sección

provider: {
  id: "anthropic",
  options: {
    model: "claude-sonnet-4-6", // example model id
    maxTokens: 4096,
  },
}

Lee ANTHROPIC_API_KEY.

OpenAICopiar enlace a esta sección

provider: {
  id: "openai",
  options: {
    model: "gpt-5.4-mini", // example model id
    maxOutputTokens: 4096,
  },
}

Lee OPENAI_API_KEY.

GeminiCopiar enlace a esta sección

provider: {
  id: "gemini",
  options: {
    model: "gemini-2.5-flash", // example model id
    maxOutputTokens: 4096,
  },
}

Lee GEMINI_API_KEY.

DeepLCopiar enlace a esta sección

provider: {
  id: "deepl",
  options: {
    glossaryId: "<your-glossary-id>",
  },
}

Lee DEEPL_API_KEY; options puede ser {}. DeepL no tiene modelo ni límite de tokens de salida, y se degrada con un aviso en lugar de fallar:

• Los placeholders viajan como marcadores numerados en una etiqueta ignorada (Hello {{name}} como Hello <x>{0}</x>) y se restauran. PLACEHOLDER_UNSUPPORTED retiene un valor con un placeholder no literal o con <, >, { o } en el resto del texto, y un resultado con un marcador perdido, repetido, cambiado o sin etiqueta, una entidad desconocida o una etiqueta ajena. El marcado sin placeholders va como texto plano.
• El tono se asigna a la formalidad (formal más, informal menos, neutral se omite). Una clave del nivel gratuito no envía ninguna formalidad e informa FORMALITY_DOWNGRADED. Una clave de pago la pide con prefer_more o prefer_less, así que un idioma sin formalidad, como el sueco, vuelve al registro predeterminado con el mismo aviso en lugar de fallar. El glosario no se aplica.

verbatra incluye la tabla de idiomas fechada de DeepL y rechaza un idioma que no está en ella con LOCALE_UNSUPPORTED_BY_PROVIDER antes de gastar nada. Un glossaryId solo funciona cuando los dos idiomas están en la lista de glosarios de DeepL (como DE, EN, FR, JA, ZH).

Google Cloud TranslationCopiar enlace a esta sección

provider: {
  id: "google-translate",
  options: {},
}

Lee GOOGLE_TRANSLATE_API_KEY, una clave de API de un proyecto de Google Cloud con la Cloud Translation API activada. Solo funciona Basic (v2): Advanced (v3) necesita una cuenta de servicio.

• Los placeholders se enmascaran como en DeepL, dentro de <span translate="no">; los saltos de línea, tabuladores y dobles espacios también se retienen.
• Códigos. Cada código enviado se comprueba como BCP 47 bien formado antes de cualquier llamada (en_US falla con INVALID_REQUEST). Se permiten códigos regionales; un par que Google rechaza falla con INVALID_REQUEST desde la API.

verbatra incluye la tabla de idiomas fechada de Google y rechaza un idioma que no está en ella antes de gastar nada. Un código regional cuyo idioma solo aparece en la lista como un todo, como de-AT, se envía tal como está escrito con un aviso.

OpenCodeCopiar enlace a esta sección

Aquí solo funcionan los modelos de OpenCode Zen que se sirven por /chat/completions (la tabla de modelos indica el endpoint de cada uno). OpenCode reserva Go y los modelos gratuitos de Zen para sus propios clientes.

provider: {
  id: "opencode",
  options: {
    model: "glm-5.3", // example: a Zen model served over Chat Completions
    maxOutputTokens: 4096,
  },
}

Endpoint fijo, sin baseUrl. Lee OPENCODE_API_KEY.

openai-compatibleCopiar enlace a esta sección

Cualquier servidor que hable la API Chat Completions de OpenAI: LM Studio, Ollama, vLLM o una API alojada.

El servidor debe servir Chat Completions en <baseUrl>/chat/completions con salida de JSON schema estricto. Las pasarelas que solo atienden a sus propias apps cliente no funcionan.

provider: {
  id: "openai-compatible",
  options: {
    baseUrl: "http://192.168.178.74:1234/v1",
    model: "qwen2.5-14b-instruct", // example: whatever your server exposes
    maxOutputTokens: 1024,
  },
}

Para una API alojada como Mistral:

provider: {
  id: "openai-compatible",
  options: {
    baseUrl: "https://api.mistral.ai/v1",
    model: "mistral-large-latest", // example: check Mistral's current model list
    maxOutputTokens: 4096,
    apiKeyEnvVar: "MISTRAL_API_KEY",
  },
}

La respuesta usa el mismo esquema estricto que openai; el primer objeto JSON balanceado se toma de cualquier prosa o bloque de código que lo rodee y se valida. verbatra init --provider openai-compatible --base-url <url> --model <name> escribe este bloque (init), y --api-key-env-var <NAME> añade el nombre de la variable.

Las claves son opcionalesCopiar enlace a esta sección

La clave se resuelve en orden:

1. apiKeyEnvVar: si está definido, su variable debe contener una clave, o la ejecución falla con MISSING_API_KEY.
2. OPENAI_COMPATIBLE_API_KEY: se usa si está definida y no vacía.
3. "local": un placeholder fijo y no secreto, que es lo que hace funcionar un servidor sin clave.

apiKeyEnvVar no puede nombrar la variable de un proveedor alojado, y el cliente nunca lee OPENAI_API_KEY, así que una clave alojada nunca llega a un baseUrl personalizado.

Elegir un modelo localCopiar enlace a esta sección

Prefiere un modelo multilingüe ajustado por instrucciones y sin razonamiento, tan grande como tu hardware ejecute bien, como qwen2.5-14b-instruct. Los modelos de razonamiento y las compilaciones muy cuantizadas tienden a envolver o truncar la respuesta, lo que falla como INVALID_RESPONSE u OUTPUT_TRUNCATED.

LibreTranslateCopiar enlace a esta sección

Un servidor LibreTranslate autoalojado (Argos Translate, sin modelo de lenguaje). verbatra solo llama a su API HTTP, así que la licencia AGPL-3.0 del servidor no se extiende a tu proyecto.

provider: {
  id: "libretranslate",
  options: {
    baseUrl: "http://localhost:5000",
  },
}

Sus idiomas son los modelos instalados en tu servidor:

docker run -p 5000:5000 libretranslate/libretranslate --load-only en,de,fr

• Clave. LIBRETRANSLATE_API_KEY se envía como api_key solo cuando está definida. Un servidor arrancado con --api-keys hace fallar la ejecución con MISSING_API_KEY cuando no está definida, y con AUTH_FAILED cuando la rechaza.
• Los placeholders se enmascaran como en DeepL, como marcadores {0} sin etiqueta; el marcado se conserva, así que solo cuentan las llaves junto a un placeholder.
• Marcado. Un valor con etiquetas de estilo HTML se envía en formato html: el texto dentro de las etiquetas se traduce, las etiquetas se quedan (una frase que cruza una etiqueta puede resentirse) y las etiquetas cambiadas se rechazan.
• Comprobación de idiomas. Cada destino avisa LOCALE_UNVERIFIED_BY_PROVIDER en cada ejecución; verbatra doctor --locales --live los comprueba contra el servidor.

verbatra init --provider libretranslate --base-url <url> escribe este bloque.

noneCopiar enlace a esta sección

Desactiva la traducción automática por política, para una norma que prohíbe enviar cadenas a cualquier servicio.

provider: { id: "none" }

options puede omitirse o ser {}. No se construye ningún proveedor, no se lee ninguna clave y no se hace ninguna petición; lo que hace cada comando en su lugar está en Trabajar sin traducción automática.

Tono y glosario entre proveedoresCopiar enlace a esta sección

Una petición lleva solo los términos del glosario de su locale de destino, y cada salida se comprueba contra ellos.

Comportamiento que todo proveedor comparteCopiar enlace a esta sección

LotesCopiar enlace a esta sección

El trabajo de un locale se envía en sublotes secuenciales de como mucho maxBatchSize entradas. Un sublote fallido se retiene y se reintenta en la siguiente ejecución mientras los demás siguen avanzando. DeepL y Google Cloud Translation además dividen un sublote para respetar sus propios topes por petición.

ReintentosCopiar enlace a esta sección

Los límites de tasa y los errores de servidor se reintentan con espera, por el cliente en OpenAI, OpenCode, openai-compatible, Anthropic y DeepL y por verbatra en Gemini. Google Cloud Translation y LibreTranslate no reintentan. Gemini respeta una espera indicada de hasta 5 segundos y hace fallar una más larga, como una cuota diaria agotada, al instante con RATE_LIMITED, que nombra la espera.

Tiempo de espera de peticiónCopiar enlace a esta sección

requestTimeoutMs (por defecto 120000 ms) evita que un servidor que nunca responde atasque una ejecución y retenga el bloqueo de escritura de un locale. Súbelo para un modelo local lento o un maxBatchSize grande.

provider: {
  id: "openai-compatible",
  options: {
    baseUrl: "http://192.168.178.74:1234/v1",
    model: "qwen2.5-14b-instruct",
    maxOutputTokens: 1024,
    requestTimeoutMs: 300000, // 5 minutes
  },
}

• Por intento. Cada reintento recibe el límite completo. Los proveedores LLM también reintentan un intento que agotó el tiempo, y todos menos Gemini un error de conexión, así que un servidor colgado tarda hasta tres límites más las pausas.
• El error nombra la causa. TIMEOUT significa que un intento no recibió respuesta a tiempo; las conexiones rechazadas repetidas fallan como PROVIDER_ERROR.
• DeepL no puede abortar una petición en vuelo, así que una ejecución interrumpida la deja resolverse en DeepL.

Códigos de locale enviados al proveedorCopiar enlace a esta sección

Los archivos, el bloqueo y la memoria siempre usan los códigos de tu configuración. Solo la petición se traduce a lo que espera el proveedor:

Un LLM recibe además los nombres de idioma, escritura y región. DeepL no tiene un inglés ni un portugués genéricos como destino, así que un destino que acaba siendo un en o pt escueto (como en-AU) se rechaza antes de la ejecución: asígnalo a EN-GB, EN-US, PT-BR o PT-PT.

localeMap sustituye el código por locale:

provider: {
  id: "deepl",
  options: {
    localeMap: {
      "en-AU": "EN-GB",
      "fr-BE": "FR-FR",
    },
  },
}

• Las claves deben ser sourceLocale o un locale de destino como en la configuración, o la configuración falla con CONFIG_INVALID. El mapa va bajo options, en todos los proveedores salvo none.
• Los valores son cadenas no vacías de 64 caracteres como máximo, enviadas sin cambios: como código de idioma a un proveedor de traducción automática, en lugar del código a un LLM ("pt-BR (Brazilian Portuguese)" funciona), cuyos nombres de idioma siguen saliendo de la clave. Un EN o PT escueto para DeepL falla con INVALID_REQUEST; un valor que el proveedor rechace hace fallar su sublote.
• Efecto en la memoria. Solo las cadenas nuevas y cambiadas se envían con un código nuevo. Un mapa no vacío forma parte de la huella de la memoria, así que cambiarlo abre un compartimento aparte.

Comprobar el soporte de idiomas de un proveedorCopiar enlace a esta sección

Cada locale configurado se evalúa antes de gastar nada:

Un locale no admitido se rechaza con LOCALE_UNSUPPORTED_BY_PROVIDER (salida 2) antes de construir ningún proveedor; una advertencia nunca rechaza y aparece como aviso. verbatra doctor informa de cada veredicto, y su opción --live comprueba la lista actual del proveedor, pero translate siempre usa la tabla incluida. Para un idioma añadido después, asigna el locale en localeMap: un código explícito se envía con un aviso, no se rechaza.

Errores estructuradosCopiar enlace a esta sección

Un fallo de proveedor aflora como un error estructurado y sin secretos que solo afecta a su propio sublote. Un PROVIDER_ERROR nombra solo el host y el puerto de un baseUrl de openai-compatible o LibreTranslate, y en Google solo translation.googleapis.com, nunca la consulta que lleva su clave.

Límites de tokens de salidaCopiar enlace a esta sección

Los proveedores LLM limitan los tokens de cada respuesta; un modelo que se detiene en el tope levanta OUTPUT_TRUNCATED. verbatra vuelve a dividir un sublote truncado en mitades, bajando hacia una sola entrada, y retiene solo una entrada que sigue desbordándose. Para resolverlo del todo, baja maxBatchSize o sube maxTokens (Anthropic) o maxOutputTokens. Un modelo de razonamiento gasta tokens de razonamiento ocultos del mismo presupuesto, así que dale margen de sobra.

Señales de revisiónCopiar enlace a esta sección

Una traducción sospechosa de cualquier proveedor se marca para revisión, no se rechaza. Consulta los motivos de revisión y Revisar en Studio.