Receita de CI com GitHub Actions

Execute a tradução em uma tarefa confiável do GitHub Actions, inspecione os artefatos e adicione a entrega por pull request quando o resultado estiver pronto.

Execute a CLI do Lingo.dev no GitHub Actions quando a tradução precisar usar os gatilhos e as verificações do seu pipeline atual. O executor lê a configuração do repositório, envia as alterações no conteúdo de origem e baixa os arquivos traduzidos. Você decide se esses arquivos ficam como artefatos ou se dão origem a um pull request.

Esta receita começa com acionamento manual e acesso somente de leitura ao repositório. Depois de inspecionar uma mensagem alterada, você pode adicionar as permissões de escrita necessárias para criar um pull request de tradução. Como alternativa, o GitHub App nativo oferece processamento gerenciado do repositório, sem precisar configurar o executor conforme esta receita.

Prepare o repositório #

Conclua o guia de início rápido da CLI localmente, com um arquivo de origem e um idioma de destino. Faça o commit de .lingo/config.json, do arquivo de destino inspecionado e de .lingo/lock.json. A configuração define o engine de localização, os idiomas de origem e destino e os padrões de arquivos. O Lockfile registra a referência inicial para as próximas alterações no conteúdo de origem.

No exemplo abaixo, configure locales/en.json como origem e espanhol como idioma de destino, gerando locales/es.json. O primeiro arquivo de destino ausente é criado com lingo push --backfill-missing --wait; as edições posteriores no conteúdo de origem usam lingo push --wait. O preenchimento retroativo seleciona arquivos de destino ausentes, por isso não serve para corrigir chaves ausentes em um arquivo existente.

Adicione LINGO_API_KEY aos segredos do Actions do repositório ou do ambiente. Essa credencial concede acesso ao Lingo.dev, independentemente das permissões do repositório no GitHub. Execute a tarefa com credenciais apenas em código confiável. Em especial, não use pull_request_target para fazer checkout da revisão mais recente de um pull request não confiável e executá-la com o segredo.

O exemplo usa uma versão fixa da CLI. Para gerenciá-la pelas dependências e pelo Lockfile do projeto, siga o guia de configuração de CI.

Obtenha um artefato de tradução #

Salve o conteúdo a seguir 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 engine no .lingo/config.json incluído no commit. Faça uma alteração no conteúdo de origem em inglês, crie um commit e acione o workflow a partir dessa branch confiável. Confira o resultado da execução e as diferenças no log da tarefa. Depois, baixe o artefato e encontre a entrada em espanhol correspondente à sua alteração. Carregue-a na aplicação e confira o significado e as variáveis.

O envio inclui arquivos ocultos para preservar .lingo/lock.json. Limite a lista de caminhos ao arquivo de destino pretendido e ao Lockfile; não inclua credenciais nem outros arquivos ocultos privados.

As verificações do shell confirmam a presença dos arquivos e a sintaxe JSON. Um arquivo de destino antigo pode passar nas duas verificações, por isso é importante inspecionar a entrada alterada. Se o engine de localização exigir revisão humana, a execução ainda poderá estar aguardando um revisor após o retorno do comando. Antes de usar essa política em um executor descartável, adicione o procedimento de preservação do estado da execução em CI. Após o envio, exporte o ponteiro dessa execução específica e o caminho absoluto original da raiz do projeto. Envie .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, o arquivo de destino e o Lockfile como artefatos de acesso restrito. Use if: always() nas etapas de exportação e envio para que uma falha de verificação posterior não descarte o estado recuperável; se o ponteiro estiver ausente, investigue o envio em vez de inventar um ponteiro.

Após a revisão, restaure exatamente essa revisão e esse estado dos arquivos no caminho absoluto registrado para a raiz do projeto. Restaure o ponteiro, autentique-se separadamente e use Pull com verificação de conflitos. Se outro executor não conseguir recriar o caminho, faça o envio e a recuperação em um executor persistente autorizado. Não considere o arquivo de destino antigo do primeiro artefato como a tradução concluída.

push --wait aguarda e baixa os resultados concluídos disponíveis. Sem --wait, o push normalmente retorna após o envio. Tarefas separadas de envio e recuperação precisam da mesma exportação e restauração do estado da execução; copiar apenas o Lockfile não basta. Mantenha juntos os arquivos de destino baixados e o Lockfile da mesma operação concluída, e nunca arquive todo o conteúdo de ~/.lingo.

Entregue um pull request #

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

Configure uma identidade do Git de acordo com a política de bots da sua equipe. Em seguida, adicione uma etapa após a validação do resultado para preparar para commit apenas o arquivo 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 hospedados pelo GitHub incluem a CLI do GitHub. Forneça GH_TOKEN a esta etapa usando secrets.GITHUB_TOKEN. A sequência pressupõe o acionamento a partir de uma branch confiável e um novo nome de branch; executar novamente com uma branch existente exige uma decisão explícita entre reutilizá-la ou substituí-la. Este não é um workflow para gravar alterações de volta em um fork.

O pull request tem como destino a branch a partir da qual você acionou a tarefa. Se o GitHub marcar os workflows do pull request como aguardando aprovação, alguém com permissão de escrita no repositório deverá selecionar Aprovar a execução dos workflows; consulte o comportamento do GITHUB_TOKEN no GitHub. Revise as diferenças da tradução, as verificações e o resultado na aplicação antes de fazer o merge.

Uma política de branch adequada permite fazer commits diretamente na branch que acionou a execução, mas isso elimina a etapa separada de revisão de conteúdo e exige medidas para evitar loops.

Agende tarefas e gerencie monorepos #

Quando a primeira execução produzir um resultado útil, adicione branches confiáveis para acionamento por push e filtros de caminhos dos arquivos de origem. Os commits de tradução gerados não devem acionar continuamente novas tarefas de tradução. Combine filtros adequados de branch ou caminho com o encerramento sem alterações na etapa de entrega.

Em um monorepo, defina o diretório de trabalho da etapa de tradução como o diretório do pacote que contém .lingo/config.json. Atualize os caminhos dos artefatos e dos arquivos preparados para commit para incluir esse pacote. Uma matriz pode processar pacotes independentes, mas duas entradas não devem disputar a atualização da mesma configuração e do mesmo Lockfile. As entradas de uma mesma execução compartilham o ID da execução, então atribua a cada uma um nome de artefato e uma branch de tradução exclusivos, por exemplo, adicionando o nome do pacote a translated-catalog e lingo/translations-${GITHUB_RUN_ID}.

Recupere uma execução incompleta #

Comece pelo estado informado: resolva os erros dos destinos com falha, tome as decisões necessárias para os destinos que aguardam revisão e, nos conflitos locais de pull, escolha entre a edição local e o resultado baixado. Mantenha os resultados bem-sucedidos disponíveis para inspeção e deixe pendentes os idiomas incompletos. Um resultado parcial não deve ser considerado uma versão completa de um idioma.

Mantenha visíveis os códigos de saída diferentes de zero. || true, forçar um pull sobre edições ou forçar todos os destinos pode ocultar a causa e substituir trabalho já aceito. O guia de workflow de CI explica como preservar a revisão e a referência inicial durante a recuperação.

Desative o workflow ou seu gatilho para impedir novas tarefas no executor. Se uma tarefa já tiver enviado uma tradução, inspecione separadamente a execução no servidor ao cancelar a execução no Actions. Ao desativar o workflow definitivamente, remova os segredos não utilizados e o acesso de escrita ao repositório.