Receita para Bitbucket Pipelines
Traduza arquivos no Bitbucket Pipelines, faça commit do resultado no repositório e reprove pull requests com traduções desatualizadas.
Use um Pipeline do Bitbucket para traduzir os arquivos de origem selecionados pela configuração do Lingo.dev. A CLI envia o trabalho e baixa os arquivos de destino; o Pipeline define como armazená-los e entregá-los. Esta receita começa com um Pipeline personalizado, acionado manualmente, para que você possa conferir uma tradução antes de agendar execuções recorrentes.
A conexão é feita por uma chamada de API do executor, não por um conector nativo de conta do Bitbucket. Gravar no repositório e criar pull requests exige permissões separadas no Bitbucket.
Prepare um catálogo funcional #
Siga o guia de início rápido da CLI no seu ambiente local e depois faça commit de .lingo/config.json, dos arquivos de destino verificados e de .lingo/lock.json. Os idiomas de origem e destino, a engine de localização e os padrões de arquivo devem ser definidos nessa configuração.
O exemplo usa locales/en.json e tem como único destino um arquivo em espanhol já existente em locales/es.json. 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, então um push posterior a ignora, e qualquer destino que fique fora do artefato permanece desatualizado. Crie os arquivos de destino ausentes com lingo push --backfill-missing --wait antes de adotar o comando abaixo para processar alterações recorrentes na origem. O push normal processa edições posteriores na origem; o preenchimento de arquivos ausentes não corrige chaves ausentes em um destino existente.
Salve LINGO_API_KEY como uma variável protegida do repositório. A CLI lê apenas esse nome; a variável LINGODOTDEV_API_KEY da CLI anterior é ignorada, então renomeie-a. Execute o pipeline apenas com código confiável e mantenha o rastreamento do shell desativado nos trechos que lidam com credenciais. Proteger uma variável não torna seguro expô-la a scripts arbitrários de um pull request.
Os exemplos usam a CLI com a versão fixada em 1.21.0. lingo check verifica arquivos de tradução a partir da versão 1.20.0 da CLI. Para gerenciar a versão pelas dependências e pelo Lockfile do projeto, siga o guia de configuração de CI.
Traduza e armazene 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.jsonVerifique se o executor consegue baixar a CLI do npm. Ajuste os caminhos dos arquivos à sua configuração.
Confira os IDs da organização e da engine no .lingo/config.json versionado. Faça commit de uma pequena alteração na origem em inglês e execute translate-catalog nessa branch confiável. Confira o resultado da execução e as diferenças; depois, baixe o artefato e compare a entrada alterada em espanhol com a revisão da origem. Carregue o catálogo pela aplicação para verificar as variáveis e a renderização.
Verificar a existência dos arquivos e analisar o JSON permite detectar resultados ausentes ou malformados. Essas verificações não distinguem um arquivo antigo e válido da nova tradução solicitada. Se a engine de localização exigir revisão humana, conclua a revisão e recupere o resultado finalizado antes de aceitar o artefato.
Preserve o estado de envio e recuperação #
O envio é assíncrono por padrão. push --wait aguarda a execução terminar e grava os arquivos traduzidos no checkout. Sem --wait, lingo push apenas solicita a execução e encerra, então o próximo comando não encontra novos arquivos para preservar ou incluir em um commit. Quando há espera por revisão humana, ainda pode ser necessário buscar os resultados em uma etapa posterior.
Antes de aguardar uma revisão ou separar a recuperação em outra etapa, 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, inclusive se uma validação posterior falhar. Armazene .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, o destino e o Lockfile como artefatos de acesso restrito, com prazo de retenção suficiente para a revisão. Mantenha visível a falha original da etapa e nunca arquive todo o conteúdo de ~/.lingo nem as credenciais.
Para recuperar os resultados, restaure a mesma revisão e o estado dos arquivos armazenados no caminho absoluto registrado para a raiz do projeto. Restaure apenas esse ponteiro, forneça as credenciais separadamente e use Pull com --dry-run antes de coletar os resultados. Se uma etapa posterior do Pipeline não conseguir recriar o caminho, use um executor persistente e autorizado tanto para o envio quanto para a recuperação. Resolva com cuidado os conflitos nos arquivos de saída locais; forçar um pull pode descartar as alterações de um revisor.
Escolha como os resultados chegam ao repositório #
Um artefato basta quando uma pessoa ou uma tarefa posterior de lançamento precisa conferir os resultados antes da entrega. Armazene juntos os arquivos traduzidos e o Lockfile da mesma operação concluída.
Para atualizar o repositório com revisão, envie as alterações para uma branch de tradução e abra um pull request no Bitbucket ou pela API documentada do serviço. Uma etapa pode enviar alterações ao próprio repositório pelo origin padrão, sem credenciais adicionais, como mostra a próxima seção. Adicione uma chave SSH do repositório ou um token de acesso apenas se as permissões da branch bloquearem esse envio ou para criar o pull request pela API, o que exige permissão de escrita em pull requests. Configure a identidade do bot da equipe, adicione à área de preparação apenas os caminhos de destino conhecidos e .lingo/lock.json e encerre se não houver diferenças nessa área. Use nomes de branch distintos ou reutilize branches de forma planejada para que execuções simultâneas não sobrescrevam umas às outras.
Um commit direto usa as mesmas verificações dos resultados e as mesmas restrições para adicionar arquivos à área de preparação, mas faz push para a branch confiável explicitamente escolhida. A entrega direta na branch padrão elimina a etapa de revisão do pull request de tradução, por isso deve ser uma escolha intencional da política de branches. Confira o resultado na aplicação em qualquer um dos modelos.
Mantenha a chave de API do Lingo.dev separada das credenciais do repositório. Ela deve ficar no ambiente do processo de tradução, nunca em um remoto Git, arquivo versionado ou artefato de saída. Adicione caminhos explícitos à área de preparação em vez de git add . para evitar incluir arquivos não relacionados do executor.
Fazer commit das traduções na branch #
Este pipeline de branch traduz cada alteração que chega a main e faz commit do resultado em main. Ele pressupõe que a tradução inicial de todo o conteúdo já esteja em um commit e que a revisão humana da engine esteja desativada, para que a tradução termine em uma única etapa. Adicione a seção branches desse pipeline sob a mesma chave pipelines do pipeline personalizado. O arquivo 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 encerra com um código diferente de zero quando um destino falha, fazendo a etapa parar antes do commit. Quando não há alterações, ele exibe "Nothing to push", não há diferenças na área de preparação e a etapa termina sem fazer commit.
O Pipelines configura o remoto origin para que uma etapa possa enviar alterações de volta ao próprio repositório sem precisar de uma credencial extra. O bloco auth da etapa dá ao token integrado permissão para executar push no Git. A partir de 30 de abril de 2027, o Bitbucket deixará de conceder essa permissão a etapas sem um bloco auth. Executores auto-hospedados precisam da versão 6.1.0 ou posterior para usar auth. Se uma restrição de branch em main bloquear o push, adicione main como branch de origem nas permissões de escrita do Pipelines dessa restrição ou forneça à etapa uma chave SSH ou um token de acesso com permissão de escrita, conforme descrito no guia do Bitbucket para enviar alterações de volta ao repositório.
A etapa não entra em loop. [skip ci] na mensagem de commit impede o Bitbucket de iniciar um pipeline para o commit de tradução. Sem isso, a próxima execução não encontraria nada para enviar, pois o .lingo/lock.json já incluído no commit registra o novo conteúdo de origem. Se a branch tiver avançado durante a tradução, o Git rejeita o envio; o pipeline do commit mais recente faz a tradução.
Adapte os gatilhos e os caminhos dos pacotes #
Adicione gatilhos automáticos de branch ou pull request somente depois de decidir qual código-fonte pode acessar as credenciais e qual branch pode receber gravações. Um fork pode não ter segredos ou um destino com permissão de gravação; não contorne isso executando o código não confiável dele com credenciais privilegiadas.
Os commits gerados não devem disparar traduções indefinidamente. Selecione os caminhos de origem relevantes e as branches confiáveis, aplique uma regra adequada para commits gerados e mantenha o encerramento quando não houver alterações. É normal 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 artefatos do Pipeline continuam seguindo as regras do Bitbucket para caminhos relativos ao repositório, portanto use caminhos como apps/web/locales/es.json e apps/web/.lingo/lock.json. Alterar o diretório de trabalho da CLI não muda a convenção dos caminhos dos artefatos.
Reprovar pull requests 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 retorna o código de saída 1 quando uma origem foi alterada desde a última tradução, uma origem não tem uma entrada no Lockfile, um arquivo de destino está ausente ou nenhum arquivo de origem corresponde aos padrões de files. Não exige chave de API nem variável de repositório e não grava nada. Fora a telemetria da CLI, desativada por DO_NOT_TRACK=1, não faz chamadas de rede; o exemplo de npx, porém, ainda baixa a CLI do npm antes de executar a verificação. O comando substitui a verificação de --frozen da CLI anterior.
O comando verifica arquivos, não chaves: um destino editado manualmente passa na verificação, e uma chave ausente em um destino existente não é apontada, exceto em catálogos .jsonc do React. Sem .lingo/lock.json, o comando não consegue detectar alterações na origem. Por isso, uma origem alterada ou nunca enviada por push não faz a verificação falhar, e essa limitação é informada em stderr. Inclua no commit o Lockfile gravado por lingo push.
Essa verificação deve ser usada em uma configuração sem o pipeline de branch acima; a tabela abaixo explica o motivo. Adicione uma seção pull-requests sob pipelines, ao lado de custom se mantiver o pipeline manual. Para usar apenas essa verificação, o arquivo 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 é adequada para uma configuração em que as traduções são incluídas em commit junto com a alteração na origem:
| Onde a tradução é executada | Verificar todos os pull requests |
|---|---|
Os desenvolvedores executam lingo push --wait e fazem commit do resultado antes de abrir o pull request | Sim. A verificação reprova um pull request cuja origem foi alterada sem atualizar a tradução. |
O pipeline de branch faz commit em main após a mesclagem | Não. Nesse fluxo, os pull requests de funcionalidades alteram as origens antes da tradução. |
Os hashes de origem são calculados byte a byte. Garanta que o checkout que executou lingo push e o checkout de CI usem as mesmas terminações de linha, por exemplo, com * text=auto eol=lf em .gitattributes. Mantenha também as verificações de recursos da aplicação.
Recupere resultados ausentes ou interrompa o trabalho #
Se faltarem resultados, confira os arquivos de origem selecionados, a referência inicial, a cobertura dos destinos, a disponibilidade das variáveis protegidas, o estado da revisão e as falhas relatadas. Recupere a execução registrada antes de optar por um novo envio. Antes de preencher os destinos ausentes em um projeto existente, conclua, recupere e confira as atualizações normais dos destinos existentes; depois, mantenha a revisão da origem fixa durante o preenchimento. Siga Adicionar um idioma para realizar essa sequência. Use a regeneração forçada somente quando a intenção for substituir o texto aceito selecionado; recuperação de execuções com falha explica como solicitar outra tentativa sem forçar a substituição.
Desative o gatilho do Pipeline para impedir novas tarefas. Ao cancelar o executor, confira separadamente qualquer execução já enviada ao servidor. Ao desativar a receita, remova as variáveis de API não utilizadas e o acesso de gravação do provedor.