A CLI da Lingo.dev traduz aplicativos e conteúdos a partir de um único arquivo de configuração i18n.json, extraindo strings traduzíveis dos arquivos-fonte e encaminhando tudo por um engine de localização ou diretamente para um provedor de LLM. Ela grava as traduções de volta no disco e rastreia o que mudou para que a próxima execução processe apenas o delta.
O pipeline em cinco etapas#
Quando você executa npx lingo.dev@latest run, a CLI segue estas cinco etapas, em sequência:
Descoberta de conteúdo
A CLI analisa o projeto em busca de arquivos de origem e de destino com base nas configurações de bucket em i18n.json. Cada bucket define um formato de arquivo e um conjunto de padrões de inclusão/exclusão que informam à CLI onde está o conteúdo traduzível.
{
"locale": {
"source": "en",
"targets": ["es", "fr", "de"]
},
"buckets": {
"json": {
"include": ["locales/[locale].json"]
},
"markdown": {
"include": ["docs/[locale]/*.md"]
}
}
}O placeholder [locale] é resolvido em tempo de execução com os códigos de idioma de origem e destino configurados.
Limpeza de dados
Nem todo conteúdo precisa ser traduzido. A CLI filtra valores que devem permanecer iguais em todos os idiomas — números, booleanos, datas ISO, UUIDs, URLs e strings vazias. Isso reduz a carga enviada ao backend de tradução, diminuindo o consumo de tokens e o tempo de processamento.
Cálculo do delta
A CLI calcula fingerprints SHA-256 para cada string de origem e compara esse resultado com o estado anterior armazenado em i18n.lock. Apenas conteúdo novo ou modificado entra no pipeline de tradução. Strings inalteradas são totalmente ignoradas.
Na prática, isso significa que, em um projeto com 10.000 chaves, se apenas 12 mudarem, só essas 12 serão traduzidas — e não o conjunto inteiro.
Localização
O delta é enviado para o backend de tradução configurado. A CLI oferece suporte a dois modos:
| Modo | Como funciona |
|---|---|
| Lingo.dev Engine | Encaminha as solicitações pelo seu engine de localização, aplicando automaticamente voz da marca, glossário, instruções e configuração do modelo. |
| Provedor de LLM | Envia as solicitações de tradução diretamente para OpenAI, Anthropic, Google, Mistral, OpenRouter ou Ollama com um prompt personalizado. |
A CLI repete automaticamente solicitações que falharam com backoff exponencial, salva o progresso parcial e processa vários idiomas de destino em paralelo.
Injeção de conteúdo
As strings traduzidas são gravadas de volta no disco exatamente nas posições em que o conteúdo de origem aparece. A CLI preserva a estrutura e a formatação dos arquivos para gerar diffs mínimos e fáceis de revisar. Se o Prettier estiver configurado no seu projeto, a saída respeita suas regras de formatação.
Arquivos de saída#
Uma execução típica gera dois tipos de alteração:
- Arquivos de idioma — arquivos do idioma de destino atualizados com traduções novas e modificadas
i18n.lock— atualizado com fingerprints de conteúdo para rastrear o estado
Os dois devem ser commitados no controle de versão — manualmente ou automaticamente por meio da integração com CI/CD.
