Receita para o Buildkite

Traduza ficheiros num pipeline do Buildkite, envie o resultado para o ramo de origem e faça falhar os pedidos de integração com traduções desatualizadas.

Um passo do Buildkite pode traduzir ficheiros do repositório com a CLI do Lingo.dev nos seus próprios agentes. A CLI submete os ficheiros de origem selecionados pela configuração do Lingo.dev e escreve os ficheiros traduzidos no checkout; o pipeline determina como os entregar. O Buildkite gere os agentes, os segredos e o acesso ao repositório; o Lingo.dev processa os ficheiros através de um motor de localização.

Esta é uma receita de CI, não uma ligação nativa ao Buildkite. Comece com um passo de tradução no ramo predefinido ou nas compilações de pedidos de integração e verifique o primeiro commit que criar. Adicione a verificação dos pedidos de integração apenas nos casos em que a tabela indicar que essa validação é adequada.

Preparar o repositório e o agente #

Conclua o guia de início rápido da CLI localmente. Inclua num commit .lingo/config.json, os ficheiros de destino aceites e .lingo/lock.json. A configuração define o idioma de origem, os idiomas de destino, os padrões de ficheiros e o motor de localização. Os exemplos usam locales/en.json como origem e um ficheiro de destino em espanhol já existente em locales/es.json. Se tiver mais destinos, execute test -s e as verificações de JSON uma vez por ficheiro de destino e indique todos os caminhos de destino nos restantes comandos que mencionam locales/es.json, ou prepare todo o diretório de destino para commit, como locales/. O Lockfile regista a origem como traduzida, pelo que um envio posterior a ignora e qualquer destino que fique de fora do commit permanece desatualizado.

Crie os ficheiros de destino em falta com lingo push --backfill-missing --wait antes de adotar o passo recorrente. Use o comando habitual lingo push --wait para alterações posteriores à origem. O preenchimento de ficheiros em falta não repõe chaves em falta num destino existente.

O agente precisa de Node.js, npm e Git, bem como de acesso de rede ao registo npm e ao Lingo.dev. A credencial do repositório que o agente usa para o checkout, como uma chave de implementação, também tem de permitir envios para o ramo em que o passo escreve.

Guarde a chave de API do Lingo.dev como um segredo do Buildkite com o nome LINGO_API_KEY. A CLI lê apenas este nome; uma variável LINGODOTDEV_API_KEY da CLI anterior é ignorada, por isso altere-lhe o nome. Carregue o segredo apenas no passo de tradução. A chave secrets: do passo requer o agente Buildkite 3.106.0 ou posterior, em execução no cluster que contém o segredo; os agentes de versões anteriores fazem falhar o pipeline. Em agentes mais antigos ou que não pertençam a um cluster, remova secrets: e, em alternativa, exporte LINGO_API_KEY para esse passo através de um ponto de execução environment do agente ou do seu plugin de segredos.

Mantenha a opção Permitir compilações a partir de bifurcações de repositórios de terceiros desativada nas definições do GitHub do pipeline. A compilação de um pedido de integração de uma bifurcação usa o pipeline.yml da própria bifurcação, que pode adicionar um passo para ler o segredo, e nenhum if: no seu ficheiro o pode impedir. Adicione também uma política de acesso ao segredo, para que apenas as compilações deste pipeline o possam ler.

Os exemplos fixam a versão da CLI em 1.21.0. O comando lingo check verifica ficheiros de tradução a partir da versão 1.20.0 da CLI. Para gerir a versão através das dependências e do Lockfile do seu projeto, siga o guia de configuração de CI.

Traduzir e enviar para o ramo de origem #

Este passo traduz cada alteração que chega ao ramo predefinido e envia o resultado para o mesmo ramo. Pressupõe que o preenchimento inicial já está incluído num commit e que a opção Revisão humana do motor está desativada, para que a tradução termine num único passo. Adicione-o a .buildkite/pipeline.yml:

yaml
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 com que o passo aguarde pela conclusão da execução e escreva os ficheiros traduzidos no checkout. Sem esta opção, lingo push apenas submete a execução e termina, pelo que o passo não encontra nada para incluir num commit. lingo push --wait termina com um código diferente de zero quando um destino falha, pelo que o passo para antes do commit. Quando nada mudou, apresenta "Nada para enviar", não há diferenças nas alterações preparadas para commit e o passo termina sem criar um commit.

O Buildkite faz checkout de um único commit em vez de um ramo, pelo que o comando de envio especifica o ramo. $$ deixa BUILDKITE_BRANCH para o interpretador de comandos expandir quando o passo for executado; com um único $, o Buildkite escreveria o nome do ramo no texto do comando ao carregar o pipeline. concurrency e concurrency_group permitem executar apenas uma tradução de cada vez. Se o ramo tiver avançado durante a tradução, o Git rejeita o envio; a compilação do commit mais recente trata da respetiva tradução.

O passo não entra num ciclo. O Buildkite ignora as compilações de commits cuja mensagem contém [skip ci]. Sem isso, a compilação seguinte não encontraria nada para enviar, porque o .lingo/lock.json incluído no commit já regista a nova origem.

Enviar diretamente para o ramo predefinido dispensa a revisão de um pedido de integração de tradução, por isso esta deve ser uma escolha deliberada na política de ramos. Para rever primeiro as traduções, envie-as para um ramo separado, como lingo/translations, e abra um pedido de integração com as ferramentas do seu fornecedor Git.

Traduzir nas compilações de pedidos de integração #

Para traduzir as alterações aos ficheiros de origem de cada pedido de integração no respetivo ramo, use este passo em vez do passo do ramo predefinido. Os pressupostos são os mesmos. O seu if: ignora pedidos de integração de bifurcações, porque o passo não pode enviar alterações para o ramo de uma bifurcação.

