Workflows de localização em CI/CD

A Lingo.dev automatiza a sua localização em CI/CD. Há duas formas de o fazer: a GitHub App, que reage aos seus pushes e pull requests do lado do servidor, ou a CLI, executada no seu próprio pipeline. Ambas mantêm as traduções sincronizadas a cada alteração e processam apenas as strings que mudaram realmente — para que a localização continue rápida e económica à medida que o seu projeto cresce.

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

A GitHub App é a forma mais simples de executar Localização Contínua. Monitoriza o seu repositório e traduz do lado do servidor, por isso não há nada para instalar no seu pipeline nem nenhuma chave de API para guardar como segredo de CI.

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

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

A partir daí, a App trata destes dois estilos de workflow por si:

• Num push para a sua branch predefinida, faz commit das traduções de volta na branch.
• Num pull request, adiciona as traduções a esse PR para que as possa rever antes do merge.

Como a App acompanha o estado das traduções do lado do servidor, não há lockfile no seu repositório que possa gerar conflitos, nem uma etapa de verificação para configurar — limita-se a manter os seus idiomas de destino sincronizados com o de origem.

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

Se não estiver no GitHub, ou se quiser que a localização corra como uma etapa explícita ao lado dos seus jobs de build e teste, execute a CLI por si. Funciona em qualquer ambiente de CI com Node.js 22 ou superior — GitHub Actions, GitLab CI, Bitbucket Pipelines ou qualquer outro.

O processo é sempre o mesmo:

1. Instale @lingo.dev/cli.
2. Autentique-se com a sua chave de API através da 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 seu job.

Guarde a sua chave de API da Lingo.dev como um segredo de CI e exponha-a como LINGO_API_KEY. O .lingo/config.json em commit indica à CLI o que deve traduzir, e o .lingo/lock.json em commit (regenerado por lingo push) acompanha o estado para que apenas sejam processadas as strings alteradas.

Exemplo mínimo de 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 num bloco script: do GitLab CI ou numa etapa do Bitbucket Pipelines. Defina LINGO_API_KEY como variável de CI mascarada/protegida nessas plataformas.

Commit ou pull request?#

Independentemente da opção escolhida, continua a decidir como as traduções chegam:

A GitHub App oferece-lhe ambas as opções automaticamente — faz commit nos pushes para a sua branch predefinida e adiciona traduções aos PR abertos. No seu próprio pipeline, a escolha é sua: faça commit dos resultados como mostrado acima ou configure o job para abrir um pull request em vez de fazer push para a branch.

Verificar traduções antes do deploy#

Para garantir que nenhum conteúdo por traduzir chega a produção, adicione lingo check como controlo antes da etapa de deploy. Termina com um estado diferente de zero quando ainda houver strings por traduzir:

- name: Verify translations
  run: lingo check

A GitHub App mantém os idiomas sincronizados de forma contínua, por isso uma etapa de verificação dedicada é sobretudo útil quando executa a CLI por si.

Monorepos#

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

lingo push "apps/web/**"

Próximos passos#