Automatizar traduções em CI
Torne a tradução uma etapa repetível de cada lançamento, desde uma revisão conhecida do código-fonte até aos ficheiros inspecionados e às verificações da aplicação.
Um pipeline de lançamento já liga uma revisão do código-fonte a algo que as pessoas podem utilizar. A tradução deve preservar essa ligação. A tarefa tem de saber que conteúdo de origem mudou, obter os ficheiros de destino correspondentes e fornecer à etapa seguinte elementos suficientes para os aceitar ou rejeitar.
Os casos mais difíceis surgem depois do primeiro pedido bem-sucedido: alguém ainda está a rever o texto, um executor deixa de estar disponível ou chega uma nova revisão do texto de origem antes de a tradução de uma revisão anterior estar concluída. Este guia apresenta um processo de CI capaz de lidar com estas situações sem publicar ficheiros desatualizados nem substituir desnecessariamente alterações já aceites. O YAML específico de cada fornecedor está nos exemplos de configuração para GitHub Actions, GitLab, Bitbucket e Buildkite.
Decida em que ponto do lançamento entram as traduções #
Utilize a GitHub App gerida se o workflow que oferece para o repositório for adequado. As alterações no ramo predefinido geram um pedido de integração de traduções; se ativar o processamento de pedidos de integração, as traduções são escritas no ramo do respetivo pedido. A aprovação da execução autoriza o trabalho de tradução; a revisão do conteúdo e a integração ocorrem depois.
Com um executor da CLI, o seu pipeline fica responsável pela submissão, obtenção e entrega. Escolha um destino adequado ao processo de lançamento:
| Destino | Decisão que permite tomar |
|---|---|
| Apenas artefacto | Outra tarefa ou uma pessoa inspeciona os resultados antes de qualquer alteração ao repositório ou ao lançamento. |
| Ramo de tradução e pedido de integração | Rever as alterações traduzidas em separado antes de entrarem no ramo predefinido. |
| Ramo do pedido de integração de origem | Rever o conteúdo de origem e as traduções em conjunto, numa única alteração. |
| Commit direto no ramo predefinido | Entregar sem um pedido de integração de traduções separado, quando a política do ramo o permitir explicitamente. |
Para escrever no repositório, defina um único processo de escrita ativo para cada estado de tradução. Caso contrário, dois executores que trabalhem a partir de revisões diferentes do código-fonte podem competir para fazer commit dos ficheiros e de um Lockfile. Os commits gerados também precisam de regras baseadas no ramo, no caminho ou na sua identificação como commits gerados, para não voltarem a desencadear a tradução repetidamente.
Estabeleça o estado de referência que o executor irá herdar #
Antes de ativar a execução recorrente, traduza localmente um ficheiro de origem para um idioma e execute as verificações de recursos da aplicação. Faça commit da configuração, do ficheiro de destino aceite e de .lingo/lock.json em conjunto. Um checkout limpo deve reproduzir a mesma seleção de ficheiros de origem e a mesma organização dos ficheiros de destino.
Os exemplos dos fornecedores fixam a versão em @lingo.dev/cli@1.21.0. Ao configurar o seu workflow, substitua essa versão pela versão atual da CLI. Para gerir a CLI com as dependências do projeto, instale-a com npm install --save-dev --save-exact @lingo.dev/cli@1.21.0 e faça commit de package.json e package-lock.json. Depois, utilize npm ci e npx --no-install lingo para executar a versão registada no Lockfile.
.lingo/config.json seleciona os idiomas, os padrões de ficheiros e o motor de localização. Configure o acesso à organização e ao motor de localização durante a configuração inicial. Se a tarefa tiver de inicializar ou associar um projeto, utilize as opções explícitas das referências Inicializar e Associar, em vez de deixar uma execução sem supervisão à espera de uma resposta interativa.
Num monorepositório, aceda ao pacote que contém a configuração pretendida antes de executar a CLI. Os padrões posicionais restringem os ficheiros de origem selecionados por essa configuração; não selecionam a configuração de outro pacote. Mantenha juntos o estado e os caminhos dos artefactos de cada pacote configurado de forma independente.
Injete LINGO_API_KEY através do mecanismo de segredos do executor. Funciona sem início de sessão interativo. Execute tarefas com credenciais apenas a partir de código de confiança, pois um ramo pode alterar os scripts de forma a expor a chave. As restrições relativas a variáveis protegidas e a bifurcações devem determinar onde a tarefa é executada; não as remova para permitir que uma tarefa de origem não fidedigna seja concluída.
Submeta o tipo de trabalho adequado #
Para uma primeira tradução de raiz, solicite os ficheiros de destino em falta. Num projeto existente, conclua primeiro as atualizações normais do conteúdo de origem para os destinos existentes e obtenha e inspecione os resultados. Depois, adicione os idiomas em falta e gere os ficheiros em falta, mantendo fixa essa revisão do código-fonte. Siga Adicionar um idioma antes de executar este comando:
lingo push --backfill-missing --waitPara alterações no conteúdo de origem face ao estado de referência estabelecido:
lingo push --waitUm envio inicial simples pode registar o estado do conteúdo de origem sem o traduzir. A operação de preenchimento cria a tarefa para gerar os ficheiros em falta; os envios normais posteriores utilizam as alterações no conteúdo de origem para determinar o trabalho a realizar. Um envio com âmbito limitado ou destinado a gerar ficheiros em falta não é uma solução universal para corrigir chaves em falta em ficheiros de destino existentes.
--wait aguarda a conclusão da execução e transfere os resultados concluídos. Sem esta opção, o envio termina após a submissão. Uma espera por revisão ou uma tarefa separada de obtenção de resultados exige o procedimento de preservação do estado de execução em CI: antes de o executor terminar, conserve o apontador específico, não secreto, guardado no diretório pessoal, o caminho absoluto original da raiz do projeto e o estado correspondente do conteúdo de origem, da configuração, dos ficheiros de destino e do Lockfile. Restaure-os nessa mesma raiz e autentique-se separadamente antes de utilizar lingo pull --dry-run e, em seguida, lingo pull. Se o executor não conseguir recriar o caminho, utilize antes um checkout persistente e autorizado. Nunca arquive credenciais nem a totalidade de ~/.lingo.
Conserve o estado de saída e os resultados comunicados para os destinos. A CLI atual termina com erro quando são comunicadas falhas nos destinos, mas a revisão humana pode deixar uma execução à espera de decisões. Um ficheiro antigo pode continuar a existir enquanto a nova versão está em espera. Conclua a revisão e obtenha o resultado antes de permitir que a tarefa de entrega o publique.
Consulte Enviar e Obter para conhecer o comportamento exato dos comandos. --yes dispensa a confirmação de regeneração forçada; não aprova a revisão humana nem transforma todas as ações pendentes em trabalho concluído.
A CLI não procura atualizações em CI. LINGO_DISABLE_UPDATE_CHECK=1 e LINGO_TELEMETRY_DISABLED=1 permitem controlar explicitamente esse comportamento quando necessário, sem desativar o tráfego de tradução.
Confirme que a etapa seguinte dispõe de ficheiros utilizáveis #
Compare a entrada que espera ver alterada com a revisão do código-fonte. A mera existência de um ficheiro é uma prova pouco sólida quando o checkout já contém um ficheiro de destino mais antigo. Conserve os resultados transferidos e o estado do Lockfile da mesma operação e mantenha claramente assinalados como incompletos os idiomas com falhas ou ainda em espera.
Depois, utilize verificações adequadas ao tipo de recurso:
- Para a extração em React, execute
lingo extract --check,lingo check, a verificação de TypeScript do projeto e a compilação efetiva da aplicação. Cada uma examina uma parte diferente do resultado. - Para recursos nativos, execute a geração ou compilação de recursos da plataforma.
- Para conteúdo estático, faça a análise sintática dos documentos traduzidos e inspecione as ligações, as variáveis e a sintaxe preservada.
- Para fazer falhar um pedido de integração quando as traduções estiverem desatualizadas, execute
lingo check. Não é necessária uma chave de API.
lingo check funciona ao nível dos ficheiros: indica alterações no conteúdo de origem e ficheiros de destino em falta para cada idioma configurado, não chaves em falta dentro de um ficheiro Android, Apple, ARB ou Markdoc existente.
Verifique o significado da tradução no âmbito do processo de aceitação escolhido. Uma compilação pode detetar um recurso malformado e, ainda assim, aceitar uma frase que altera uma condição importante. Quando as verificações e a revisão forem concluídas com êxito, faça commit ou publique apenas os caminhos de saída pretendidos. Preveja uma saída para os casos sem alterações e deixe que as verificações obrigatórias façam a tarefa falhar, em vez de ocultar as falhas com um commit incondicional.
Retome o trabalho registado antes de criar trabalho para o substituir #
Após a interrupção de uma tarefa, recupere o identificador da execução e os resultados dos destinos. Se a tradução tiver sido concluída, obtenha esses resultados antes de submeter outro pedido. Se um ficheiro de destino local tiver mudado durante a espera, resolva o conflito de obtenção com a edição aceite à vista; substituí-la à força pode eliminar precisamente a correção que o workflow deve preservar.
Mantenha o Lockfile durante o diagnóstico. Eliminá-lo altera o estado de referência do conteúdo de origem para a execução seguinte e pode transformar uma recuperação pontual num trabalho diferente. Inspecione as diferenças e repita apenas o que continua incompleto. Recuperar uma execução de localização interrompida explica esta decisão em maior detalhe.
Antes de agendar a tarefa, teste uma espera por revisão humana e uma obtenção de resultados interrompida, além do caso bem-sucedido. A etapa de lançamento deve conservar o último estado aceite e identificar o idioma incompleto, em vez de aceitar qualquer ficheiro que por acaso exista.