Guia prático de CI com GitHub Actions

Execute a tradução numa tarefa de confiança do GitHub Actions, inspecione os artefactos gerados e adicione a entrega por pull request quando os resultados estiverem prontos.

Execute a CLI do Lingo.dev no GitHub Actions quando a tradução precisar de usar os gatilhos e as verificações do seu pipeline atual. O executor lê a configuração do repositório, submete as alterações ao conteúdo de origem e descarrega os ficheiros traduzidos. Pode decidir se esses ficheiros ficam como artefactos ou dão origem a um pull request.

Este guia começa com o acionamento manual e o acesso só de leitura ao repositório. Depois de inspecionar uma mensagem alterada, pode adicionar as permissões de escrita necessárias para criar um pull request de tradução. Em alternativa, a GitHub App nativa oferece processamento gerido do repositório, sem precisar de configurar o executor como descrito neste guia.

Preparar o repositório #

Conclua localmente o guia de início rápido da CLI com um ficheiro de origem e um idioma de destino. Faça commit de .lingo/config.json, do ficheiro de destino inspecionado e de .lingo/lock.json. A configuração define o motor de localização, os idiomas de origem e de destino e os padrões de ficheiros. O Lockfile regista o estado de referência para alterações posteriores ao conteúdo de origem.

No exemplo abaixo, configure locales/en.json como origem e espanhol como idioma de destino, para gerar locales/es.json. O primeiro ficheiro de destino em falta é criado com lingo push --backfill-missing --wait; as alterações posteriores ao conteúdo de origem usam lingo push --wait. O preenchimento retroativo seleciona ficheiros de destino em falta, pelo que não corrige chaves em falta num ficheiro existente.

Adicione LINGO_API_KEY aos segredos do Actions do repositório ou do ambiente. Este segredo concede acesso ao Lingo.dev, independentemente das permissões do repositório GitHub. Execute a tarefa com credenciais apenas em código de confiança. Em particular, não use pull_request_target para obter e executar, com o segredo, a revisão mais recente de um pull request que não seja de confiança.

O exemplo usa uma versão fixa da CLI. Para gerir essa versão através das dependências e do Lockfile do seu projeto, siga o guia de configuração de CI.

Obter um artefacto de tradução #

Guarde este conteúdo como .github/workflows/translate.yml. O exemplo usa Node.js 22.

yaml
name: Translate catalog
on:
  workflow_dispatch:
permissions:
  contents: read
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Translate and download
        # Replace 1.21.0 with the current CLI version.
        run: npx -y @lingo.dev/cli@1.21.0 push --wait
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Inspect expected output
        run: |
          test -s locales/es.json
          node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
          git diff -- locales/es.json .lingo/lock.json
      - uses: actions/upload-artifact@v4
        with:
          name: translated-catalog
          include-hidden-files: true
          path: |
            locales/es.json
            .lingo/lock.json

Verifique os IDs da organização e do motor no .lingo/config.json incluído no commit. Faça uma alteração ao conteúdo de origem em inglês, faça commit e acione o workflow a partir desse ramo de confiança. Consulte o resultado da execução e as diferenças no registo da tarefa. Depois, descarregue o artefacto e procure a entrada em espanhol correspondente à sua alteração. Carregue-a na aplicação e verifique o significado e as variáveis.

O carregamento inclui ficheiros ocultos para preservar .lingo/lock.json. Limite a lista de caminhos ao ficheiro de destino pretendido e ao Lockfile; não a alargue para incluir credenciais ou outros ficheiros ocultos privados.

As verificações da shell confirmam a presença dos ficheiros e a sintaxe JSON. Um ficheiro de destino antigo pode passar ambas as verificações, pelo que é importante inspecionar a entrada alterada. Se o motor de localização exigir revisão humana, a execução pode continuar a aguardar intervenção humana depois de o comando terminar. Antes de usar essa política num executor descartável, adicione o procedimento de preservação do estado da execução de CI. Após a submissão, exporte o apontador dessa execução e o caminho absoluto original da raiz do projeto e carregue .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, o ficheiro de destino e o Lockfile como artefactos de acesso restrito. Use if: always() nos passos de exportação e carregamento para que uma falha numa verificação posterior não descarte o estado recuperável; se o apontador estiver em falta, investigue a submissão em vez de inventar um.

Após a revisão, restaure exatamente essa revisão do código e esse estado dos ficheiros no caminho absoluto da raiz registado, restaure o apontador, autentique-se separadamente e use Pull com verificação de conflitos. Se outro executor não conseguir recriar o caminho, faça a submissão e obtenha os resultados num executor persistente autorizado. Não considere o ficheiro de destino antigo do primeiro artefacto como a tradução concluída.

