@lingo.dev/cli envia o seu conteúdo de origem para um motor de localização, espera enquanto o motor gera as traduções e grava os resultados no disco. Substitui o fluxo antigo do npx lingo.dev — é o mesmo projeto, mas com uma arquitetura fundamentalmente diferente.
O que mudou face à CLI antiga#
A CLI antiga (npx lingo.dev run) extraía strings, chamava um LLM diretamente a partir da sua máquina e escrevia os ficheiros numa única passagem, também na sua máquina. A CLI atual divide o trabalho em push e pull:
lingo pushenvia as origens para o seu motor, inicia um workflow no servidor e tanto pode esperar pela conclusão como devolver de imediato um ID de execuçãolingo pullvai buscar os resultados do push mais recente — funciona mesmo que tenha fechado o terminal a meio da tradução ou esteja a fazer pull a partir de outra máquina- Um lockfile (
.lingo/lock.json) regista a última versão conhecida no servidor de cada destino, para que a deteção de conflitos possa assinalar edições locais antes de serem substituídas
Isto desbloqueia duas coisas que a CLI antiga não conseguia fazer: traduções demoradas sem deixar o terminal bloqueado e a possibilidade de obter resultados numa máquina diferente daquela onde correu o push (ou em CI).
Esperar pelos resultados#
Hoje, lingo push envia as origens, arranca o workflow no servidor, espera que termine e grava os resultados — tudo num só comando. Passar --wait (-w) torna esse comportamento bloqueante explícito. Também pode voltar a ligar-se 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 outputsAlteração futura: uma próxima versão vai mudar o comportamento por defeito para que lingo push submeta a execução e saia de imediato; depois, executará lingo pull para transferir 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 pullvolta a ligar-se ao push mais recente deste projeto e transfere os respetivos resultados — funciona mesmo depois de fechar o terminal. O estado de execução é guardado por máquina em~/.lingo/runs/<project-hash>.json, por issopullretoma na mesma máquina.
Autenticação: ambos os comandos leem LINGO_API_KEY (ou --api-key, ou uma sessão lingo login). Em CI, basta definir LINGO_API_KEY.
modos de push#
| Comando | Modo | Quando |
|---|---|---|
lingo push | Incremental — compara as diferenças entre a origem e .lingo/lock.json, traduz apenas chaves novas ou alteradas para destinos existentes e preserva o resto | Em todas as execuções de rotina / CI |
lingo push --backfill-missing | Bootstrap — preenche FICHEIROS de destino que ainda não existem | No primeiro push ou depois de adicionar um novo idioma |
lingo push --force | Retradução completa — substitui todos os destinos (incluindo edições manuais); --yes/-y ignora a confirmação | Raramente (por exemplo, depois de alterar o glossário ou o motor) |
--backfill-missing é uma flag de bootstrap. Faz um pedido novo com âmbito limitado e apenas adiciona ficheiros de destino completos que estejam em falta — NÃO traduz chaves adicionadas de novo em ficheiros já traduzidos (a execução indica "already up-to-date" e a chave é ignorada). Para edições contínuas, use apenas lingo push.
Editar traduções manualmente#
lingo push sem flags preserva as edições manuais por chave:
- Editar uma string de destino (mantendo a origem inalterada) → essa string é mantida; as outras chaves continuam a ser atualizadas.
- A origem por trás de uma chave editada muda → é gerada uma nova tradução para essa chave, substituindo a edição manual.
- É adicionada uma nova chave de origem → é traduzida e adicionada, mesmo em ficheiros com edições manuais.
