@lingo.dev/cli envia seu conteúdo de origem para um engine de localização, espera enquanto o engine gera as traduções e grava os resultados de volta no disco. É a substituta do fluxo legado do npx lingo.dev — o mesmo projeto, com uma arquitetura fundamentalmente diferente.
O que mudou em relação à CLI legada#
A CLI legada (npx lingo.dev run) extraía strings, chamava um LLM diretamente da sua máquina e gravava os arquivos em uma única etapa síncrona. A nova CLI foi projetada para ser assíncrona:
lingo pushenvia os arquivos de origem para seu engine, dispara um workflow no servidor e pode aguardar a conclusão ou retornar imediatamente com um ID de execuçãolingo pullbusca os resultados do push mais recente — funciona mesmo se você fechou o terminal no meio da tradução ou estiver fazendo pull de outra máquina- Um lockfile (
.lingo/lock.json) rastreia a última versão conhecida no servidor de cada destino, para que a detecção de conflitos possa sinalizar edições locais antes que sejam sobrescritas
Isso viabiliza duas coisas que a CLI legada não conseguia fazer: traduções longas sem deixar o terminal preso e baixar os resultados em uma máquina diferente daquela que executou o push (ou no CI).
Aguardando os resultados#
Hoje, lingo push envia os arquivos de origem, inicia o workflow no servidor, espera ele terminar e grava os resultados — tudo em um único comando. Passar --wait (-w) deixa esse comportamento bloqueante explícito. Você também pode se reconectar mais tarde a uma execução concluída com lingo pull.
lingo push # submit, wait, and write outputs (current default)
lingo push --wait # same thing, made explicit
lingo pull # later: re-attach to the most recent push and download its outputsMudança em breve: uma versão futura vai tornar o modo assíncrono o padrão. lingo push enviará a execução e sairá imediatamente; você usará lingo pull para baixar as traduções concluídas, e --wait (-w) passará a ser a forma de voltar ao fluxo bloqueante em um único comando.
--wait(-w) bloqueia até o workflow terminar e grava os resultados no mesmo comando.lingo pullse reconecta ao push mais recente deste projeto e baixa seus resultados — funciona mesmo depois de você fechar o terminal. O estado de execução é salvo por máquina em~/.lingo/runs/<project-hash>.json, entãopullretoma na mesma máquina.
Autenticação: ambos os comandos leem LINGO_API_KEY (ou --api-key, ou uma sessão lingo login). No CI, defina LINGO_API_KEY e não é preciso mais nada.
Modos de push#
| Comando | Modo | Quando usar |
|---|---|---|
lingo push | Incremental — compara as diferenças da origem com .lingo/lock.json, traduz apenas chaves novas ou alteradas nos destinos existentes e preserva o restante | Em execuções de rotina / CI |
lingo push --backfill-missing | Bootstrap — preenche ARQUIVOS de destino que ainda não existem | No primeiro push ou após adicionar um novo idioma |
lingo push --force | Retradução completa — sobrescreve todos os destinos (incluindo edições manuais); --yes/-y pula o prompt | Raramente (por exemplo, após mudar o glossário ou o engine) |
--backfill-missing é uma flag de bootstrap. Ela faz uma nova solicitação com escopo definido e adiciona apenas arquivos de destino inteiros que estiverem faltando — ela NÃO traduz chaves recém-adicionadas em arquivos já traduzidos (a execução informa "already up-to-date" e a chave é ignorada). Para mudanças contínuas, use lingo push sem flags.
Editando traduções manualmente#
lingo push sem flags preserva edições manuais por chave:
- Edite uma string de destino (com a origem inalterada) → essa string é mantida; as outras chaves continuam sendo atualizadas.
- A origem por trás de uma chave editada muda → uma nova tradução é gerada para essa chave, substituindo a edição manual.
- Uma nova chave de origem é adicionada → ela é traduzida e adicionada, mesmo em arquivos com edições manuais.
