@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. É o substituto do fluxo legado npx lingo.dev — o mesmo projeto, com uma arquitetura fundamentalmente diferente.
O que mudou face à CLI legada#
A CLI legada (npx lingo.dev run) extraía strings, chamava um LLM diretamente a partir da sua máquina e gravava ficheiros numa única passagem síncrona. A nova CLI foi concebida de raiz para ser assíncrona:
lingo pushcarrega as origens para o seu motor, inicia um workflow no servidor e espera pela conclusão ou devolve imediatamente um ID de execuçãolingo pullobtém 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 capacidades que a CLI legada não tinha: traduções de longa duração sem deixar o terminal bloqueado e a possibilidade de fazer pull dos resultados noutra máquina que não aquela onde executou o push (ou em CI).
Esperar pelos resultados#
Atualmente, lingo push carrega as origens, inicia o workflow no servidor, espera que termine e grava os resultados — tudo num único comando. Passar --wait (-w) torna explícito esse comportamento bloqueante. Também pode voltar a associar-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 outputsPróxima alteração: uma versão prestes a ser lançada vai tornar o modo assíncrono o comportamento predefinido. lingo push submeterá a execução e sairá 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 associar-se ao push mais recente deste projeto e transfere os respetivos resultados — funciona mesmo depois de ter fechado 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, defina LINGO_API_KEY e não precisa de mais nada.
Modos de push#
| Comando | Modo | Quando |
|---|---|---|
lingo push | Incremental — compara as diferenças entre a origem e .lingo/lock.json, traduz apenas as chaves novas/alteradas para os destinos existentes e preserva o restante | Em 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 o prompt | Raramente (por ex., depois de uma alteração ao glossário/motor) |
--backfill-missing é uma flag de bootstrap. Faz um novo pedido com âmbito limitado e apenas adiciona ficheiros de destino completos que estejam em falta — NÃO traduz chaves recém-adicionadas em ficheiros já traduzidos (a execução indica "already up-to-date" e a chave é ignorada). Para alterações contínuas, use simplesmente lingo push.
Editar traduções manualmente#
O lingo push simples preserva as edições manuais por chave:
- Editar uma string de destino (com a origem inalterada) → essa string é mantida; as restantes 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.
