Automatización y salida de la CLI

La CLI imprime tablas legibles en una terminal y JSON cuando la salida se redirige, por lo que el mismo comando funciona de forma interactiva y en automatizaciones.

aiglot batches list                    # tabla en una terminal
aiglot batches list | jq '.data[0].id' # JSON al redirigir
aiglot batches list --output ndjson    # un objeto por línea
aiglot account --json                  # JSON explícito

Los errores se envían a la salida de error estándar, al igual que las advertencias que el operador aún debe ver, como una página de resultados truncada. Por lo tanto, la salida estándar permanece segura para redirigirla a otro programa.

Esperar a que finalice una traducción

Un script que inicia una traducción normalmente debe esperar a que termine. Realice consultas a batches get y deténgase al alcanzar un estado terminal:

id=$(aiglot batches create catalogue.csv --instruction "Translate into French" --json | jq -r '.data.id')
aiglot batches approve "$id" --json > /dev/null

until status=$(aiglot batches get "$id" --json | jq -r '.data.status'); [ "$status" = "completed" ] || [ "$status" = "failed" ]; do
  sleep 5
done

[ "$status" = "completed" ] && aiglot batches download "$id" --output result.csv

Estos son todos los estados que puede reportar una traducción y los tres que la finalizan. Cada uno responde a la misma pregunta: ¿quién está esperando y a qué?

Paginación

batches list y glossaries list se basan en cursores. Devuelva el next_cursor de la respuesta anterior textualmente con --cursor, o deje que --all lo haga por usted hasta que has_more sea false (con un límite de 200 páginas como medida de seguridad):

aiglot batches list --status completed --all
aiglot glossaries list --all --output ndjson

En --output ndjson, --all imprime cada fila de cada página a medida que llega. En modo table y json, imprime un único resultado combinado con has_more: false, next_cursor: null y un recuento de pages_fetched en lugar de request_id, ya que ninguna solicitud individual puede nombrarse una vez que se han ejecutado varias.

Autenticación en CI

Cree una clave API dedicada con el alcance mínimo y almacénela en el gestor de secretos del proveedor de CI:

export AIGLOT_API_KEY="aig_live_…"
aiglot account --json

La CLI verifica las credenciales en este orden: AIGLOT_API_KEY, el llavero del sistema operativo y, por último, su archivo de configuración protegido.

Códigos de salida

Los scripts deben ramificarse según el código de salida o el error.code estructurado, no según el texto del mensaje de error.

Reintentos

Los reintentos son automáticos, pero solo cuando es seguro hacerlo. El error 429 se reintenta en todos los comandos, respetando Retry-After con un retroceso limitado. Los errores 408 y 5xx solo se reintentan en solicitudes idempotentes (RFC 9110 §9.2.2): lecturas, glossaries replace y glossaries delete.

glossaries create, glossaries add, glossaries remove, batches rename y batches archive no se reintentan tras un 5xx, ya que la escritura podría haberse efectuado y un segundo intento la aplicaría dos veces. Estos fallos llegan a su script con el código de salida 1: vuelva a leer el recurso y decida si debe intentar de nuevo en lugar de reintentar a ciegas.

Use --no-retry cuando el operador gestione la política de reintentos, y --timeout <seconds> (predeterminado 60) para limitar una única solicitud. Los comandos destructivos nunca esperan indefinidamente a un aviso interactivo: el uso no interactivo debe pasar --force.

Perfiles

Utilice perfiles con nombre para mantener separadas las credenciales de diferentes espacios de trabajo o entornos:

aiglot --profile client-a auth login --key "$CLIENT_A_KEY"
aiglot --profile client-a account
export AIGLOT_PROFILE=client-a

Variables de entorno