A CLI da Lingo.dev traduz aplicações e conteúdo ao ler um único ficheiro de configuração i18n.json, extrair strings traduzíveis dos seus ficheiros de origem e encaminhá-las através de um motor de localização ou de um fornecedor LLM sem camada adicional. Grava as traduções no disco e regista o que mudou para que a execução seguinte processe apenas o delta.
O pipeline em cinco etapas#
Quando executa npx lingo.dev@latest run, a CLI segue cinco etapas em sequência:
Descoberta de conteúdo
A CLI analisa o seu projeto à procura de ficheiros de origem e de destino com base nas configurações de bucket em i18n.json. Cada bucket define um formato de ficheiro e um conjunto de padrões de inclusão/exclusão que indica à 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 marcador de posição [locale] é resolvido, em tempo de execução, para os códigos de idioma de origem e de destino configurados.
Limpeza de dados
Nem todo o conteúdo precisa de ser traduzido. A CLI filtra os valores que devem manter-se inalterados entre idiomas — números, booleanos, datas ISO, UUIDs, URLs e strings vazias. Isto reduz a carga enviada para o backend de tradução, diminuindo o consumo de tokens e o tempo de processamento.
Cálculo do delta
A CLI calcula impressões digitais SHA-256 para cada string de origem e compara-as com o estado anterior armazenado em i18n.lock. Apenas o conteúdo novo ou alterado entra no pipeline de tradução. As strings inalteradas são totalmente ignoradas.
Esta abordagem incremental significa que, num projeto com 10 000 chaves em que apenas 12 mudaram, só essas 12 são traduzidas — e não o conjunto completo.
Localização
O delta é enviado para o backend de tradução configurado. A CLI suporta dois modos:
| Modo | Como funciona |
|---|---|
| Lingo.dev Engine | Encaminha os pedidos através do seu motor de localização, aplicando automaticamente a voz da marca, o glossário, as instruções e a configuração do modelo. |
| Raw LLM provider | Envia pedidos de tradução diretamente para OpenAI, Anthropic, Google, Mistral, OpenRouter ou Ollama com um prompt personalizado. |
A CLI repete pedidos que falham com backoff exponencial, guarda o progresso parcial e processa vários idiomas de destino em simultâneo.
Injeção de conteúdo
As strings traduzidas são gravadas no disco exatamente nas posições em que existe conteúdo de origem. A CLI preserva a estrutura e a formatação dos ficheiros para gerar diffs mínimos e fáceis de rever. Se o Prettier estiver configurado no seu projeto, o resultado respeita as suas regras de formatação.
Ficheiros de saída#
Uma execução típica produz dois tipos de alterações:
- Ficheiros de idioma — ficheiros do idioma de destino atualizados com traduções novas e alteradas
i18n.lock— atualizado com impressões digitais do conteúdo para acompanhar o estado
Ambos devem ser registados no controlo de versões — manualmente ou automaticamente através da integração CI/CD.
