CLI

azbox-cli descarga las traducciones de tu proyecto y las escribe en ficheros, para que lo haga un paso del build en lugar de una persona. Es de código abierto (GitHub) y no tiene dependencias.

Qué hace, y qué no puede hacer

Lee. No hay push: las claves se crean en el panel o importando un fichero desde él, y la API no escribe keywords. Si escribes azbox push, el CLI te lo dice en lugar de fingir.

Eso cubre igualmente lo que importa en CI: traer las traducciones actuales, escribirlas en ficheros y commitearlas o empaquetarlas.

Instalación

npm install --save-dev azbox-cli

Node 18 o superior. O sin instalar, una sola vez, con npx azbox-cli.

Credenciales

Necesitas el ID del proyecto y una clave de API.

1. En el panel, abre Ajustes → API keys y crea una clave atada al proyecto. Solo puede leer ese proyecto, y puedes revocarla sin tocar nada más.
2. Cópiala cuando aparezca: se guarda con hash y no se puede volver a mostrar.

export AZBOX_PROJECT_ID=tu-project-id
export AZBOX_TOKEN=azb_live_…

La API key de la cuenta que aparece en Ajustes también funciona, pero abre todos los proyectos de la cuenta y no se puede revocar. Mejor una clave de proyecto.

La clave nunca se lee de azbox.json. Ese fichero se commitea, y una clave en un repositorio es una fuga: el CLI se niega a arrancar si encuentra una ahí.

Configuración

Todo puede ir en la línea de comandos, pero un proyecto suele querer un azbox.json en la raíz:

{
  "projectId": "tu-project-id",
  "languages": ["EN", "ES"],
  "out": "locales/{language}.{ext}",
  "format": "json"
}

Los flags mandan sobre las variables de entorno, y estas sobre el fichero.

Los códigos de idioma son los del proyecto (EN-US, ES, PT-PT). Desde la versión 0.1.1 da igual mayúsculas o minúsculas: -l es pide ES y escribe es.json.

Comandos

azbox pull

Descarga y escribe un fichero por idioma. Crea los directorios que hagan falta y no reescribe un fichero cuyo contenido no ha cambiado, así que se puede ejecutar en cada build.

azbox pull -l ES                                   # locales/ES.json
azbox pull -l es -f arb -o "l10n/app_{language}.{ext}"
azbox pull -l ES --since 2026-09-01                # solo lo cambiado desde entonces
azbox pull -l ES --dry-run                         # dice qué escribiría

azbox status

La misma petición, sin escribir nada. Dice cuántas claves están traducidas en cada idioma y cuántas siguen sin texto.

azbox qa

Comprueba las traducciones contra el idioma de origen y sale con 1 si hay algo roto, así que una traducción mala corta el despliegue en vez de llegar a los usuarios. Marcadores que faltan o sobran, plurales ICU rotos, HTML que no cuadra, textos que se desbordan. Ver el informe de calidad.

azbox qa                         # resumen, falla si hay errores
azbox qa --fail-on warning       # falla también con avisos de longitud y espacios
azbox qa --json > qa.json        # el informe entero, para guardarlo como artefacto

Opciones

Opción	Significado
-p, --project <id>	ID del proyecto, o AZBOX_PROJECT_ID
-t, --token <clave>	clave de API, o AZBOX_TOKEN
-l, --language <código>	idioma; repítelo para varios, o AZBOX_LANGUAGES=EN,ES
-o, --out <plantilla>	ruta de salida; se sustituyen {language} y {ext}
-f, --format <fmt>	json o arb
--flat	JSON con claves con puntos en vez de objetos anidados
--since <fecha iso>	solo keywords actualizadas después de esa fecha
--dry-run	informa, no escribe
--source <código>	qa: idioma contra el que se compara (por defecto, el primero del proyecto)
--fail-on <nivel>	qa: error (por defecto), warning o none
--json, --csv	qa: imprime el informe entero en vez del resumen

Formatos

json anida las claves con puntos, que es lo que espera i18next: home.title se convierte en { "home": { "title": … } }. Con --flat se mantienen los puntos. Si dos claves chocan —home y home.title en el mismo proyecto— anidar destruiría una de las dos, así que el CLI escribe plano y te lo dice.

arb es siempre plano, con @@locale según el idioma, porque el generador de Flutter espera las claves en el primer nivel.

En CI

- run: npx azbox-cli pull -l EN -l ES
  env:
    AZBOX_PROJECT_ID: ${{ vars.AZBOX_PROJECT_ID }}
    AZBOX_TOKEN: ${{ secrets.AZBOX_TOKEN }}

- name: Revisar las traducciones
  run: npx azbox-cli qa --fail-on error
  env:
    AZBOX_PROJECT_ID: ${{ vars.AZBOX_PROJECT_ID }}
    AZBOX_TOKEN: ${{ secrets.AZBOX_TOKEN }}

Códigos de salida: 0 bien, 1 la API falló en algún idioma —o, en qa, hay avisos del nivel de --fail-on o peores— y 2 se llamó mal.

Conviene saber

• Una clave sin traducción se omite, no se escribe como texto vacío. Escribirla vacía machacaría traducciones buenas con nada.
• Las claves salen ordenadas alfabéticamente, así que un diff solo enseña lo que ha cambiado.
• Un idioma vacío no es un error. Simplemente no se escribe el fichero.
• Los placeholders llegan tal cual se guardaron. La interpolación es cosa de tu librería de i18n.

Por debajo es una sola llamada a la API REST.