O passo requer duas opções nas definições do GitHub do pipeline. Ative Compilar quando um pedido de integração é aberto ou atualizado. Desative Compilar ramos ou limite esta opção ao ramo predefinido. Com as compilações de ramos ativadas, um envio para o ramo de um pedido de integração pode iniciar uma compilação sem os detalhes desse pedido. O passo ignora essa compilação, pelo que nada é traduzido e nada falha.

O if: não protege LINGO_API_KEY. O Buildkite lê-o a partir do pipeline.yml do próprio pedido de integração, e uma bifurcação pode alterar esse ficheiro. Por isso, as compilações de bifurcações têm de permanecer desativadas, como indica a configuração. Um pedido de integração a partir de um ramo do repositório também pode alterar o ficheiro, pelo que qualquer pessoa que possa enviar alterações para um ramo pode ler a chave através deste passo. Use o passo apenas se todas as pessoas com acesso de envio estiverem autorizadas a ter a chave.

yaml
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], propositadamente. O Buildkite compila o commit de tradução, o passo volta a executar-se, não encontra nada para enviar e termina sem criar um commit. Assim, o ciclo termina após uma compilação adicional. Essa compilação atribui um estado ao commit mais recente do pedido de integração. Com [skip ci], o commit mais recente não teria uma compilação do Buildkite e uma verificação de estado obrigatória do Buildkite bloquearia a integração.

A credencial de checkout do agente tem de permitir envios para ramos de pedidos de integração. Se o ramo tiver avançado durante a tradução, o Git rejeita o envio e o passo falha; a compilação do commit mais recente trata da respetiva tradução. Assim, dois envios rápidos iniciam duas traduções e ambas são faturadas. Ative Cancelar compilações intermédias nas definições do pipeline, para que um envio mais recente cancele a compilação anterior. Uma tradução já submetida pela compilação anterior não é cancelada.

Fazer falhar pedidos de integração com traduções desatualizadas #

lingo check compara cada origem configurada com .lingo/lock.json e exige a presença de todos os ficheiros de destino. Termina com o código 1 quando uma origem mudou desde a última tradução, uma origem não tem entrada no Lockfile, falta um ficheiro de destino ou nenhum ficheiro de origem corresponde aos padrões files. Não precisa de chave de API nem de segredo e não escreve nada. À exceção da telemetria da CLI, que DO_NOT_TRACK=1 desativa, não faz chamadas de rede; o exemplo npx continua a transferir a CLI do npm antes de executar a verificação. Substitui a validação --frozen da CLI anterior.

Verifica ficheiros, não chaves: um destino editado manualmente passa na verificação e uma chave em falta num destino existente não é assinalada, exceto em catálogos .jsonc do React. Sem .lingo/lock.json, não consegue detetar alterações na origem, pelo que uma origem alterada ou nunca enviada não faz falhar a verificação, e essa limitação é indicada no stderr. Inclua num commit o Lockfile que lingo push escreve.

Adicione este passo a .buildkite/pipeline.yml quando a tabela abaixo indicar que a validação é adequada. Destina-se a uma configuração sem nenhum dos dois passos de tradução acima, pelo que cada exemplo aqui apresentado é uma lista steps: completa para uma configuração; integre o respetivo passo na sua lista steps: existente em vez de adicionar uma segunda chave steps::

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

A validação é adequada a uma configuração em que as traduções são incluídas no mesmo commit que a alteração da origem:

Onde é executada a traduçãoValidação em todos os pedidos de integração
A equipa de desenvolvimento executa lingo push --wait e inclui o resultado num commit antes de abrir o pedido de integraçãoSim. Faz falhar um pedido de integração cuja origem tenha mudado sem tradução.
O passo de tradução envia as alterações para o ramo predefinido após a integraçãoNão. Por definição, os pedidos de integração de funcionalidades alteram as origens antes da tradução.
O passo de pedidos de integração cria commits no ramo do pedido de integraçãoNão. Na compilação que traduz, a verificação analisa o commit anterior à tradução e falha. A nova execução do próprio passo no commit de tradução, que não encontra nada para enviar, mostra que nenhuma origem mudou desde .lingo/lock.json.

Os hashes da origem têm precisão ao byte. Garanta que o checkout em que foi executado lingo push e o checkout de CI usam os mesmos finais de linha, por exemplo com * text=auto eol=lf em .gitattributes.

Adaptar o passo #

Num monorepositório, 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 prepare os ficheiros de destino e o Lockfile desse pacote para commit. Os pacotes independentes mantêm ficheiros Lockfile separados e podem usar motores de localização diferentes.

Se o motor de localização enviar trabalho para revisão humana, lingo push --wait termina com o código 0 depois de escrever apenas os ficheiros concluídos. Não inclua esse resultado parcial num commit como se estivesse completo. Adicione o procedimento de preservação do estado de execução em CI e obtenha os restantes ficheiros com Obter no mesmo agente quando a revisão terminar.

Recuperar de falhas e desativar o passo #

Use o erro para identificar a ação seguinte: corrigir a instalação dos pacotes, fornecer o segredo, concluir a revisão, resolver um conflito ao obter alterações ou voltar a tentar a tradução do destino que falhou depois de corrigir a causa. Mantenha visíveis as terminações com código diferente de zero; || true oculta a causa.

Remova o passo ou o seu gatilho para impedir novas compilações. Ao cancelar uma compilação, verifique separadamente qualquer tradução já submetida. Remova o segredo LINGO_API_KEY e o acesso de escrita do agente quando deixar de usar esta receita.