lingo push

Envie arquivos de origem para o engine, aguarde a execução e grave as saídas em disco.

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

Comportamento padrão — push delta#

Sem argumentos, lingo push roda no modo somente delta:

1. Gera o hash de cada arquivo de origem que corresponde aos padrões files da configuração
2. Compara cada hash com o lockfile para identificar quais origens mudaram
3. Faz upload das origens alteradas como uma execução no engine
4. Aguarda a execução terminar
5. Grava as saídas em disco
6. Registra os novos hashes de origem no lockfile

Se nenhuma origem mudou desde o último push bem-sucedido, o comando encerra antecipadamente com ✓ Nothing to push. — sem ida e volta ao servidor, sem consumo de tokens.

Argumentos e flags#

Posicional: patterns... — push com escopo#

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

Restringe o push a arquivos específicos (que já precisam corresponder a padrões definidos em .lingo/config.json). Isso coloca o comando em modo com escopo:

• Sem diff com a origem anterior — toda origem correspondente entra no escopo, mesmo que não tenha mudado.
• Noop no servidor para destinos que já existem com hashes de origem correspondentes — o engine os ignora e a CLI os reporta como em cache.

Use quando quiser traduzir exatamente um arquivo atualizado sem recalcular 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 traduções existentes e contornando o cache no servidor. Exige um escopo — seja por padrões posicionais ou por --backfill-missing. Usar lingo push --force sozinho é rejeitado porque retraduziria o projeto inteiro.

Por padrã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 pular a confirmação (compatível com 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 push com escopo sobre todos os padrões da configuração, mas gerando arquivos apenas onde ainda não existirem. Use depois de adicionar um novo idioma a targetLocales ou no primeiro push de um projeto novo.

Combine com --force para retraduzir tudo do zero:

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

--yes / -y#

Pula a 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 é dividido em:

• N arquivo(s) de destino localizado(s) — o engine gerou novas traduções e a CLI as gravou.
• N já atualizados — acertos de cache no servidor (origem correspondente, destino reutilizado).
• N novo(s) artefato(s) enviado(s) — origens que o engine ainda não tinha visto (conteúdo binário/grande armazenado uma vez e referenciado depois).
• N destino(s) ignorado(s) (edições locais) — os hashes dos destinos locais divergem do lockfile. Execute novamente com --force para sobrescrever.

Se houver falha por destino, a CLI imprime o erro de cada destino com falha e encerra com 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 retry#

O lockfile é atualizado somente após uma execução totalmente bem-sucedida. Uma falha parcial (por exemplo, timeout em um idioma) mantém os hashes de origem inalterados no lockfile, então a próxima execução de lingo push repete o mesmo diff — sem reset manual.

Se o engine falhar antes de qualquer tradução acontecer (autenticação, validação), nada é gravado e o lockfile 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 padrão mais segura: não sobrescreve nada, só preenche as lacunas.

Iteração em arquivo único#

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

Retraduza apenas uma origem após uma grande mudança no texto. Pule a confirmação para iterar mais rápido.

Adicionando um novo idioma#

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

lingo push --backfill-missing

Traduz todo o corpus para o novo idioma sem retraduzir os que já existem.