Workflows de localização em CI/CD

O Lingo.dev automatiza sua localização em CI/CD. Há duas formas de fazer isso: com o GitHub App, que responde aos seus pushes e pull requests no servidor, ou com a CLI executada no seu próprio pipeline. As duas opções mantêm as traduções sincronizadas a cada mudança e processam apenas as strings que realmente foram alteradas — assim, a localização continua rápida e econômica conforme seu projeto cresce.

Opção 1: GitHub App (recomendado)#

O GitHub App é a maneira mais simples de executar a Localização contínua. Ele monitora seu repositório e traduz no servidor, então você não precisa instalar nada no pipeline nem armazenar uma chave de API como segredo de CI.

A configuração é feita uma única vez:

1. Instale o GitHub App da Lingo.dev no seu repositório.
2. Faça commit de um .lingo/config.json com seu orgId, engineId, idioma de origem, idiomas de destino e os arquivos a serem traduzidos. Execute lingo init e lingo link localmente para gerá-lo e depois faça commit do resultado.
3. Faça push.

A partir daí, o App cuida dos dois estilos de workflow para você:

• Em um push para a branch padrão, ele faz commit das traduções de volta na própria branch.
• Em um pull request, ele adiciona as traduções ao PR para que você possa fazer a revisão antes do merge.

Como o App acompanha o estado da tradução no servidor, não há lockfile no repositório para gerar conflitos nem etapa de verificação para configurar — ele simplesmente mantém seus idiomas de destino sincronizados com a origem.

Opção 2: CLI no seu próprio pipeline#

Se você não usa GitHub, ou quer que a localização rode como uma etapa explícita ao lado dos jobs de build e teste, execute a CLI por conta própria. Ela funciona em qualquer ambiente de CI com Node.js 22 ou superior, incluindo GitHub Actions, GitLab CI, Bitbucket Pipelines ou qualquer outro.

O fluxo é sempre o mesmo:

1. Instale @lingo.dev/cli.
2. Autentique-se com sua chave de API pela variável de ambiente LINGO_API_KEY.
3. Execute lingo push para traduzir as strings alteradas.
4. Faça commit dos resultados ou abra um pull request a partir do job.

Armazene sua chave de API da Lingo.dev como um segredo de CI e exponha-a como LINGO_API_KEY. O .lingo/config.json versionado informa à CLI o que deve ser traduzido, e o .lingo/lock.json versionado (regenerado por lingo push) rastreia o estado para que apenas as strings alteradas sejam processadas.

Exemplo mínimo com GitHub Actions#

Este workflow instala a CLI, traduz a cada push para main e faz commit dos resultados de volta:

name: Localize
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g @lingo.dev/cli
      - run: lingo push
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Commit translations
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add .
          git commit -m "chore: update translations" || echo "No changes"
          git push

As mesmas duas linhas — npm install -g @lingo.dev/cli e depois lingo push — podem ser usadas em um bloco script: do GitLab CI ou em uma etapa do Bitbucket Pipelines. Defina LINGO_API_KEY como uma variável de CI mascarada/protegida nessas plataformas.

Commit ou pull request?#

Seja qual for o caminho escolhido, você ainda decide como as traduções vão entrar:

O GitHub App oferece as duas opções automaticamente — ele faz commit em pushes para a branch padrão e adiciona traduções aos PRs abertos. No seu próprio pipeline, a escolha é sua: fazer commit dos resultados, como mostrado acima, ou configurar o job para abrir um pull request em vez de enviar direto para a branch.

Verificando traduções antes do deploy#

Para garantir que nenhum conteúdo sem tradução chegue à produção, adicione lingo check como uma etapa de bloqueio antes do deploy. Ele retorna um status diferente de zero quando ainda há strings que precisam ser traduzidas:

- name: Verify translations
  run: lingo check

O GitHub App mantém os idiomas sincronizados continuamente, então uma etapa dedicada de verificação é mais útil quando você executa a CLI por conta própria.

Monorepos#

Em monorepos em que cada pacote tem seu próprio .lingo/config.json, limite a execução a um pacote passando um glob ou execute a CLI a partir do diretório desse pacote:

lingo push "apps/web/**"

Próximos passos#