lingo push

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

lingo push [patterns...] [--key <pattern>] [--force] [--backfill-missing] [--yes] [--wait] [--estimate]

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.

--key <pattern>#

lingo push --key auth.login
lingo push --key auth.login --key billing.plan
lingo push --key "auth.*"

Traduza novamente apenas as chaves que um padrão abrange, mescle-as à tradução existente e mantenha todas as outras chaves byte a byte idênticas. Repetível — um --key por padrão.

Um escopo de chave ignora o diff da origem, então mesmo uma chave cujo texto de origem nunca mudou ainda será traduzida novamente. Esse é justamente o objetivo da flag: é a forma compatível de refazer algumas strings após uma mudança de redação, uma troca de modelo ou uma atualização do glossário, sem pagar pelo restante do arquivo.

--force não acrescenta nada além disso e suprime o prompt de confirmação do arquivo inteiro.

O que acontece com cada chave#

A última linha é o que diferencia um escopo de chave de um push normal. Uma chave adicionada à origem desde o seu último push completo não é levada para a tradução como texto de origem — ela fica de fora, e o próximo lingo push simples faz essa tradução.

Como um padrão corresponde#

Um padrão pode corresponder exatamente a uma chave, a um prefixo que termina em um limite de ., /, - ou [, ou ainda como um glob. Membros de array podem ser alcançados pelo limite de colchetes, então nav.items abrange nav.items[0].title.

Coloque os globs entre aspas. Seu shell os expande primeiro: no zsh, um --key auth.* sem aspas aborta com no matches found ou — se houver um arquivo como auth.json no diretório — vira silenciosamente esse nome de arquivo. Um valor separado por vírgulas não é uma lista: --key "a,b" é um único padrão literal que não corresponde a nada. Em vez disso, repita a flag.

O que ele recusa#

Um escopo de chave informa e ignora, em vez de silenciosamente fazer mais do que você pediu:

• Um idioma sem tradução ainda. Não há nada para mesclar, então o idioma é informado e ignorado — traduza-o uma vez com --backfill-missing e depois use --key.
• Formatos em que nenhuma chave pode ficar de fora — formatos de documento, cujas chaves mudam assim que o documento é editado, e xcode-stringsdict, cujas categorias de plural precisam estar no arquivo para que ele continue válido. Formats traz a lista completa. Esses arquivos são ignorados com um aviso, então um push ainda pode misturá-los com arquivos de chave-valor; envie-os sem --key.
• Um escopo que não correspondeu a nada informa isso, em vez de relatar a execução como já atualizada.

Membros posicionais mantêm seu texto de origem mesmo com escopo — elementos de array, itens <string-array> do Android, quantidades <plurals> — porque remover um deles renumeraria os demais.

Ele não avança o lockfile#

Uma execução com escopo de chave traduz apenas parte de um arquivo, então deixa de propósito o hash da origem no lockfile como está. Qualquer outra mudança nesse arquivo continua pendente, e o próximo lingo push simples a captura.

--force / -f#

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

Traduza novamente todos os destinos correspondentes, ignorando traduções existentes e contornando o cache do lado do servidor. Defina um escopo para isso — com padrões posicionais ou --backfill-missing — a menos que você realmente queira o projeto inteiro: lingo push --force sozinho traduz novamente todos os padrões configurados, e a confirmação abaixo é a única barreira no caminho.

Em um projeto que nunca foi traduzido, não há nada para sobrescrever, então --force não oferece nenhuma vantagem nesse caso — use --backfill-missing no lugar. No geral, esse é o hábito mais seguro: ele só preenche lacunas e nunca exibe prompts.

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).

Para refazer só algumas strings, em vez de arquivos inteiros, use --key — você paga apenas pelas chaves que nomear.

--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 o prompt de confirmação de --force. Não tem efeito sem --force e também não tem efeito ao lado de --key — um escopo de chave nunca exibe prompt, porque só toca nas chaves que você nomeou.

--estimate#

lingo push --estimate
lingo push 'docs/en/**/*.md' --estimate

Exibe o custo aproximado deste push e encerra sem traduzir. A CLI executa todo o pipeline do push — hashing, delta e upload dos bytes de origem para que o servidor possa calcular o delta exato — e então pede ao engine que precifique a execução, em vez de iniciá-la. Nada é traduzido, gravado nem cobrado; o lockfile e seus arquivos de destino permanecem intocados.

Os valores são estimativas, não cotações. --estimate combina com escopo e com --key / --force / --backfill-missing, para que você possa calcular exatamente o push que está prestes a executar.

Se nenhuma origem tiver mudado, --estimate é encerrado antecipadamente com ✓ Nothing to push., assim como em um push normal.

Se uma execução com as mesmas origens já estiver em andamento, --estimate falha em vez de precificar uma execução iniciada pela metade:

Error: Cannot estimate: existing group run_a8c... is already in 'running' state. Change a source file or wait for the run to finish.

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

Com --estimate:

Estimating push cost…
› Estimated cost: ~$1.87 (12 target(s), ~48,000 output tokens — estimate, not a quote)
  de: ~$0.9350 (6 target(s), ~24,000 tokens)
  fr: ~$0.9350 (6 target(s), ~24,000 tokens)
  4 target(s) already up-to-date — no cost.
✓ Estimate complete — nothing was translated. Run `lingo push` to start the translation.

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.

Refaça algumas strings#

lingo push --key auth.login --key billing.plan --wait

Traduza novamente exatamente essas chaves após uma mudança de redação, deixando todas as outras chaves do arquivo intactas.

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.