La CLI de Lingo.dev traduce apps y contenido leyendo un único archivo de configuración i18n.json, extrayendo cadenas traducibles de tus archivos fuente y enviándolas a través de un motor de localización o directamente a un proveedor de LLM. Luego guarda las traducciones en disco y registra qué cambió para que la siguiente ejecución procese solo el delta.
El flujo de cinco pasos#
Cuando ejecutas npx lingo.dev@latest run, la CLI realiza cinco pasos en secuencia:
Detección de contenido
La CLI escanea tu proyecto en busca de archivos fuente y de destino según las configuraciones de bucket en i18n.json. Cada bucket define un formato de archivo y un conjunto de patrones de inclusión/exclusión que le indican a la CLI dónde está el contenido traducible.
{
"locale": {
"source": "en",
"targets": ["es", "fr", "de"]
},
"buckets": {
"json": {
"include": ["locales/[locale].json"]
},
"markdown": {
"include": ["docs/[locale]/*.md"]
}
}
}El marcador de posición [locale] se resuelve en tiempo de ejecución con los códigos de idioma de origen y destino que configuraste.
Limpieza de datos
No todo el contenido requiere traducción. La CLI filtra los valores que deben permanecer iguales entre idiomas: números, booleanos, fechas ISO, UUID, URL y cadenas vacías. Esto reduce la carga útil que se envía al backend de traducción, disminuyendo el consumo de tokens y el tiempo de procesamiento.
Cálculo del delta
La CLI calcula huellas digitales SHA-256 para cada cadena de origen y las compara con el estado anterior almacenado en i18n.lock. Solo el contenido nuevo o modificado entra al flujo de traducción. Las cadenas sin cambios se omiten por completo.
Este enfoque incremental significa que, en un proyecto con 10,000 claves donde solo cambiaron 12, se traducen únicamente esas 12 claves, no el conjunto completo.
Localización
El delta se envía al backend de traducción configurado. La CLI admite dos modos:
| Modo | Cómo funciona |
|---|---|
| Lingo.dev Engine | Canaliza las solicitudes a través de tu motor de localización y aplica automáticamente la voz de marca, el glosario, las instrucciones y la configuración del modelo. |
| Raw LLM provider | Envía solicitudes de traducción directamente a OpenAI, Anthropic, Google, Mistral, OpenRouter o Ollama con un prompt personalizado. |
La CLI reintenta las solicitudes fallidas con backoff exponencial, guarda el progreso parcial y procesa varios idiomas de destino en paralelo.
Inyección de contenido
Las cadenas traducidas se guardan en disco exactamente en las posiciones donde existe el contenido fuente. La CLI conserva la estructura y el formato de los archivos para generar diffs mínimos y fáciles de revisar. Si Prettier está configurado en tu proyecto, la salida respeta tus reglas de formato.
Archivos de salida#
Una ejecución típica produce dos tipos de cambios:
- Archivos de idioma - archivos del idioma de destino actualizados con traducciones nuevas y modificadas
i18n.lock- se actualiza con huellas digitales del contenido para dar seguimiento al estado
Ambos deben confirmarse en el control de versiones, ya sea manualmente o de forma automática mediante la integración de CI/CD.
