GitLab CI/CD

Execute o Lingo.dev no GitLab CI para que cada merge request que adiciona ou altera strings de origem volte com as traduções já preenchidas. O pipeline executa lingo push, o motor de localização traduz apenas as chaves novas ou alteradas, e o resultado é gravado diretamente no branch do MR — as traduções aparecem no diff do MR e são alvo de revisão antes de alguém fazer merge. Nada chega ao seu branch predefinido sem passar por revisão.

Pré-requisitos#

• Uma organização e um motor da Lingo.dev, além de uma chave de API de serviço (Dashboard → API Keys → create, type service).

• Um projeto configurado para o Lingo.dev. Gere-o uma vez com:

  bashCopy

  npx @lingo.dev/cli@latest init   # scaffolds .lingo/config.json
  npx @lingo.dev/cli@latest link   # connects the project to your org + engine

  .lingo/config.json define os idiomas de origem/destino e os globs de origem:

  jsonCopy

  {
    "sourceLocale": "en",
    "targetLocales": ["es", "fr", "de", "zh"],
    "files": [{ "pattern": "locales/en.json" }],
    "orgId": "org_...",
    "engineId": "eng_..."
  }

• Uma base já com commit. Na primeira vez, traduza tudo e faça commit para que o CI tenha um lockfile com o qual comparar diferenças:

  bashCopy

  npx @lingo.dev/cli@latest push --backfill-missing --wait
  git add locales .lingo && git commit -m "chore(i18n): baseline translations"

Tokens de acesso#

Adicione duas variáveis de CI/CD masked em Settings → CI/CD → Variables:

• LINGO_API_KEY — a sua chave de serviço do Lingo.dev (lingo_sk_...). A CLI lê-a automaticamente para autenticação.
• GITLAB_PUSH_TOKEN — um Project Access Token com o âmbito write_repository (função Developer). Isto permite ao CI fazer commit das traduções de volta para o branch do MR.

Pipeline#

Faça commit deste ficheiro .gitlab-ci.yml. É executado em merge requests com destino ao branch predefinido e envia as traduções de volta para o branch de origem do MR:

stages:
  - localize

localize:
  stage: localize
  image: node:22-alpine
  rules:
    # Only on merge requests that target the default branch.
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH'
  before_script:
    - apk add --no-cache git
  script:
    # Pin the CLI version — never @latest; bump deliberately after testing.
    # --wait blocks until the engine finishes and writes files: since 1.6.0
    # `push` is async by default (it submits the run and exits), so CI must
    # wait to have something to commit.
    - npx -y @lingo.dev/cli@1.6.0 push --wait
    - |
      if [ -z "$(git status --porcelain)" ]; then
        echo "Translations already up to date — nothing to commit."
        exit 0
      fi
      git config user.name "lingo-bot"
      git config user.email "bot@lingo.dev"
      git add locales .lingo/lock.json
      # [skip ci] keeps the bot's own commit from re-triggering this pipeline.
      git commit -m "chore(i18n): sync translations [skip ci]"
      git push "https://oauth2:${GITLAB_PUSH_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git" "HEAD:${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME}"

Experimente#

git checkout -b feat/new-strings
# add or change a key in locales/en.json
git commit -am "feat: add strings" && git push -u origin feat/new-strings
# open an MR feat/new-strings -> main (UI, or: glab mr create --fill --target-branch main)

O pipeline do MR executa lingo push --wait, faz commit de locales/{...}.json juntamente com o .lingo/lock.json atualizado no branch do MR, e as traduções aparecem no diff. Um revisor ajusta os valores necessários e depois faz merge.

Como as edições humanas são preservadas#

lingo push preserva as edições manuais por chave:

• Edite uma string de destino (mantendo a origem em inglês inalterada) → essa string é preservada; todas as outras chaves continuam a ser traduzidas.
• A origem em inglês por trás de uma chave editada muda → é gerada uma nova tradução para essa chave (porque o significado mudou).
• É adicionada uma nova chave de origem → é traduzida e adicionada, mesmo em ficheiros com edições manuais.

Assim, a correção de um revisor no MR sobrevive a todas as execuções posteriores do pipeline, enquanto as chaves novas e alteradas entram automaticamente.

Modos de push#

• lingo push — incremental; o modo predefinido no CI. Traduz apenas chaves novas/alteradas e preserva tudo o resto. Adicione --wait no CI para que o processo bloqueie até os outputs serem escritos (1.6.0+ é assíncrono por predefinição).
• lingo push --backfill-missing — bootstrap do primeiro push / de um novo idioma; preenche ficheiros de destino que ainda não existem. Não serve para alterações contínuas.
• lingo push --force --yes — volta a traduzir tudo de raiz (substitui edições manuais). Raro.

Personalização#

• Commit automático no branch predefinido em vez de MRs: use o gatilho em $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH e faça push de volta para $CI_DEFAULT_BRANCH. É mais simples, mas o resultado da IA chega ao branch predefinido sem revisão.
• Fixar strings específicas: use preservedKeys / lockedKeys em .lingo/config.json para manter determinadas chaves fixas, mesmo quando a respetiva origem muda.
• GitLab self-hosted: funciona sem alterações. Em gitlab.com, as contas novas têm de passar pela verificação de identidade antes de os runners partilhados executarem jobs de CI.

Próximos passos#