Receita para Buildkite
Traduza arquivos em um pipeline do Buildkite, envie o resultado de volta à branch e reprove pull requests com traduções desatualizadas.
Uma etapa do Buildkite pode traduzir arquivos do repositório com a CLI do Lingo.dev nos seus próprios agentes. A CLI envia os arquivos de origem selecionados pela configuração do Lingo.dev e grava os arquivos traduzidos no checkout; seu pipeline define como entregá-los. O Buildkite gerencia os agentes, os segredos e o acesso ao repositório; o Lingo.dev processa os arquivos por meio de um engine de localização.
Esta é uma receita de CI, não uma conexão nativa com o Buildkite. Comece com uma etapa de tradução na branch padrão ou nas execuções de pull requests e confira o primeiro commit gerado. Adicione a verificação de pull requests apenas nos cenários em que a tabela indicar que esse bloqueio é adequado.
Prepare o repositório e o agente #
Conclua o guia de início rápido da CLI localmente. Faça commit de .lingo/config.json, dos arquivos de destino aceitos e de .lingo/lock.json. A configuração define o idioma de origem, os idiomas de destino, os padrões de arquivos e o engine de localização. Os exemplos usam locales/en.json como origem e um arquivo de destino em espanhol já existente em locales/es.json. Se houver mais destinos, execute test -s e as verificações de JSON uma vez para cada arquivo de destino e liste todos os caminhos de destino nos demais comandos que mencionam locales/es.json, ou adicione todo o diretório de destino à área de preparação, como locales/. O Lockfile registra a origem como traduzida, então um envio posterior a ignora, e qualquer destino que ficar fora do commit permanece desatualizado.
Crie os arquivos de destino ausentes com lingo push --backfill-missing --wait antes de adotar a etapa recorrente. Nas próximas edições da origem, use lingo push --wait normalmente. O preenchimento de arquivos ausentes não corrige chaves ausentes em um destino existente.
O agente precisa de Node.js, npm e Git, além de acesso de rede ao registro do npm e ao Lingo.dev. A credencial do repositório usada pelo agente no checkout, como uma chave de implantação, também deve permitir envios para a branch em que a etapa grava.
Armazene a chave de API do Lingo.dev como um segredo do Buildkite chamado LINGO_API_KEY. A CLI lê apenas esse nome; uma variável LINGODOTDEV_API_KEY da CLI anterior é ignorada, então renomeie-a. Carregue o segredo somente na etapa de tradução. A chave secrets: da etapa exige o agente do Buildkite na versão 3.106.0 ou posterior, em execução no cluster que armazena o segredo; versões anteriores do agente fazem o pipeline falhar. Em agentes mais antigos ou que não fazem parte de um cluster, remova secrets: e exporte LINGO_API_KEY para essa etapa por meio de um hook environment do agente ou do seu plugin de segredos.
Mantenha Permitir execuções de repositórios de terceiros criados por fork desativado nas Configurações do GitHub do pipeline. A execução de um pull request de um fork usa o próprio pipeline.yml do fork, que pode adicionar uma etapa para ler o segredo, e nenhum if: no seu arquivo pode impedir isso. Adicione também uma política de acesso ao segredo para que apenas as execuções deste pipeline possam lê-lo.
Os exemplos usam a versão fixa 1.21.0 da CLI. lingo check verifica arquivos de tradução a partir da versão 1.20.0 da CLI. Para gerenciar a versão pelas dependências e pelo Lockfile do seu projeto, siga o guia de configuração de CI.
Traduza e envie de volta à branch #
Esta etapa traduz cada alteração que chega à branch padrão e envia o resultado para a mesma branch. Ela pressupõe que o preenchimento inicial já foi incluído em um commit e que a Revisão humana do engine está desativada, para que a tradução termine em uma única etapa. Adicione-a a .buildkite/pipeline.yml:
steps:
- label: "Translate"
if: build.branch == pipeline.default_branch && build.pull_request.id == null
concurrency: 1
concurrency_group: "lingo-translations"
# secrets: needs Buildkite agent 3.106.0 or later.
secrets:
- LINGO_API_KEY
command: |
# Replace 1.21.0 with the current CLI version.
npx -y @lingo.dev/cli@1.21.0 push --wait
test -s locales/es.json
node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
git add -- locales/es.json .lingo/lock.json
if git diff --cached --quiet; then exit 0; fi
git config user.name "Localization bot"
git config user.email "localization@example.com"
git commit -m "[skip ci] Update translations"
git push origin "HEAD:refs/heads/$${BUILDKITE_BRANCH}"--wait faz a etapa aguardar a conclusão da execução e gravar os arquivos traduzidos no checkout. Sem isso, lingo push apenas envia a execução e encerra, e a etapa não encontra nada para incluir em um commit. lingo push --wait encerra com código diferente de zero quando um destino falha, interrompendo a etapa antes do commit. Quando nada mudou, ela exibe "Nada para enviar", não há diferenças na área de preparação e a etapa encerra sem fazer commit.
O Buildkite faz checkout de um único commit, não de uma branch, por isso o comando de envio especifica o nome da branch. $$ mantém BUILDKITE_BRANCH para que o shell faça a expansão quando a etapa for executada; com um único $, o Buildkite gravaria o nome da branch no texto do comando ao carregar o pipeline. concurrency e concurrency_group permitem executar uma tradução por vez. Se a branch tiver avançado durante a tradução, o Git rejeita o envio; a execução do commit mais recente faz a tradução.
A etapa não entra em loop. O Buildkite ignora execuções de commits cuja mensagem contém [skip ci]. Sem isso, a próxima execução não encontraria nada para enviar, porque o .lingo/lock.json incluído no commit já registra a nova origem.
Enviar diretamente para a branch padrão elimina a revisão por pull request das traduções, então adote essa opção de forma deliberada na política de branches. Para revisar as traduções primeiro, envie o resultado para uma branch separada, como lingo/translations, e abra um pull request com as ferramentas do seu provedor Git.
Traduza nas execuções de pull requests #
Para traduzir as alterações de origem de cada pull request na própria branch dele, use esta etapa no lugar da etapa da branch padrão. As premissas são as mesmas. Seu if: ignora pull requests de forks, porque a etapa não pode enviar para a branch de um fork.
A etapa exige duas opções nas Configurações do GitHub do pipeline. Ative Executar quando um pull request for aberto ou atualizado. Desative Executar branches ou limite essa opção à branch padrão. Com as execuções de branches ativadas, um envio para uma branch de pull request pode iniciar uma execução sem os detalhes do pull request. A etapa ignora essa execução, então nada é traduzido e nada falha.
O if: não protege LINGO_API_KEY. O Buildkite o lê do próprio pipeline.yml do pull request, e um fork pode alterar esse arquivo. Por isso, as execuções de forks devem permanecer desativadas, como orienta a configuração. Um pull request de uma branch do repositório também pode alterar o arquivo, então qualquer pessoa que possa enviar para uma branch pode ler a chave por meio desta etapa. Use a etapa apenas em ambientes em que todas as pessoas com acesso de envio possam ter a chave.
steps:
- label: "Translate pull request"
if: build.pull_request.id != null && build.pull_request.repository.fork != true
# secrets: needs Buildkite agent 3.106.0 or later.
secrets:
- LINGO_API_KEY
command: |
# Replace 1.21.0 with the current CLI version.
npx -y @lingo.dev/cli@1.21.0 push --wait
test -s locales/es.json
node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
git add -- locales/es.json .lingo/lock.json
if git diff --cached --quiet; then exit 0; fi
git config user.name "Localization bot"
git config user.email "localization@example.com"
git commit -m "Update translations"
git push origin "HEAD:refs/heads/$${BUILDKITE_BRANCH}"A mensagem de commit não contém [skip ci], de propósito. O Buildkite executa o commit da tradução, a etapa roda novamente, não encontra nada para enviar e encerra sem fazer commit. Assim, o loop termina após uma execução extra. Essa execução atribui um estado ao commit mais recente do pull request. Com [skip ci], o commit mais recente não teria uma execução do Buildkite, e uma verificação de estado obrigatória do Buildkite bloquearia o merge.
A credencial de checkout do agente deve permitir envios para branches de pull requests. Se a branch tiver avançado durante a tradução, o Git rejeita o envio e a etapa falha; a execução do commit mais recente faz a tradução. Assim, dois envios em sequência rápida iniciam duas traduções, e ambas são cobradas. Ative Cancelar execuções intermediárias nas configurações do pipeline para que um envio mais recente cancele a execução anterior. Uma tradução já enviada pela execução anterior não é cancelada.
Reprove pull requests com traduções desatualizadas #
lingo check compara cada origem configurada com .lingo/lock.json e exige que todos os arquivos de destino existam. Ele encerra com código 1 quando uma origem mudou desde a última tradução, uma origem não tem entrada no Lockfile, um arquivo de destino está ausente ou nenhum arquivo de origem corresponde aos padrões de files. Não precisa de chave de API nem de segredo e não grava nada. Além da telemetria da CLI, que DO_NOT_TRACK=1 desativa, ele não faz chamadas de rede; o exemplo com npx ainda baixa a CLI do npm antes de executar a verificação. Ele substitui o bloqueio --frozen da CLI anterior.
Ele verifica arquivos, não chaves: um destino editado manualmente passa, e uma chave ausente em um destino existente não é sinalizada, exceto em catálogos .jsonc do React. Sem .lingo/lock.json, ele não consegue detectar alterações na origem, então uma origem alterada ou nunca enviada não faz a verificação falhar, e isso é informado em stderr. Faça commit do Lockfile gravado por lingo push.
Adicione esta etapa a .buildkite/pipeline.yml quando a tabela abaixo indicar que o bloqueio é adequado. Ela se destina a uma configuração sem nenhuma das duas etapas de tradução acima. Por isso, cada exemplo aqui é uma lista steps: completa para uma configuração; incorpore a etapa à sua lista steps: existente em vez de adicionar uma segunda chave steps::
steps:
- label: "Check translations"
if: build.pull_request.id != null
command:
# lingo check needs CLI 1.20.0 or newer.
- npx -y @lingo.dev/cli@1.21.0 checkO bloqueio é adequado quando as traduções são incluídas no commit junto com a alteração de origem:
| Onde a tradução é executada | Bloqueio em todos os pull requests |
|---|---|
Os desenvolvedores executam lingo push --wait e fazem commit do resultado antes de abrir o pull request | Sim. Ele reprova um pull request cuja origem mudou sem ser traduzida. |
| A etapa de tradução envia para a branch padrão após o merge | Não. Nesse fluxo, os pull requests de funcionalidades alteram as origens antes da tradução. |
| A etapa de pull request faz commit na branch do pull request | Não. Na execução que traduz, a verificação analisa o commit anterior à tradução e falha. A própria reexecução da etapa no commit da tradução, que não encontra nada para enviar, mostra que nenhuma origem mudou desde .lingo/lock.json. |
Os hashes de origem são exatos, byte a byte. Garanta que o checkout em que lingo push foi executado e o checkout de CI usem as mesmas terminações de linha, por exemplo, com * text=auto eol=lf em .gitattributes.
Adapte a etapa #
Em um monorepo, execute a CLI a partir do pacote que contém .lingo/config.json, por exemplo, com cd apps/web no início do comando, e adicione os arquivos de destino e o Lockfile desse pacote à área de preparação. Pacotes independentes mantêm arquivos Lockfile separados e podem usar engines de localização diferentes.
Se o engine de localização enviar trabalho para revisão humana, lingo push --wait encerra com código 0 após gravar apenas os arquivos concluídos. Não faça commit desse resultado parcial como se estivesse completo. Adicione o procedimento de preservação do estado da execução em CI e obtenha o restante com Obter no mesmo agente quando a revisão terminar.
Recupere e desative a etapa #
Use o erro para identificar a próxima ação: corrigir a instalação de pacotes, fornecer o segredo, concluir a revisão, resolver um conflito ao obter alterações ou tentar novamente a tradução dos destinos que falharam após corrigir a causa. Mantenha visíveis os encerramentos com código diferente de zero; || true oculta a causa.
Remova a etapa ou seu gatilho para impedir novas execuções. Ao cancelar uma execução, confira separadamente qualquer tradução já enviada. Remova o segredo LINGO_API_KEY e o acesso de gravação do agente ao desativar a receita.