@lingo.dev/cli envia seu conteúdo-fonte para um engine de localização, aguarda enquanto o engine gera as traduções e grava os resultados de volta no disco. É o substituto 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, localmente. A CLI atual divide o processo em push e pull:
lingo pushenvia as fontes para o seu engine, inicia 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 sinalize 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 travado e o download dos resultados em uma máquina diferente daquela que executou o push (ou no CI).
Aguardando os resultados#
Hoje, lingo push envia as fontes, inicia o workflow no servidor, aguarda a conclusão e grava os resultados — tudo em um único comando. Passar --wait (-w) deixa explícito esse comportamento bloqueante. Você também pode se reconectar depois 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 futura: uma versão já em preparação vai alterar o padrão para que lingo push envie a execução e saia imediatamente; aí você usará lingo pull para baixar as traduções concluídas, e --wait (-w) passa a ser a forma de voltar ao fluxo bloqueante de comando único.
--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 os resultados — funciona mesmo depois que você fechou o terminal. O estado da execução fica por máquina em~/.lingo/runs/<project-hash>.json, entãopullretoma na mesma máquina.
Autenticação: os dois comandos leem LINGO_API_KEY (ou --api-key, ou uma sessão lingo login). No CI, basta definir LINGO_API_KEY.
Modos de push#
| Comando | Modo | Quando usar |
|---|---|---|
lingo push | Incremental — compara a fonte com .lingo/lock.json, traduz apenas chaves novas ou alteradas nos destinos existentes e preserva o restante | Em toda execução 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 uma mudança no glossário ou no 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 — NÃO traduz chaves recém-adicionadas em arquivos já traduzidos (a execução informa "already up-to-date" e a chave é ignorada). Para edições 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 fonte inalterada) → essa string é mantida; as outras chaves continuam sendo atualizadas.
- A fonte 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 fonte é adicionada → ela é traduzida e adicionada, mesmo em arquivos com edições manuais.
