Automatize traduções na CI

Torne a tradução uma etapa reproduzível do lançamento, de uma revisão conhecida do código-fonte a arquivos inspecionados e verificações da aplicação.

Um pipeline de lançamento já conecta uma revisão do código-fonte a algo que as pessoas podem usar. A tradução deve manter essa conexão. A tarefa precisa identificar o conteúdo de origem que mudou, obter os arquivos de destino correspondentes e fornecer à próxima etapa evidências suficientes para aceitá-los ou rejeitá-los.

Os casos mais complicados surgem depois da primeira solicitação bem-sucedida: um revisor ainda está editando, um executor fica indisponível ou uma nova revisão do texto-fonte chega antes que uma tradução anterior seja concluída. Este guia apresenta um processo de CI capaz de lidar com essas situações sem publicar arquivos desatualizados nem substituir desnecessariamente edições já aceitas. O YAML específico de cada provedor está nas receitas de GitHub Actions, GitLab, Bitbucket e Buildkite.

Decida em que etapa do lançamento as traduções entram #

Use o GitHub App gerenciado quando o workflow dele for adequado ao seu repositório. Alterações na branch padrão geram um pull request de tradução; o processamento opcional de pull requests grava as alterações na branch do próprio pull request. A aprovação da execução autoriza o trabalho de tradução; a revisão do conteúdo e a mesclagem acontecem depois.

Com um executor da CLI, seu pipeline assume a responsabilidade pelo envio, pela obtenção dos resultados e pela entrega. Escolha um destino compatível com o processo de lançamento:

DestinoDecisão que permite tomar
Apenas artefatoOutra tarefa ou uma pessoa inspeciona o resultado antes de qualquer alteração no repositório ou no lançamento.
Branch de tradução e pull requestRevise as alterações traduzidas separadamente antes de incorporá-las à branch padrão.
Branch do pull request de origemRevise o conteúdo de origem e as traduções juntos, em uma única alteração.
Commit direto na branch padrãoFaça a entrega sem um pull request de tradução separado quando a política da branch permitir isso explicitamente.

Para gravar no repositório, defina um único responsável ativo pela gravação de cada estado da tradução. Caso contrário, dois executores trabalhando com revisões diferentes do conteúdo de origem podem disputar os commits dos arquivos e do Lockfile. Os commits gerados também precisam de regras por branch, caminho ou identificação de commit gerado para não acionarem a tradução repetidamente.

Estabeleça a base que o executor vai herdar #

Antes de ativar as execuções recorrentes, traduza localmente um arquivo de origem para um idioma e execute as verificações de recursos da aplicação. Inclua a configuração, o arquivo de destino aceito e o .lingo/lock.json no mesmo commit. Um checkout limpo deve reproduzir a mesma seleção de arquivos de origem e a mesma estrutura de arquivos de destino.

Os exemplos dos provedores fixam a versão em @lingo.dev/cli@1.21.0. Ao configurar seu workflow, substitua essa versão pela versão atual da CLI. Para gerenciar a CLI junto com as dependências do projeto, instale-a com npm install --save-dev --save-exact @lingo.dev/cli@1.21.0 e inclua package.json e package-lock.json no commit. Depois, use npm ci e npx --no-install lingo para executar a versão registrada no Lockfile.

.lingo/config.json seleciona os idiomas, os padrões de arquivo e o engine de localização. Defina o acesso à organização e ao engine de localização durante a configuração inicial. Se a tarefa precisar inicializar ou vincular um projeto, use as opções explícitas nas referências de Inicializar e Vincular, em vez de aguardar uma resposta interativa em uma execução sem supervisão.

Em um monorepositório, acesse o diretório do pacote que contém a configuração desejada antes de executar a CLI. Os padrões posicionais restringem os arquivos de origem selecionados por essa configuração; eles não selecionam a configuração de outro pacote. Mantenha juntos o estado e os caminhos dos artefatos de cada pacote configurado de forma independente.

Injete LINGO_API_KEY pelo mecanismo de segredos do executor. Ele funciona sem login interativo. Execute tarefas com credenciais apenas a partir de código confiável, pois uma branch pode alterar scripts para expor a chave. As restrições de variáveis protegidas e de forks devem determinar onde a tarefa será executada, e não ser removidas para fazer uma tarefa não confiável funcionar.

Envie o tipo certo de trabalho #

Para uma primeira tradução do zero, solicite os arquivos de destino ausentes. Em um projeto existente, primeiro conclua as atualizações normais do conteúdo de origem para os destinos existentes, obtenha os resultados e inspecione-os. Depois, adicione os idiomas ausentes e preencha os arquivos que faltam, mantendo fixa a revisão do conteúdo de origem. Siga Adicionar um idioma antes de executar este comando:

sh
lingo push --backfill-missing --wait

