@lingo.dev/cli
@lingo.dev/cli envia o seu conteúdo de origem para um motor de localização, que o traduz no servidor e grava os resultados no disco — no mesmo comando com --wait ou mais tarde com lingo pull. É a substituição do fluxo legado npx lingo.dev — o mesmo projeto, 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 pullobtém os resultados do push mais recente — funciona mesmo que tenha fechado o terminal a meio da tradução, desde que faça pull na mesma máquina, a partir do mesmo checkout- 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 permite algo que a CLI legada não conseguia fazer: traduções de longa duração sem deixar o terminal preso — faça push, feche o terminal e vá buscar os resultados mais tarde.
Esperar pelos resultados#
lingo push carrega as origens, inicia o workflow no servidor e termina assim que a execução é submetida — não espera pelas traduções nem as grava. Recolha os resultados com lingo pull ou use --wait (-w) para fazer tudo num só 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 pullvolta a ligar-se ao push mais recente deste projeto e transfere os respetivos resultados — funciona mesmo depois de ter fechado o terminal. O estado da execução é guardado por máquina em~/.lingo/runs/<project-hash>.json, associado ao caminho do projeto, por issopullretoma na mesma máquina, a partir do mesmo checkout.
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 | Todas as execuções de rotina (adicione --wait em 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.