Guia de implementação com Bitbucket Pipelines
Traduza ficheiros no Bitbucket Pipelines, faça commit dos resultados no repositório e faça falhar os pedidos de integração com traduções desatualizadas.
Utilize um Pipeline do Bitbucket para traduzir os ficheiros de origem selecionados na configuração do Lingo.dev. A CLI submete o trabalho e descarrega os ficheiros de destino; o Pipeline determina como os conservar e entregar. Este guia começa com um Pipeline personalizado, iniciado manualmente, para que possa verificar uma tradução antes de agendar trabalho recorrente.
A ligação é feita por uma chamada do executor à API, e não por um conector nativo da conta Bitbucket. A escrita no repositório e a criação de pedidos de integração exigem permissões distintas no Bitbucket.
Prepare um catálogo funcional #
Siga o guia de início rápido da CLI localmente e, em seguida, faça commit de .lingo/config.json, dos ficheiros de destino verificados e de .lingo/lock.json. Os idiomas de origem e de destino, o motor de localização e os padrões de ficheiros devem ser definidos nessa configuração.
O exemplo utiliza locales/en.json e tem como único destino um ficheiro em espanhol já existente em locales/es.json. Se houver mais destinos, execute as verificações de test -s e de JSON uma vez por ficheiro de destino e indique 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 permanece desatualizado. Crie os ficheiros de destino em falta com lingo push --backfill-missing --wait antes de adotar o comando abaixo para processar alterações recorrentes na origem. O envio normal processa as alterações posteriores na origem; o preenchimento de ficheiros em falta não corrige chaves em falta num destino existente.
Guarde LINGO_API_KEY como variável protegida do repositório. A CLI lê apenas este nome; uma variável LINGODOTDEV_API_KEY da CLI anterior é ignorada, pelo que deve mudar-lhe o nome. Execute o Pipeline com código de confiança e mantenha o rastreio da shell desativado ao lidar com credenciais. Proteger uma variável não torna seguro expô-la a scripts arbitrários de um pedido de integração.
Os exemplos usam a CLI com a versão fixa 1.21.0. 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 seu projeto, siga o guia de configuração de CI.
Traduza e conserve o resultado #
Adicione este Pipeline personalizado a bitbucket-pipelines.yml:
image: node:22
pipelines:
custom:
translate-catalog:
- step:
name: Translate and inspect
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:
- locales/es.json
- .lingo/lock.jsonCertifique-se de que o executor consegue descarregar a CLI a partir do npm. Adapte os caminhos dos ficheiros à sua configuração.
Verifique os IDs da organização e do motor em .lingo/config.json, já incluído num commit. Faça commit de uma pequena alteração no conteúdo de origem em inglês e execute translate-catalog nesse ramo de confiança. Verifique o resultado da execução e as diferenças; depois, descarregue o artefacto e compare a entrada alterada em espanhol com a revisão de origem. Carregue o catálogo através da aplicação para verificar as variáveis e a apresentação.
A verificação da existência dos ficheiros e a análise de JSON detetam resultados em falta ou malformados. Não permitem distinguir um ficheiro antigo e válido da nova tradução que pediu. Se o motor de localização exigir revisão humana, conclua a revisão e obtenha os resultados concluídos antes de aceitar o artefacto.
Preserve o estado de submissão e obtenção dos resultados #
O envio é assíncrono por predefinição. push --wait aguarda a conclusão da execução e grava os ficheiros traduzidos no checkout. Sem --wait, lingo push limita-se a submeter a execução e termina, pelo que o comando seguinte não encontra novos ficheiros para conservar ou incluir num commit. Quando é necessário aguardar pela revisão humana, pode ainda ser preciso obter os resultados num passo posterior.
Antes de uma espera por revisão ou de uma etapa separada de obtenção dos resultados, adicione o procedimento de preservação do estado da execução de CI. Após a submissão, exporte o apontador específico e o caminho absoluto original da raiz do projeto, mesmo que uma validação posterior falhe. Conserve .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, o ficheiro de destino e o Lockfile como artefactos de acesso restrito, com um prazo de retenção suficiente para a revisão. Mantenha visível a falha da etapa original e nunca arquive todo o conteúdo de ~/.lingo nem credenciais.
Para obter os resultados, restaure a mesma revisão e o estado dos ficheiros conservados no caminho absoluto registado para a raiz do projeto. Restaure apenas esse apontador, forneça as credenciais separadamente e utilize Obter com --dry-run antes de recolher os resultados. Se uma etapa posterior do Pipeline não conseguir recriar o caminho, utilize um executor persistente e autorizado tanto para a submissão como para a obtenção dos resultados. Resolva cuidadosamente os conflitos nos ficheiros de saída locais; forçar a obtenção pode eliminar as alterações de quem fez a revisão.
Escolha como os resultados chegam ao repositório #
Um artefacto é suficiente quando uma pessoa ou uma tarefa de lançamento posterior deve verificar os resultados antes da entrega. Conserve em conjunto os ficheiros traduzidos e o Lockfile da mesma operação concluída.
Para atualizar o repositório após uma revisão, envie as alterações para um ramo de tradução e abra um pedido de integração no Bitbucket ou através da respetiva API documentada. Um passo pode enviar alterações para o seu próprio repositório através de origin, que está configurado por predefinição, sem credenciais adicionais, como mostra a secção seguinte. Adicione uma chave SSH do repositório ou um token de acesso apenas se as permissões do ramo bloquearem esse envio ou se pretender criar o pedido de integração através da API, o que exige permissões de escrita em pedidos de integração. Configure a identidade do bot da equipa, adicione à área de preparação apenas os caminhos de destino conhecidos e .lingo/lock.json, e termine se não houver diferenças nessa área. Use nomes de ramo distintos ou reutilize os ramos de forma deliberada para evitar que as execuções simultâneas se sobrescrevam.
Um commit direto utiliza as mesmas verificações dos resultados e a mesma seleção restrita de alterações para commit, mas envia para o ramo de confiança explicitamente escolhido. A entrega direta no ramo predefinido elimina a etapa de revisão do pedido de integração da tradução, pelo que deve resultar de uma escolha deliberada na política de ramos. Em qualquer dos modelos, reveja o resultado na aplicação.
Mantenha a chave de API do Lingo.dev separada das credenciais do repositório. Deve ficar no ambiente do processo de tradução, nunca num destino remoto Git, num ficheiro incluído num commit ou num artefacto de saída. Prepare para commit caminhos explícitos em vez de git add . para evitar incluir ficheiros do executor que não estejam relacionados.
Fazer commit das traduções no ramo #
Este Pipeline de ramo traduz cada alteração que chega a main e faz commit do resultado em main. Pressupõe que as traduções iniciais já foram incluídas num commit e que a revisão humana do motor está desativada, permitindo concluir a tradução num único passo. Adicione a respetiva secção branches sob a mesma chave pipelines do Pipeline personalizado. O ficheiro completo fica assim:
image: node:22
pipelines:
custom:
translate-catalog:
- step:
name: Translate and inspect
script:
- 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:
- locales/es.json
- .lingo/lock.json
branches:
main:
- step:
name: Translate and commit
auth:
system:
scopes:
- read:git:bitbucket
- write:git:bitbucket
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 "[skip ci] Update translations"
- git push origin "HEAD:$BITBUCKET_BRANCH"lingo push --wait termina com um código diferente de zero quando um destino falha, pelo que o passo é interrompido antes do commit. Quando não há alterações, apresenta "Nothing to push", não há diferenças na área de preparação e o passo termina sem fazer commit.
O Pipelines configura o repositório remoto origin para que um passo possa enviar alterações para o seu próprio repositório sem credenciais adicionais. O bloco auth do passo dá ao respetivo token integrado permissão para enviar alterações através do Git. A partir de 30 de abril de 2027, o Bitbucket deixa de conceder essa permissão a passos sem um bloco auth. Os executores autoalojados precisam da versão 6.1.0 ou posterior para utilizar auth. Se uma restrição de ramo em main bloquear o envio, adicione main como ramo de origem nas permissões de escrita do Pipelines dessa restrição ou atribua ao passo uma chave SSH ou um token de acesso com permissões de escrita, conforme descrito no guia do Bitbucket para enviar alterações de volta para o repositório.
O passo não entra num ciclo. A presença de [skip ci] na mensagem de commit impede o Bitbucket de iniciar um Pipeline para o commit das traduções. Sem isso, a execução seguinte não encontraria nada para enviar, porque o .lingo/lock.json incluído no commit já regista o novo conteúdo de origem. Se o ramo tiver avançado durante a tradução, o Git rejeita o envio; o Pipeline do commit mais recente trata da tradução desse conteúdo.
Adapte os gatilhos e os caminhos dos pacotes #
Adicione gatilhos automáticos de ramo ou de pedido de integração apenas depois de decidir que código-fonte pode aceder às credenciais e que ramo pode receber operações de escrita. Uma bifurcação pode não ter segredos ou um destino com acesso de escrita; não resolva essa situação executando código dessa bifurcação que não seja de confiança com credenciais privilegiadas.
Os commits gerados não devem desencadear traduções indefinidamente. Selecione os caminhos de origem relevantes e os ramos de confiança, aplique uma regra adequada aos commits gerados e mantenha a condição de saída quando não há alterações. É legítimo que uma origem inalterada não produza diferenças.
Para uma configuração em apps/web/.lingo/config.json, execute a CLI a partir de apps/web. Os caminhos dos artefactos do Pipeline continuam a seguir as regras do Bitbucket relativas à raiz do repositório, por isso utilize caminhos como apps/web/locales/es.json e apps/web/.lingo/lock.json. Alterar o diretório de trabalho da CLI não altera a convenção dos caminhos dos artefactos.
Fazer falhar pedidos de integração com traduções desatualizadas #
lingo check compara cada origem configurada com .lingo/lock.json e exige que todos os ficheiros de destino existam. Termina com o código 1 se uma origem tiver sido alterada desde a última tradução, se uma origem não tiver uma entrada no Lockfile, se faltar um ficheiro de destino ou se nenhum ficheiro de origem corresponder aos padrões de files. Não precisa de uma chave de API nem de uma variável de repositório e não escreve nada. À exceção da telemetria da CLI, que DO_NOT_TRACK=1 desativa, não faz chamadas de rede; o exemplo npx continua a descarregar 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 na origem, pelo que uma origem alterada ou nunca enviada não faz a verificação falhar; esta limitação é indicada em stderr. Inclua num commit o Lockfile que lingo push escreve.
Esta verificação de bloqueio destina-se a uma configuração sem o Pipeline de ramo apresentado acima; a tabela abaixo explica porquê. Adicione uma secção pull-requests sob pipelines, ao lado de custom se mantiver o Pipeline manual. Por si só, o ficheiro fica assim:
image: node:22
pipelines:
pull-requests:
"**":
- step:
name: Check translations
script:
# lingo check needs CLI 1.20.0 or newer.
- npx -y @lingo.dev/cli@1.21.0 checkA verificação de bloqueio adequa-se a uma configuração em que as traduções são incluídas num commit juntamente com a alteração da origem:
| Onde é executada a tradução | Verificação de bloqueio em cada pedido de integração |
|---|---|
Os programadores executam lingo push --wait e fazem commit do resultado antes de abrir o pedido de integração | Sim. Faz falhar os pedidos de integração em que a origem foi alterada sem atualizar a tradução. |
O Pipeline de ramo faz commit em main após a integração | Não. Neste modelo, os pedidos de integração de funcionalidades alteram as origens antes da tradução. |
Os hashes da origem são calculados byte a byte. Garanta que o checkout que executou lingo push e o checkout de CI usam os mesmos fins de linha, por exemplo com * text=auto eol=lf em .gitattributes. Mantenha também as verificações de recursos da aplicação.
Recupere resultados em falta ou interrompa o trabalho #
Se faltarem resultados, verifique os ficheiros de origem selecionados, a referência de base, a cobertura dos destinos, a disponibilidade das variáveis protegidas, o estado da revisão e as falhas comunicadas. Recupere a execução registada antes de optar por uma nova submissão. Antes de preencher os destinos em falta num projeto existente, conclua, obtenha e verifique as atualizações normais dos destinos existentes e, em seguida, mantenha fixa a revisão de origem durante o preenchimento. Siga Adicionar um idioma para cumprir essa sequência. Utilize a regeneração forçada apenas quando pretender substituir o texto aceite selecionado; a recuperação de execuções falhadas explica como pedir outra tentativa sem forçar a substituição.
Desative o gatilho do Pipeline para impedir novas tarefas. Ao cancelar o executor, verifique separadamente qualquer execução já submetida no servidor. Remova as variáveis de API não utilizadas e o acesso de escrita do fornecedor quando deixar de utilizar esta implementação.