Para alterações no conteúdo de origem em relação à base estabelecida:

sh
lingo push --wait

Um envio inicial simples pode registrar o estado do conteúdo de origem sem traduzi-lo. O preenchimento de arquivos ausentes cria a tarefa para gerar esses arquivos; os envios normais seguintes usam as alterações no conteúdo de origem para determinar o trabalho. Um envio com escopo limitado ou para preencher arquivos ausentes não é uma solução universal para corrigir chaves ausentes em arquivos de destino existentes.

--wait aguarda a execução e baixa os resultados concluídos. Sem essa opção, o comando de envio retorna assim que a solicitação é enviada. Uma espera por revisão ou uma tarefa separada para obter os resultados exige o procedimento de preservação do estado de execução na CI: antes de o executor encerrar, preserve o ponteiro específico sem dados secretos armazenado no diretório pessoal, o caminho absoluto original da raiz do projeto e o estado correspondente do conteúdo de origem, da configuração, dos arquivos de destino e do Lockfile. Restaure tudo nessa mesma raiz e autentique-se separadamente antes de usar lingo pull --dry-run e, depois, lingo pull. Se o executor não conseguir recriar o caminho, use um checkout persistente e autorizado. Nunca arquive credenciais nem todo o conteúdo de ~/.lingo.

Preserve o código de saída e os resultados informados para cada destino. A CLI atual retorna falha quando há destinos com falha reportada, mas a revisão humana pode deixar uma execução aguardando decisões. Um arquivo antigo pode continuar existindo enquanto a nova versão aguarda revisão. Conclua a revisão e obtenha o resultado antes de permitir que a tarefa de entrega o publique.

Consulte Push e Pull para conhecer o comportamento exato dos comandos. --yes pula a confirmação de regeneração forçada; não aprova a revisão humana nem transforma todas as ações pendentes em trabalho concluído.

A CLI não verifica atualizações na CI. LINGO_DISABLE_UPDATE_CHECK=1 e LINGO_TELEMETRY_DISABLED=1 oferecem controles explícitos quando necessário, sem desativar o tráfego de tradução.

Garanta que a próxima etapa tenha arquivos utilizáveis #

Confira a entrada que deveria ter mudado em relação à revisão do conteúdo de origem. A simples existência do arquivo é uma evidência fraca quando o checkout já contém um arquivo de destino antigo. Preserve os resultados baixados e o estado do Lockfile da mesma operação, deixando claramente incompletos os idiomas com falha ou ainda em espera.

Depois, execute verificações adequadas ao tipo de recurso:

  • Para extração em React, execute lingo extract --check, lingo check, a verificação de TypeScript do projeto e a compilação efetiva da aplicação. Essas verificações examinam partes diferentes do resultado.
  • Para recursos nativos, execute a geração ou compilação de recursos da plataforma.
  • Para conteúdo estático, analise os documentos traduzidos e inspecione os links, as variáveis e a sintaxe preservada.
  • Para fazer uma solicitação de mesclagem falhar quando as traduções estiverem desatualizadas, execute lingo check. Não é necessária uma chave de API.

lingo check opera no nível de arquivo: informa alterações no conteúdo de origem e a ausência de arquivos de destino para cada idioma configurado, não a ausência de uma chave dentro de um arquivo Android, Apple, ARB ou Markdoc existente.

Confira o significado da tradução como parte do processo de aceitação escolhido. Uma compilação pode detectar um recurso malformado e, ainda assim, aceitar uma frase que altera uma condição importante. Quando as verificações e a revisão forem concluídas com sucesso, faça o commit ou publique apenas os caminhos de saída previstos. Permita que a tarefa termine sem alterações e deixe as verificações obrigatórias causarem sua falha, em vez de mascará-las com um commit incondicional.

Retome o trabalho registrado antes de iniciar outro para substituí-lo #

Após a interrupção de uma tarefa, recupere a identificação da execução e os resultados dos destinos. Se a tradução tiver sido concluída, baixe o resultado antes de enviar outra solicitação. Se um arquivo de destino local tiver mudado durante a espera, resolva o conflito ao baixar o resultado mantendo a edição aceita visível; sobrescrevê-lo à força pode descartar justamente a correção que o workflow deveria preservar.

Mantenha o Lockfile durante o diagnóstico. Excluí-lo muda a base do conteúdo de origem para a próxima execução e pode transformar uma recuperação pontual em um trabalho diferente. Inspecione as diferenças e tente novamente apenas o escopo que continua incompleto. Recuperar uma execução de localização interrompida detalha essa decisão.

Antes de agendar a tarefa, simule uma espera por revisão humana e uma interrupção na obtenção dos resultados, além do caso bem-sucedido. A etapa de lançamento deve preservar o último estado aceito e identificar o idioma incompleto, em vez de aceitar qualquer arquivo que por acaso exista.