lingo push

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

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

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.

--key <pattern>#

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

Volte a traduzir apenas as chaves abrangidas por um padrão, junte-as à tradução existente e deixe todas as outras chaves exatamente iguais, byte por byte. Repetível — um --key por padrão.

Um âmbito de chave ignora as diferenças na origem, por isso uma chave cujo texto de origem nunca mudou continua a ser novamente traduzida. Esse é precisamente o objetivo da flag: é a forma suportada de refazer um punhado de strings após uma alteração de redação, uma mudança de modelo ou uma atualização do glossário, sem pagar pelo resto do ficheiro.

--force não acrescenta mais nada e elimina o pedido de confirmação para o ficheiro inteiro.

O que acontece a cada chave#

A última linha é o que distingue um âmbito de chave de um push normal. Uma chave adicionada à origem desde o seu último push completo não é transportada para a tradução como texto de origem — fica de fora, e o próximo lingo push simples trata de a traduzir.

Como um padrão corresponde#

Um padrão corresponde a uma chave exatamente, como prefixo terminado num limite de ., /, - ou [, ou como glob. É possível aceder aos membros de arrays através do limite de parênteses retos, por isso nav.items abrange nav.items[0].title.

Coloque os globs entre aspas. O seu shell expande-os primeiro: no zsh, um --key auth.* sem aspas ou falha com no matches found, ou — se um ficheiro como auth.json estiver por acaso na diretoria — transforma-se silenciosamente nesse nome de ficheiro. 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 recusa#

Um âmbito de chave informa e ignora, em vez de fazer discretamente mais do que pediu:

• Um idioma ainda sem tradução. Não há nada em que fazer merge, por isso o idioma é indicado e ignorado — traduza-o uma vez com --backfill-missing e depois use --key.
• Formatos que não podem ficar com chaves em falta — os formatos de documento, cujas chaves mudam assim que o documento é editado, e xcode-stringsdict, cujas categorias de plural são necessárias para que o ficheiro se mantenha válido. Em Formatos encontra a lista completa. Estes ficheiros são ignorados com um aviso, pelo que um push pode, ainda assim, misturá-los com ficheiros de chave-valor; envie-os sem --key.
• Um âmbito que não correspondeu a nada diz isso explicitamente, em vez de indicar que a execução já estava atualizada.

Os membros posicionais mantêm o respetivo texto de origem mesmo dentro de um âmbito — elementos de array, itens Android <string-array>, quantidades <plurals> — porque remover um faria renumerar os restantes.

Não faz avançar o lockfile#

Uma execução com âmbito de chave traduz apenas parte de um ficheiro, por isso deixa deliberadamente inalterado o hash de origem no lockfile. Tudo o resto que mudou nesse ficheiro continua pendente, e o próximo lingo push simples trata disso.

--force / -f#

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

Volte a traduzir todos os destinos correspondentes, ignorando quaisquer traduções existentes e contornando a cache do lado do servidor. Dê-lhe âmbito — com padrões posicionais ou --backfill-missing — a menos que queira mesmo o projeto inteiro: lingo push --force, sem mais nada, volta a traduzir todos os padrões configurados, e a confirmação abaixo é a única coisa no caminho.

Num projeto que nunca foi traduzido, não há nada para substituir, por isso --force não serve de nada nesse caso — opte antes por --backfill-missing. De um modo geral, é também a opção mais segura: limita-se a preencher lacunas e nunca pede confirmação.

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

Para refazer algumas strings em vez de ficheiros inteiros, use --key — paga apenas pelas chaves que indicar.

--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, nem em conjunto com --key — um âmbito de chave nunca pede confirmação, porque só toca nas chaves que indicou.

--estimate#

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

Mostra o custo aproximado deste push e sai sem traduzir. A CLI executa todo o pipeline de push — hashing, delta e carregamento dos bytes de origem para que o servidor possa planear o delta exato — e depois pede ao motor para calcular o preço da execução, em vez de a iniciar. Nada é traduzido, gravado ou faturado; o lockfile e os seus ficheiros de destino mantêm-se inalterados.

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

Se nenhuma origem tiver sido alterada, --estimate termina de imediato com ✓ Nothing to push., tal como num push normal.

Se já estiver em curso uma execução para as mesmas origens, --estimate falha em vez de calcular o preço de uma execução iniciada apenas a meio:

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

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

Refazer algumas strings#

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

Volte a traduzir exatamente essas chaves após uma alteração de redação, deixando todas as outras chaves do ficheiro intocadas.

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.