Automatisation CLI et sorties

Le CLI affiche des tableaux lisibles dans un terminal et du JSON lorsque la sortie est redirigée, ainsi la même commande fonctionne en mode interactif comme en automatisation.

aiglot batches list                    # tableau dans un terminal
aiglot batches list | jq '.data[0].id' # JSON lors d'une redirection
aiglot batches list --output ndjson    # un objet par ligne
aiglot account --json                  # JSON explicite

Les erreurs sont envoyées vers la sortie d’erreur standard (stderr), tout comme les avertissements que l’appelant doit voir, tel qu’une page de résultats tronquée. La sortie standard (stdout) peut donc être redirigée en toute sécurité vers un autre programme.

Attendre la fin d’une traduction

Un script qui lance une traduction doit généralement attendre sa fin. Interrogez batches get et arrêtez-vous sur un statut 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

Voici tous les statuts qu’une traduction peut rapporter, dont les trois qui y mettent fin. Chacun répond à la même question : qui attend, et quoi ?

Pagination

batches list et glossaries list sont basés sur des curseurs. Renvoyez le next_cursor de la réponse précédente tel quel avec --cursor, ou laissez --all s’en charger jusqu’à ce que has_more soit false (limité à 200 pages par sécurité) :

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

En mode --output ndjson, --all affiche chaque ligne de chaque page au fur et à mesure de leur arrivée. En mode table et json, il affiche un résultat combiné avec has_more: false, next_cursor: null et un compte pages_fetched à la place de request_id, puisqu’aucune requête unique ne peut être nommée une fois que plusieurs ont été exécutées.

Authentification CI

Créez une clé API dédiée avec un périmètre minimum et stockez-la dans le gestionnaire de secrets de votre fournisseur CI :

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

Le CLI vérifie les identifiants dans cet ordre : AIGLOT_API_KEY, le trousseau de clés de l’OS, puis son fichier de configuration protégé.

Codes de sortie

Les scripts doivent se baser sur le code de sortie ou le error.code structuré, et non sur le texte du message d’erreur.

Tentatives (Retries)

Les tentatives sont automatiques, mais uniquement là où elles sont sûres. L’erreur 429 est retryée pour chaque commande, en respectant Retry-After avec un backoff borné. Les erreurs 408 et 5xx sont retryées uniquement pour les requêtes idempotentes (RFC 9110 §9.2.2) : lectures, glossaries replace, glossaries delete.

glossaries create, glossaries add, glossaries remove, batches rename et batches archive ne sont pas retryées après une 5xx, car l’écriture a pu être enregistrée et une seconde tentative l’appliquerait deux fois. Ces échecs remontent à votre script avec le code de sortie 1 : relisez la ressource et décidez vous-même s’il faut réessayer plutôt que de le faire aveuglément.

Utilisez --no-retry lorsque l’appelant gère sa propre politique de tentative, et --timeout <seconds> (par défaut 60) pour limiter une requête unique. Les commandes destructives n’attendent jamais indéfiniment une invite interactive : l’utilisation non interactive doit passer l’option --force.

Profils

Utilisez des profils nommés pour séparer les identifiants de différents espaces de travail ou environnements :

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

Variables d’environnement