@lingo.dev/cli
@lingo.dev/cli envia seu conteúdo de origem para um engine de localização, que faz a tradução no servidor e grava os resultados de volta no disco — no mesmo comando com --wait ou depois com lingo pull. É a substituta do fluxo legado do npx lingo.dev — mesmo projeto, 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ê fechar o terminal no meio da tradução, desde que faça pull na mesma máquina, a partir do mesmo checkout- 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 libera algo que a CLI legada não conseguia fazer: traduções longas sem deixar o terminal preso — faça push, feche o terminal e puxe os resultados depois.
Aguardando os resultados#
lingo push envia os arquivos de origem, inicia o workflow no servidor e sai assim que a execução é enviada — não espera as traduções nem grava os resultados. Recupere os resultados com lingo pull ou use --wait (-w) para fazer tudo em um único comando.
lingo push # submit the run and exit (default)
lingo pull # later: re-attach to the most recent push and download its outputs
lingo push --wait # submit, wait, and write outputs in one command--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 é salvo por máquina em~/.lingo/runs/<project-hash>.json, vinculado ao caminho do projeto, entãopullretoma na mesma máquina, a partir do mesmo checkout.
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 rotineira (adicione --wait no 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.