Receita de CI para GitLab
Traduza arquivos em um pipeline confiável do GitLab, entregue as traduções por meio de uma solicitação de mesclagem e reprove solicitações com traduções desatualizadas.
Um runner do GitLab pode traduzir arquivos do repositório com a CLI do Lingo.dev e armazenar os resultados como artefatos de jobs. Assim, a tradução segue o mesmo checkout, as mesmas verificações e o mesmo processo de lançamento do restante da aplicação. O GitLab cuida da execução do pipeline e da entrega no repositório; o Lingo.dev processa os arquivos de origem selecionados por meio de um engine de localização.
Esta é uma receita de CI, não uma conexão nativa com uma conta do GitLab. Comece com um pipeline iniciado manualmente na branch padrão. Depois de conferir o resultado, adicione gatilhos recorrentes e entrega por solicitação de merge.
Defina a origem e as credenciais #
Conclua o guia de início rápido da CLI localmente. Faça commit de .lingo/config.json, dos arquivos de destino aceitos e de .lingo/lock.json. A configuração define o idioma de origem, os idiomas de destino, os padrões de arquivos e o engine de localização. Execute a CLI no diretório que contém essa configuração.
Crie os arquivos de destino ausentes com lingo push --backfill-missing --wait. Para alterações posteriores na origem, use lingo push --wait normalmente. Alterar as instruções do engine de localização não reescreve, por si só, os arquivos aceitos; regenerá-los de forma deliberada é uma tarefa separada.
Nas configurações de variáveis de CI/CD do projeto, salve LINGO_API_KEY como uma variável mascarada. A CLI lê apenas esse nome; a variável LINGODOTDEV_API_KEY da CLI anterior é ignorada, por isso, renomeie-a. Restrinja seu acesso às branches ou aos ambientes confiáveis autorizados a enviar trabalhos de tradução. Uma variável protegida pode ficar indisponível em uma branch ou solicitação de mesclagem não protegida; use uma branch autorizada em vez de expor a variável a código não confiável.
A chave de API autoriza a tradução. Uma credencial do GitLab com acesso de gravação ao repositório só é necessária quando você adiciona a entrega por commit.
Os exemplos usam a CLI fixada na versão 1.21.0. A partir da CLI 1.20.0, lingo check verifica os arquivos de tradução. Para gerenciar a versão pelas dependências e pelo Lockfile do projeto, siga o guia de configuração de CI.
Execute um pipeline com foco inicial em artefatos #
Este exemplo de .gitlab-ci.yml pressupõe que locales/en.json seja a origem configurada e que locales/es.json, um arquivo em espanhol já existente, seja seu único destino. Se houver mais destinos, execute test -s e as verificações de JSON uma vez para cada arquivo de destino e liste todos os caminhos de destino nos demais comandos que mencionam locales/es.json. O Lockfile registra a origem como traduzida, por isso um envio posterior a ignora, e qualquer destino que fique fora do artefato ou do commit permanece desatualizado. O exemplo usa um pipeline iniciado manualmente na branch padrão:
stages:
- translate
translate_catalog:
stage: translate
image: node:22
rules:
- if: '$CI_PIPELINE_SOURCE == "web" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
script:
# Replace 1.21.0 with the current CLI version.
- npx -y @lingo.dev/cli@1.21.0 push --wait
- 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
artifacts:
paths:
- locales/es.json
- .lingo/lock.json--wait faz a tarefa aguardar o término da execução e gravar os arquivos traduzidos no checkout. Sem essa opção, lingo push apenas envia a execução e encerra, de modo que as etapas seguintes não encontram arquivos novos para inspecionar ou incluir em um commit.
Verifique se o runner tem acesso ao registro e disponibilize as ferramentas necessárias para as etapas seguintes. Por exemplo, uma imagem mínima alternativa pode precisar do Git instalado para inspecionar um diff ou fazer commit das alterações.
Verifique os IDs da organização e do engine no .lingo/config.json incluído no commit. Faça uma alteração na origem e inicie o pipeline. No log, confirme o estado informado da execução e a entrada de destino alterada. Baixe o artefato, compare a tradução com essa revisão da origem e carregue-a na aplicação. As verificações de presença de arquivos e de JSON, por si só, não garantem que o conteúdo esteja atualizado nem que seu significado esteja correto.
--wait baixa o resultado concluído, mas, se a revisão humana estiver configurada, o trabalho pode ficar aguardando um revisor. Antes de usar uma espera por revisão ou um job separado de recuperação, adicione o procedimento de preservação do estado de execução de CI. Após o envio, exporte o ponteiro específico e o caminho absoluto original da raiz do projeto. Inclua .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, o destino e o Lockfile em artefatos de job com acesso restrito. Defina when: always na configuração de artifacts e estabeleça um período de retenção suficiente para a revisão. Garanta que a exportação também seja executada se uma validação posterior falhar; não oculte a falha original.
Conclua a revisão e, no runner de recuperação, restaure a revisão registrada e o estado dos arquivos no mesmo caminho absoluto da raiz do projeto. Restaure apenas esse ponteiro, autentique-se separadamente e use lingo pull --dry-run antes da coleta. Se o runner não conseguir recriar o caminho original, use um runner persistente e autorizado para os dois jobs. Nunca arquive todo o conteúdo de ~/.lingo. Um envio bem-sucedido ou um arquivo de destino antigo, por si só, não disponibiliza novos arquivos para publicação.
Faça commit das traduções em uma solicitação de merge #
Este job traduz alterações na origem de uma solicitação de merge e faz commit dos resultados na mesma branch. Ele pressupõe que o preenchimento inicial já tenha sido incluído em um commit e que a revisão humana do engine esteja desativada, para que a tradução possa ser concluída em um único job.
No GitLab 18.4 ou posterior, ative Configurações → CI/CD → Permissões do token de job → Permitir solicitações de push do Git para o repositório. O job usa o token integrado do GitLab; quem o inicia precisa ter permissão para fazer push na branch de origem. Consulte a configuração de token de job do GitLab.
Mantenha LINGO_API_KEY mascarado e protegido. Use branches de origem e destino confiáveis no mesmo projeto, proteja ambas e ative Permitir que pipelines de solicitações de merge acessem variáveis protegidas e runners nas configurações de CI/CD do projeto. Quem inicia o pipeline também precisa de acesso para fazer push ou merge na branch de destino. Esses são os requisitos do GitLab para variáveis protegidas.
Use os mesmos caminhos de origem e destino do primeiro exemplo. Adicione este job à etapa translate:
translate_merge_request:
stage: translate
image: node:22
resource_group: lingo-mr-$CI_MERGE_REQUEST_IID
rules:
- if: >-
$CI_PIPELINE_SOURCE == "merge_request_event" &&
$CI_MERGE_REQUEST_EVENT_TYPE == "detached" &&
$CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_MERGE_REQUEST_TARGET_PROJECT_ID
script:
# Replace 1.21.0 with the current CLI version.
- npx -y @lingo.dev/cli@1.21.0 push --wait
- test -s locales/es.json
- node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
- git add -- locales/es.json .lingo/lock.json
- if git diff --cached --quiet; then exit 0; fi
- git config user.name "Localization bot"
- git config user.email "localization@example.com"
- git commit -m "Update translations"
- git push "$CI_REPOSITORY_URL" "HEAD:refs/heads/$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"resource_group executa um job de tradução por vez para cada MR. O job faz commit apenas do destino em espanhol e do Lockfile de tradução. Se a branch mudar durante a tradução, o Git rejeitará o push; execute um pipeline para a branch atualizada.
CI_REPOSITORY_URL fornece as credenciais do token de job. Pushes com esse token não iniciam outro pipeline, então adicione as verificações de recursos da aplicação antes da etapa de commit. Revise o diff da tradução na MR e execute as verificações restantes antes de fazer o merge.
Como esse envio não inicia nenhum pipeline, o commit mais recente da solicitação de mesclagem fica sem pipeline. Se o projeto exigir Os pipelines devem ser bem-sucedidos, o GitLab poderá bloquear a mesclagem. Nesse caso, selecione Executar pipeline na aba Pipelines da solicitação de mesclagem. A tarefa não encontra nada para enviar e termina sem criar um commit, e esse pipeline atribui um estado ao commit mais recente.
Abra uma solicitação de mesclagem de tradução a partir da branch padrão #
Esta tarefa traduz cada alteração que chega à branch padrão e abre uma solicitação de mesclagem com o resultado. As opções de envio do GitLab criam a solicitação de mesclagem no mesmo git push, sem necessidade de chamadas de API ou ferramentas adicionais. As premissas são as mesmas da tarefa acima: as traduções iniciais já estão em um commit e a revisão humana está desativada.
Crie um token de acesso do projeto com a função Desenvolvedor e o escopo write_repository. Salve-o como uma variável de CI/CD mascarada e protegida chamada GITLAB_PUSH_TOKEN. No GitLab.com, os tokens de acesso do projeto exigem um plano pago. CI_JOB_TOKEN não é usado aqui porque o GitLab não inicia pipelines para envios feitos com ele. A URL de envio usa CI_SERVER_FQDN, que preserva a porta de instâncias autogerenciadas que usam uma porta não padrão. CI_SERVER_FQDN exige o GitLab 16.10 ou posterior. Em uma instância autogerenciada mais antiga, use ${CI_SERVER_HOST}:${CI_SERVER_PORT}.
Adicione esta tarefa à etapa translate:
translate_default_branch:
stage: translate
image: node:22
resource_group: lingo-translations
rules:
- if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
script:
- git fetch --quiet "$CI_REPOSITORY_URL" "$CI_DEFAULT_BRANCH"
- if [ "$(git rev-parse FETCH_HEAD)" != "$CI_COMMIT_SHA" ]; then exit 0; fi
# Replace 1.21.0 with the current CLI version.
- npx -y @lingo.dev/cli@1.21.0 push --wait
- test -s locales/es.json
- node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
- git add -- locales/es.json .lingo/lock.json
- if git diff --cached --quiet; then exit 0; fi
- git config user.name "Localization bot"
- git config user.email "localization@example.com"
- git commit -m "Update translations"
- >-
git push --force
-o ci.skip
-o merge_request.create
-o merge_request.target="$CI_DEFAULT_BRANCH"
-o merge_request.title="Update translations"
"https://oauth2:${GITLAB_PUSH_TOKEN}@${CI_SERVER_FQDN}/${CI_PROJECT_PATH}.git"
"HEAD:refs/heads/lingo/translations"lingo push --wait termina com um código de saída diferente de zero quando um destino falha, interrompendo a tarefa antes do commit. Quando nada mudou, exibe "Nothing to push", não há diferenças nas alterações preparadas para o commit e a tarefa termina sem criar um commit.
As duas primeiras linhas interrompem a tarefa quando a branch padrão já avançou além do commit em que ela está sendo executada. resource_group executa uma tarefa por vez, mas, no modo de processamento unordered padrão do GitLab, inicia as tarefas em espera sem uma ordem fixa. Sem essa verificação, uma tarefa mais antiga poderia ser executada por último e forçar um envio que sobrescrevesse traduções recentes com versões antigas. A tarefa correspondente ao commit mais recente traduz esse commit, e nada é enviado para commits que já estejam desatualizados.
A tarefa não entra em um ciclo de execuções. Ela só é executada em envios para a branch padrão e grava apenas em lingo/translations. A documentação do GitLab informa que -o ci.skip afeta apenas pipelines de branch, não pipelines de solicitação de mesclagem, e que um pipeline de solicitação de mesclagem é executado quando a solicitação é criada ou sua branch de origem recebe um novo commit. Portanto, a verificação de bloqueio abaixo deve ser executada na solicitação de mesclagem de tradução; confirme isso na primeira execução. Mesclar essa solicitação inicia a tarefa mais uma vez, mas ela não encontra nada para enviar.
Cada execução reconstrói lingo/translations a partir do commit da branch padrão em que foi executada e força seu envio, para que a solicitação de mesclagem aberta mostre as diferenças de tradução mais recentes. Edições manuais nessa branch são substituídas na próxima execução; faça-as após a mesclagem. Enquanto a solicitação de mesclagem não for mesclada, a branch padrão mantém o .lingo/lock.json anterior, e a próxima execução envia novamente as mesmas alterações de origem. Se commits posteriores desfizerem todas as alterações de origem traduzidas pela solicitação de mesclagem, a próxima execução não encontrará nada para enviar e deixará a solicitação aberta com traduções desatualizadas; nesse caso, feche-a em vez de mesclá-la.
Reprove solicitações de mesclagem com traduções desatualizadas #
lingo check compara cada origem configurada com .lingo/lock.json e exige que todos os arquivos de destino estejam presentes. O comando termina com código de saída 1 quando uma origem mudou desde a última tradução, uma origem não tem entrada no Lockfile, um arquivo de destino está ausente ou nenhum arquivo de origem corresponde aos padrões files. Não precisa de chave de API nem de variável de CI/CD e não grava nada, por isso também pode ser executado em solicitações de mesclagem de forks. Com exceção da telemetria da CLI, desativada por DO_NOT_TRACK=1, não faz chamadas de rede; os exemplos de npx ainda baixam a CLI do npm antes de executar a verificação. O comando substitui a verificação de bloqueio --frozen da CLI anterior.
O comando verifica arquivos, não chaves: um destino editado manualmente passa na verificação, e a ausência de uma chave em um destino existente não é informada, exceto em catálogos .jsonc do React. Sem .lingo/lock.json, ele não consegue detectar alterações na origem, de modo que uma origem alterada ou nunca enviada não faz a verificação falhar. A verificação informa essa limitação em stderr. Inclua no commit o Lockfile gravado por lingo push.
Adicione check à lista stages e, em seguida, adicione a tarefa adequada à sua configuração. Quando os desenvolvedores executarem lingo push --wait e incluírem o resultado no commit junto com a alteração de origem, verifique todas as solicitações de mesclagem:
check_translations:
stage: check
image: node:22
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
script:
# lingo check needs CLI 1.20.0 or newer.
- npx -y @lingo.dev/cli@1.21.0 checkCom a tarefa da branch padrão, verifique apenas a solicitação de mesclagem de tradução criada por ela, pois as solicitações de mesclagem de funcionalidades alteram as origens antes da tradução:
check_translations:
stage: check
image: node:22
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME == "lingo/translations"'
script:
# lingo check needs CLI 1.20.0 or newer.
- npx -y @lingo.dev/cli@1.21.0 checkA verificação de bloqueio é adequada para configurações em que as traduções são incluídas no commit junto com a alteração de origem:
| Onde a tradução é executada | Verificação de bloqueio em todas as solicitações de mesclagem |
|---|---|
Os desenvolvedores executam lingo push --wait e incluem o resultado em um commit antes de abrir a solicitação de mesclagem | Sim. A verificação reprova solicitações de mesclagem cuja origem tenha sido alterada sem tradução. |
| A tarefa da solicitação de mesclagem cria um commit na branch de origem | Não. A verificação inspecionaria o commit anterior à tradução, e o envio feito pela tarefa não inicia um novo pipeline. |
| A tarefa da branch padrão abre uma solicitação de mesclagem de tradução | Apenas em lingo/translations, com a segunda tarefa acima. Nesse fluxo, as solicitações de mesclagem de funcionalidades alteram as origens antes da tradução. |
Os hashes de origem consideram cada byte. Garanta que o checkout em que lingo push foi executado e o checkout de CI usem os mesmos finais de linha, por exemplo, com * text=auto eol=lf em .gitattributes.
Torne o trabalho recorrente previsível #
Limite os jobs automáticos às branches confiáveis e aos caminhos de origem desejados. Se usar gatilhos de solicitação de merge, restrinja também o projeto de origem e a branch de destino. Impeça que commits gerados enviem novas tarefas de tradução repetidamente: use uma regra de branch ou uma política adequada para pular a CI e encerre a execução quando o diff estiver vazio.
Em um monorepo, acesse o pacote que contém a configuração desejada e preserve a saída e o estado nos caminhos relativos a esse pacote. Pacotes independentes podem ter engines de localização e idiomas diferentes; mantenha seus arquivos Lockfile separados. A mesma abordagem com runners funciona no GitLab autogerenciado, desde que o acesso à rede, as ferramentas do runner, as variáveis e a política do repositório permitam.
A tradução incremental comum pode preservar uma chave de destino editada manualmente enquanto sua origem permanecer inalterada. Uma alteração na origem pode regenerar essa chave. O preenchimento de arquivos ausentes e a regeneração forçada têm escopos diferentes. Sem padrões de arquivos, --force abrange todos os idiomas de origem e destino configurados e pode substituir traduções aceitas. Use padrões explícitos e confira uma estimativa antes de forçar a execução. Consulte Push ao alterar o comando de envio.
Recupere e desative o pipeline #
Use o erro para identificar a próxima ação: corrigir a instalação de pacotes, fornecer uma variável autorizada, concluir a revisão, resolver um conflito de merge ou tentar novamente a tarefa de destino que falhou após corrigir sua causa. Preserve os artefatos gerados com sucesso, mas mantenha claramente indicado quando um lançamento estiver apenas parcialmente concluído.
Desative o gatilho para impedir novos pipelines. Ao cancelar o runner, confira separadamente qualquer tradução já enviada. Remova as credenciais obsoletas de API e de repositório ao desativar a receita.