Receita de CI para GitLab
Traduza ficheiros num pipeline de confiança do GitLab, entregue-os através de um pedido de integração e faça falhar os pedidos de integração com traduções desatualizadas.
Um executor do GitLab pode traduzir ficheiros do repositório com a CLI do Lingo.dev e guardar os resultados como artefactos do trabalho. Assim, a tradução segue o mesmo checkout, as mesmas verificações e o mesmo processo de lançamento que o resto da aplicação. O GitLab gere a execução do pipeline e a entrega no repositório; o Lingo.dev processa os ficheiros de origem selecionados através de um motor de localização.
Esta é uma receita de CI, não uma ligação nativa a uma conta GitLab. Comece por iniciar manualmente um pipeline no ramo predefinido. Depois de verificar o resultado, adicione gatilhos recorrentes e a entrega através de pedidos de integração.
Definir a origem e as credenciais #
Conclua localmente o guia de início rápido da CLI. Faça commit de .lingo/config.json, dos ficheiros de destino aceites e de .lingo/lock.json. A configuração define o idioma de origem, os idiomas de destino, os padrões de ficheiros e o motor de localização. Execute a CLI a partir do diretório ao qual essa configuração pertence.
Crie os ficheiros de destino em falta com lingo push --backfill-missing --wait. Para alterações posteriores na origem, use o comando lingo push --wait habitual. Alterar as instruções do motor de localização não reescreve, por si só, os ficheiros aceites; a regeneração intencional é uma tarefa separada.
Nas definições de variáveis de CI/CD do projeto, guarde LINGO_API_KEY como variável mascarada. A CLI lê apenas este nome; qualquer variável LINGODOTDEV_API_KEY da CLI anterior é ignorada, pelo que deve mudar-lhe o nome. Restrinja-a aos ramos ou ambientes de confiança autorizados a submeter trabalhos de tradução. Uma variável protegida pode não estar disponível num ramo ou pedido de integração não protegido; utilize um ramo autorizado em vez de a expor a código não fidedigno.
A chave de API autoriza a tradução. Só precisa de uma credencial do GitLab com acesso de escrita ao repositório quando adicionar a entrega por commit.
Os exemplos fixam a CLI na versão 1.21.0. O comando lingo check verifica os ficheiros de tradução a partir da versão 1.20.0 da CLI. Para gerir a versão através das dependências e do Lockfile do projeto, siga o guia de configuração de CI.
Executar um pipeline que começa por gerar artefactos #
Este exemplo de .gitlab-ci.yml pressupõe que locales/en.json é a origem configurada e que locales/es.json, um ficheiro em espanhol já existente, é o seu único destino. Se houver mais destinos, execute test -s e as verificações de JSON uma vez por ficheiro de destino e inclua todos os caminhos de destino nos restantes comandos que mencionam locales/es.json. O Lockfile regista a origem como traduzida, pelo que um envio posterior a ignora, e qualquer destino que fique de fora do artefacto ou do commit permanece desatualizado. O exemplo utiliza um pipeline iniciado manualmente no ramo predefinido:
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 com que a tarefa aguarde a conclusão da execução e escreva os ficheiros traduzidos no checkout. Sem esta opção, lingo push limita-se a submeter a execução e termina, pelo que os passos seguintes não encontram ficheiros novos para inspecionar ou incluir num commit.
Verifique se o executor consegue aceder ao registo e disponibilize as ferramentas necessárias para os passos seguintes. Por exemplo, se optar por uma imagem mínima alternativa, poderá ter de instalar o Git para inspecionar as diferenças ou fazer commit das alterações.
Verifique os identificadores da organização e do motor no .lingo/config.json incluído no commit. Faça uma alteração na origem e inicie o pipeline. No registo, confirme o estado de execução indicado e a entrada de destino alterada. Transfira o artefacto, compare a tradução com essa revisão da origem e carregue-a através da aplicação. As verificações da presença de ficheiros e de JSON não permitem, por si só, confirmar se a tradução está atualizada ou se o significado está correto.
--wait transfere os resultados concluídos, mas, se a revisão humana estiver configurada, o trabalho pode ficar a aguardar a intervenção de uma pessoa. Antes de usar uma espera por revisão ou um trabalho de recolha separado, adicione o procedimento de preservação do estado de execução em CI. Após a submissão, exporte a referência específica 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 artefactos de trabalho de 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 é executada se uma validação posterior falhar; não oculte a falha original.
Conclua a revisão e, em seguida, restaure a revisão e o estado dos ficheiros registados, usando o mesmo caminho absoluto da raiz no executor de recolha. Restaure apenas essa referência, autentique-se separadamente e use lingo pull --dry-run antes da recolha. Se o executor não conseguir recriar o caminho original, use um executor persistente e autorizado para ambos os trabalhos. Nunca arquive todo o conteúdo de ~/.lingo. Uma submissão bem-sucedida ou um ficheiro de destino antigo não bastam, por si só, para disponibilizar novos ficheiros para publicação.
Fazer commit das traduções num pedido de integração #
Este trabalho traduz as alterações na origem de um pedido de integração e faz commit dos resultados no mesmo ramo. Pressupõe que o preenchimento inicial dos ficheiros em falta já foi incluído num commit e que a Revisão humana do motor está desativada, permitindo concluir a tradução num único trabalho.
No GitLab 18.4 ou posterior, ative Definições → CI/CD → Permissões do token de trabalho → Permitir pedidos de push do Git para o repositório. O trabalho usa o token integrado do GitLab; a pessoa que o inicia tem de ter permissão para fazer push para o ramo de origem. Consulte a configuração do token de trabalho do GitLab.
Mantenha LINGO_API_KEY mascarado e protegido. Use ramos de origem e de destino de confiança no mesmo projeto, proteja ambos e ative Permitir que os pipelines de pedidos de integração acedam a variáveis e executores protegidos nas definições de CI/CD do projeto. A pessoa que inicia o pipeline também precisa de acesso para fazer push ou integrar alterações no ramo de destino. Estes são os requisitos do GitLab para variáveis protegidas.
Use os mesmos caminhos de origem e de destino do primeiro exemplo. Adicione este trabalho à fase 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 trabalho de tradução de cada vez por MR. O trabalho faz commit apenas do destino em espanhol e do Lockfile de tradução. Se o ramo mudar durante a tradução, o Git rejeita o push; execute um pipeline para o ramo atualizado.
CI_REPOSITORY_URL fornece as credenciais do token de trabalho. Os pushes com este token não iniciam outro pipeline, por isso adicione as verificações de recursos da aplicação antes do passo de commit. Reveja as diferenças da tradução no MR e execute as verificações restantes antes de integrar as alterações.
Como esse envio não inicia nenhum pipeline, o commit mais recente do pedido de integração fica sem pipeline. Se o projeto exigir Os pipelines têm de ser bem-sucedidos, o GitLab pode bloquear a integração. Nesse caso, selecione Executar pipeline no separador Pipelines do pedido de integração. A tarefa não encontra nada para enviar e termina sem criar um commit, e esse pipeline atribui um estado ao commit mais recente.
Abrir um pedido de integração de traduções a partir do ramo predefinido #
Esta tarefa traduz cada alteração que chega ao ramo predefinido e abre um pedido de integração com o resultado. As opções de envio do GitLab criam o pedido de integração no mesmo git push, sem necessidade de chamadas à API ou ferramentas adicionais. Aplicam-se os mesmos pressupostos da tarefa acima: as traduções iniciais já foram incluídas num commit e a Revisão humana está desativada.
Crie um token de acesso ao projeto com a função de Programador e o âmbito write_repository. Guarde-o como variável de CI/CD mascarada e protegida, com o nome GITLAB_PUSH_TOKEN. No GitLab.com, os tokens de acesso ao projeto requerem um plano pago. Não se utiliza CI_JOB_TOKEN aqui, porque o GitLab não inicia nenhum pipeline para envios feitos com esse token. O URL de envio utiliza CI_SERVER_FQDN, que preserva a porta de uma instância autogerida quando esta utiliza uma porta não padrão. CI_SERVER_FQDN requer o GitLab 16.10 ou posterior. Numa instância autogerida mais antiga, utilize ${CI_SERVER_HOST}:${CI_SERVER_PORT} em alternativa.
Adicione esta tarefa à fase 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, pelo que a tarefa para antes do commit. Quando não há alterações, apresenta "Nada para enviar", não há diferenças preparadas para o commit e a tarefa termina sem criar um commit.
As primeiras duas linhas interrompem a tarefa se o ramo predefinido já tiver avançado para além do commit em que esta está a ser executada. resource_group executa uma tarefa de cada vez, mas, no modo de processamento unordered predefinido do GitLab, inicia as tarefas em espera sem uma ordem fixa. Sem esta verificação, uma tarefa mais antiga poderia ser executada em último lugar e fazer um envio forçado que substituísse as traduções mais recentes por versões antigas. A tarefa do commit mais recente traduz esse commit, e nada é submetido para commits já desatualizados.
A tarefa não se repete em ciclo. Só é executada para envios para o ramo predefinido e só escreve em lingo/translations. A documentação do GitLab indica que -o ci.skip afeta apenas os pipelines de ramos, não os pipelines de pedidos de integração, e que um pipeline de pedido de integração é executado quando se cria um pedido de integração ou quando o respetivo ramo de origem recebe um novo commit. Por isso, a verificação de bloqueio abaixo deverá ser executada no pedido de integração de traduções; confirme-o na primeira execução. A integração desse pedido volta a iniciar a tarefa, que não encontra nada para enviar.
Cada execução reconstrói lingo/translations a partir do commit do ramo predefinido em que foi executada e faz um envio forçado, pelo que um pedido de integração aberto apresenta as diferenças de tradução mais recentes. As edições manuais feitas nesse ramo são substituídas pela execução seguinte; faça-as após a integração. Enquanto o pedido de integração não for integrado, o ramo predefinido mantém o .lingo/lock.json anterior, pelo que a execução seguinte volta a submeter as mesmas alterações à origem. Se commits posteriores anularem todas as alterações à origem traduzidas pelo pedido de integração, a execução seguinte não encontra nada para enviar e deixa o pedido de integração aberto com traduções desatualizadas; feche-o em vez de o integrar.
Fazer falhar pedidos de integração com traduções desatualizadas #
O comando lingo check compara cada origem configurada com .lingo/lock.json e exige a presença de todos os ficheiros de destino. Termina com o código de saída 1 quando uma origem mudou desde a última tradução, uma origem não tem entrada no Lockfile, falta um ficheiro de destino ou nenhum ficheiro de origem corresponde aos padrões files. Não precisa de chave de API nem de variável de CI/CD e não escreve nada, pelo que também pode ser executado em pedidos de integração provenientes de bifurcações. À exceção da telemetria da CLI, que DO_NOT_TRACK=1 desativa, não faz chamadas de rede; os exemplos de npx continuam a transferir a CLI do npm antes de executar a verificação. Substitui a verificação de bloqueio --frozen da CLI anterior.
Verifica ficheiros, não chaves: um destino editado manualmente passa na verificação, e uma chave em falta num destino existente não é assinalada, exceto nos catálogos .jsonc do React. Sem .lingo/lock.json, não consegue detetar alterações à origem, pelo que uma origem alterada ou nunca enviada não faz falhar a verificação, que assinala esse facto em stderr. Inclua num commit o Lockfile que lingo push escreve.
Adicione check à lista stages e, em seguida, adicione a tarefa adequada à sua configuração. Se os programadores executarem lingo push --wait e incluírem o resultado num commit juntamente com a alteração à origem, verifique todos os pedidos de integração:
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 do ramo predefinido, verifique apenas o respetivo pedido de integração de traduções, porque os pedidos de integração 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 a uma configuração em que as traduções são incluídas num commit juntamente com a alteração à origem:
| Onde é executada a tradução | Verificação de bloqueio em todos os pedidos de integração |
|---|---|
Os programadores executam lingo push --wait e incluem o resultado num commit antes de abrir o pedido de integração | Sim. Faz falhar um pedido de integração cuja origem tenha sido alterada sem ser traduzida. |
| A tarefa do pedido de integração cria commits no ramo 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 do ramo predefinido abre um pedido de integração de traduções | Apenas em lingo/translations, com a segunda tarefa acima. Os pedidos de integração de funcionalidades alteram as origens antes da tradução, por definição. |
Os hashes da origem são exatos ao nível dos bytes. Certifique-se de que o checkout em que foi executado lingo push e o checkout de CI utilizam os mesmos finais de linha, por exemplo, com * text=auto eol=lf em .gitattributes.
Tornar o trabalho recorrente previsível #
Filtre os trabalhos automáticos para abranger apenas os ramos de confiança e os caminhos de origem pretendidos. Se usar gatilhos de pedidos de integração, restrinja também o projeto de origem e o ramo de destino. Impeça que os commits gerados submetam traduções repetidamente: use uma regra de ramo ou uma política adequada para ignorar a CI e termine a execução quando não houver diferenças.
Num monorepositório, aceda ao pacote que contém a configuração pretendida e conserve os resultados e o estado com caminhos relativos a esse pacote. Pacotes independentes podem ter motores de localização e idiomas diferentes; mantenha os respetivos Lockfiles separados. A mesma abordagem com executores funciona com o GitLab autogerido, desde que o acesso à rede, as ferramentas do executor, as variáveis e a política do repositório o permitam.
A tradução incremental habitual pode preservar uma chave de destino editada manualmente enquanto a respetiva origem permanecer inalterada. Uma alteração na origem pode regenerar essa chave. O preenchimento de ficheiros em falta e a regeneração forçada têm âmbitos diferentes. Sem padrões de ficheiros, --force abrange todos os idiomas de origem e de destino configurados e pode substituir traduções aceites. Use padrões explícitos e analise uma estimativa antes de forçar o trabalho. Consulte Push ao alterar o comando de submissão.
Recuperar e desativar o pipeline #
Use o erro para determinar a próxima ação: corrigir a instalação do pacote, fornecer uma variável autorizada, concluir a revisão, resolver um conflito de integração ou voltar a executar o trabalho de destino que falhou, depois de corrigir a causa. Preserve os artefactos concluídos com êxito, mas mantenha claramente assinalado como incompleto qualquer lançamento parcialmente concluído.
Desative o gatilho para impedir novos pipelines. Ao cancelar o executor, verifique separadamente qualquer tradução já submetida. Quando deixar de usar esta receita, remova as credenciais de API e de repositório obsoletas.