lingo push

Envie ficheiros de origem para o motor, aguarde pela execução e grave as saídas em disco.

lingo push [patterns...] [--force] [--backfill-missing] [--yes]

Comportamento predefinido — envio delta#

Sem argumentos, lingo push executa o modo só delta:

1. Gerar o hash de cada ficheiro de origem correspondente aos padrões files da configuração
2. Comparar cada hash com o ficheiro de bloqueio para identificar as origens que foram alteradas
3. Carregar as origens alteradas como uma execução no motor
4. Aguardar que a execução termine
5. Gravar as saídas em disco
6. Registar os novos hashes das origens no ficheiro de bloqueio

Se nenhuma origem tiver mudado desde o último envio bem-sucedido, o comando termina de imediato com ✓ Nothing to push. — sem ida e volta ao servidor, sem consumo de tokens.

Argumentos e flags#

Posicional: patterns... — envio com âmbito#

lingo push docs/en/about.md
lingo push 'docs/en/**/*.md' 'locales/en.json'

Restringe o envio a ficheiros específicos (têm de corresponder a padrões já presentes em .lingo/config.json). Coloca o comando em modo com âmbito:

• Sem diff face às origens anteriores — cada origem correspondente é tratada como estando dentro do âmbito, mesmo que não tenha sido alterada.
• Noop do lado do servidor para destinos que já existam com hashes de origem correspondentes — o motor ignora-os e a CLI assinala-os como em cache.

Utilize quando quiser traduzir exatamente um ficheiro atualizado sem voltar a calcular os hashes do projeto inteiro, ou quando quiser retraduzir uma única página com --force.

--force / -f#

lingo push docs/en/about.md --force

Retraduz todos os destinos correspondentes, ignorando quaisquer traduções existentes e contornando a cache do lado do servidor. Requer um âmbito — padrões posicionais ou --backfill-missing. lingo push --force isolado é rejeitado porque retraduziria o projeto inteiro.

Por predefinição, --force pede confirmação antes de executar:

! --force will retranslate every target for pattern(s): docs/en/about.md and
  overwrite existing translations. Continue? (Yes, retranslate / Cancel)

Passe --yes / -y para ignorar a confirmação (adequado para CI).

--backfill-missing#

lingo push --backfill-missing

Traduz todos os destinos que ainda não existem em todos os padrões configurados. Equivale a um envio com âmbito sobre todos os padrões da configuração, mas produz apenas os ficheiros em falta. Utilize depois de adicionar um novo idioma a targetLocales, ou no primeiro envio de um novo projeto.

Combine com --force para retraduzir tudo de raiz:

lingo push --backfill-missing --force --yes

--yes / -y#

Ignora o pedido de confirmação de --force. Não tem efeito sem --force.

Saída#

Em caso de sucesso:

Pushing source files to localization engine…
✓ Run run_a8c...: localized 12 target file(s), 4 already up-to-date, uploaded 1 new artifact(s).

O resumo divide-se em:

• N ficheiro(s) de destino localizado(s) — o motor produziu novas traduções e a CLI gravou-as.
• N já atualizados — acertos de cache do lado do servidor (origem correspondente, destino reutilizado).
• N novo(s) artefacto(s) carregado(s) — origens que o motor ainda não tinha visto (conteúdo binário/de grande dimensão armazenado uma vez e depois referenciado).
• N destino(s) ignorado(s) (edições locais) — os hashes dos destinos locais divergem do ficheiro de bloqueio. Execute novamente com --force para substituir.

Em caso de falha por destino, a CLI apresenta o erro de cada destino com falha e termina com um código diferente de zero — útil para CI:

✓ Run run_a8c...: localized 10 target file(s).
  2 target(s) failed:
    locales/de.json: rate limit on engine; retry later
    locales/fr.json: timeout

Semântica de repetição#

O ficheiro de bloqueio é atualizado apenas após uma execução totalmente bem-sucedida. Uma falha parcial (por exemplo, um idioma expira) deixa os hashes das origens inalterados no ficheiro de bloqueio, pelo que o próximo lingo push repete o mesmo diff — sem reposição manual.

Se o motor der erro antes de qualquer tradução acontecer (autenticação, validação), nada é gravado e o ficheiro de bloqueio permanece inalterado.

Padrões comuns#

CI: traduzir no merge#

- run: lingo push --backfill-missing --yes
- run: git add . && git commit -m "chore: refresh translations" && git push

--backfill-missing é a opção segura por predefinição: não substitui nada, apenas preenche lacunas.

Iteração num único ficheiro#

lingo push docs/en/onboarding.md -f -y

Retraduzir apenas uma origem após uma grande alteração de texto. Ignore a confirmação para uma iteração rápida.

Adicionar um novo idioma#

Depois de atualizar targetLocales em .lingo/config.json:

lingo push --backfill-missing

Traduz o corpus completo para o novo idioma sem retraduzir os já existentes.