push --wait aguarda e descarrega os resultados concluídos disponíveis. Sem --wait, o envio termina normalmente após a submissão. As tarefas separadas de submissão e obtenção exigem a mesma exportação e reposição do estado da execução; copiar apenas o Lockfile não é suficiente. Mantenha juntos os ficheiros de destino descarregados e o Lockfile da mesma operação concluída e nunca arquive a totalidade de ~/.lingo.

Entregar um pull request #

Depois de inspecionar o artefacto com sucesso, conceda à tarefa as permissões contents: write e pull-requests: write. A política do repositório também tem de permitir que o Actions crie pull requests. GITHUB_TOKEN autoriza estas operações no GitHub; mantenha LINGO_API_KEY para a tradução.

Configure uma identidade Git de acordo com a política de bots da sua equipa. Em seguida, após a validação dos resultados, adicione um passo que prepare para commit apenas o ficheiro de destino esperado e o Lockfile:

bash
git add locales/es.json .lingo/lock.json
git diff --cached --quiet && exit 0
branch="lingo/translations-${GITHUB_RUN_ID}"
git switch -c "$branch"
git commit -m "chore: update translations"
git push origin "$branch"
gh pr create --fill --base "$GITHUB_REF_NAME" --head "$branch"

Os executores alojados pelo GitHub incluem a CLI do GitHub. Disponibilize GH_TOKEN a este passo através de secrets.GITHUB_TOKEN. A sequência pressupõe um acionamento a partir de um ramo de confiança e um nome de ramo novo; repetir a execução com um ramo existente exige uma decisão explícita sobre a sua reutilização ou substituição. Este workflow não se destina a escrever os resultados num fork.

O pull request tem como destino o ramo a partir do qual acionou a tarefa. Se o GitHub assinalar os workflows desse pull request como estando a aguardar aprovação, uma pessoa com permissões de escrita no repositório tem de selecionar Aprovar a execução dos workflows; consulte o comportamento do GITHUB_TOKEN no GitHub. Reveja as diferenças da tradução, as verificações e os resultados na aplicação antes de integrar as alterações.

É possível fazer commits diretamente no ramo que acionou a execução, desde que a política de ramos o permita, mas isso elimina este passo separado de revisão do conteúdo e exige medidas para evitar ciclos.

Agendar trabalho e gerir monorepositórios #

Quando a primeira execução produzir resultados úteis, adicione ramos de confiança para acionar o workflow em eventos de envio e filtros de caminhos dos ficheiros de origem. Os commits de tradução gerados não devem acionar continuamente novas tarefas de tradução. Combine filtros de ramos ou caminhos adequados com a condição de saída quando não há alterações no passo de entrega.

Num monorepositório, defina como diretório de trabalho do passo de tradução o pacote que contém .lingo/config.json. Atualize os caminhos dos artefactos e dos ficheiros preparados para incluir esse pacote. Uma matriz pode processar pacotes independentes, mas duas entradas não devem tentar atualizar a mesma configuração e o mesmo Lockfile em simultâneo. As entradas de uma mesma execução partilham o ID dessa execução, por isso atribua a cada uma um nome de artefacto e um ramo de tradução próprios, por exemplo, acrescentando o nome do pacote a translated-catalog e lingo/translations-${GITHUB_RUN_ID}.

Recuperar uma execução incompleta #

Comece pelo estado indicado: resolva os erros dos destinos com falhas, tome decisões sobre os destinos que aguardam revisão e, nos conflitos locais de obtenção, escolha entre a alteração local e o resultado descarregado. Mantenha os resultados bem-sucedidos disponíveis para inspeção e deixe por resolver os idiomas incompletos. Um resultado parcial não deve ser aceite como uma versão completa de um idioma.

Mantenha visíveis os códigos de saída diferentes de zero. Usar || true, forçar a obtenção por cima de alterações ou forçar todos os destinos pode ocultar a causa e substituir trabalho já aceite. O guia de workflows de CI explica como preservar a revisão do código e o estado de referência durante a recuperação.

Desative o workflow ou o respetivo gatilho para impedir novas tarefas do executor. Se uma tarefa já tiver submetido uma tradução, inspecione separadamente essa execução no servidor ao cancelar o Actions. Remova os segredos não utilizados e o acesso de escrita ao repositório quando desativar definitivamente o workflow.