← Voltar ao blog
A git diff view showing a locale file with three changed keys highlighted, and only those three keys being sent to the translation API below.

Você não precisa traduzir tudo novamente: como a tradução delta funciona no CI

By Robert M

Você não precisa re-translatear tudo: como a tradução delta funciona no CI

Uma vez que você tenha a tradução automatizada integrada ao seu pipeline de CI, uma pergunta natural surge rapidamente: isso re-translatea o arquivo de localidade inteiro toda vez que alguém faz um push?

Sem o modo delta, sim. Cada push que toca seu arquivo de localidade fonte envia tudo para a API, cada chave, cada string, tenha ela mudado ou não. Para um projeto pequeno no início, isso é aceitável. Para um projeto maduro com centenas de chaves de tradução em 10 ou 20 idiomas, você está gastando tokens em strings que não mudaram desde a última execução e recebendo de volta uma saída idêntica pelo privilégio.

A tradução delta resolve isso. Em vez de enviar o arquivo completo, a Action compara seu arquivo fonte atual com uma linha de base armazenada, identifica apenas as chaves que foram adicionadas ou modificadas, e envia apenas essas para a API. A saída para chaves não alteradas é retirada dos arquivos traduzidos existentes. O uso de tokens cai para corresponder ao trabalho real realizado.

Como a linha de base funciona

Quando o modo delta roda pela primeira vez, ou quando você força uma atualização completa, a Action traduz o arquivo fonte completo e armazena uma representação JSON plana dele como um arquivo de linha de base no seu repositório. Nas execuções subsequentes, a Action carrega essa linha de base, compara com o arquivo fonte atual e constrói uma carga contendo apenas as chaves alteradas.

Para arquivos JSON de localidade, a linha de base é armazenada como .polylingo-baseline.json no seu diretório de mensagens. Para arquivos YAML de localidade, é .polylingo-yaml-baseline.json no seu diretório de locais. Para arquivos PHP lang do Laravel, é .polylingo-laravel-php-baseline.json no seu diretório lang.

A linha de base é comitada junto com seus arquivos traduzidos para que viaje com o repositório. Qualquer desenvolvedor que clona o repo obtém a mesma linha de base com a qual o pipeline está trabalhando.

O que conta como uma mudança

O diff opera na representação plana das chaves do seu arquivo fonte. Estruturas aninhadas são achatadas para chaves em notação de ponto antes da comparação:

{
  "nav.home": "Home",
  "nav.about": "Sobre nós",
  "hero.title": "Bem-vindo à nossa plataforma",
  "hero.cta": "Comece agora"
}

Uma chave é incluída na carga delta se:

  • Ela existe no arquivo fonte atual mas não na linha de base (chave nova)
  • Ela existe em ambos mas o valor mudou (chave modificada) Chaves que existem na linha de base mas não no arquivo fonte atual (chaves deletadas) são removidas automaticamente dos arquivos traduzidos. Chaves idênticas em ambos são completamente ignoradas e suas traduções existentes permanecem no lugar.

Como isso funciona na prática

Suponha que você tenha um projeto Next.js com 200 chaves de tradução em messages/en.json, já traduzidas em 12 idiomas. Um desenvolvedor atualiza o texto da seção hero e adiciona duas novas chaves para um anúncio de recurso. Isso são 4 chaves alteradas de 200.

Sem o modo delta, o pipeline envia todas as 200 chaves multiplicadas por 12 idiomas a cada push. Com o modo delta, ele envia 4 chaves. O uso de tokens para essa execução é cerca de 2% do custo de uma tradução completa. O pipeline também é mais rápido porque há menos para enviar e menos para esperar.

Ao longo de um mês de desenvolvimento regular, a economia se acumula significativamente. A maioria dos pushes toca apenas algumas strings. A retradução completa só acontece quando você adiciona um novo idioma ou redefine explicitamente a linha de base.

As três Actions PolyLingo do GitHub

O modo delta está disponível em todas as três Actions de tradução PolyLingo. Cada uma é construída para um tipo específico de conteúdo e estrutura de projeto.

translateAction — JSON e Markdown

A Action original. Lida com arquivos JSON planos de localidade no estilo next-intl e i18next, com uma passagem opcional de documentação Markdown via API de jobs assíncronos para arquivos maiores.

- uses: UsePolyLingo/translate-action@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    source_file: messages/en.json
    locales: fr,de,es,ja,zh
    delta: true
    commit: true
    commit_message: "chore(i18n): sincronizar traduções"

Linha de base delta: messages/.polylingo-baseline.json

github.com/UsePolyLingo/translateAction — Ver no Marketplace

translate-action-yaml — arquivos YAML de localidade

Para projetos que usam arquivos YAML aninhados de localidade: Rails i18n, Vue i18n e qualquer outro framework que use o formato YAML. A Action lida automaticamente com a convenção Rails de uma chave raiz de localidade — en.yml tem uma chave raiz en:, e cada arquivo de saída recebe a chave correta do local de destino (fr:, de: etc).

Como a API PolyLingo trabalha nativamente com JSON, a Action achata o YAML aninhado para JSON em notação de ponto antes de enviar, traduz, depois reconstrói a estrutura aninhada e escreve saída YAML válida. Uma ressalva da v1 que vale saber: chaves que contêm pontos naturalmente não são suportadas, pois conflitam com o achatamento em notação de ponto.

- uses: UsePolyLingo/translate-action-yaml@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    locales_dir: config/locales
    source_file: config/locales/en.yml
    locales: fr,de,es,ja
    delta: true
    commit: true

Linha de base delta: config/locales/.polylingo-yaml-baseline.json

github.com/UsePolyLingo/translate-action-yaml — Ver no Marketplace

translate-action-laravel — arquivos lang do Laravel

Para projetos Laravel que usam arquivos de tradução JSON (lang/en.json, suportando estruturas aninhadas e planas no estilo Laravel 9+) ou arquivos PHP array lang (lang/en/*.php). A Action detecta automaticamente qual formato seu projeto usa via php_format: auto — verifica lang/en.json primeiro e recua para arquivos PHP array se não encontrar.

Para arquivos PHP, ela chama o CLI PHP para ler os arquivos fonte e serializa a saída traduzida de volta para sintaxe válida de array PHP em JavaScript, sem dependências adicionais. Os runners ubuntu-latest hospedados no GitHub incluem PHP 8.x por padrão, então não é necessário passo extra de configuração. PHP 7.4 ou superior é requerido.

Uma ressalva da v1: chaves contendo pontos não são suportadas no modo PHP devido à estratégia de achatamento em notação de ponto.

- uses: UsePolyLingo/translate-action-laravel@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    lang_dir: lang
    source_locale: en
    locales: fr,de,es,pt,nl
    php_format: auto
    delta: true
    open_pr: true

Linha de base delta: lang/.polylingo-laravel-json-baseline.json ou lang/.polylingo-laravel-php-baseline.json dependendo do formato.

github.com/UsePolyLingo/translate-action-laravel — Ver no Marketplace

Modo PR vs modo commit

Todas as três Actions suportam dois modos de saída.

Modo commit (commit: true) escreve os arquivos traduzidos e os comita diretamente no branch atual. Configuração simples, bom para equipes que tratam a tradução como um processo automatizado que não precisa de revisão.

Modo PR (open_pr: true) cria um novo branch (polylingo/yaml-<sha>, polylingo/laravel-<sha> etc), escreve os arquivos traduzidos lá e abre um pull request contra seu branch base. Melhor para equipes que querem uma etapa de revisão humana antes da fusão do conteúdo traduzido, ou para projetos onde a qualidade da tradução afeta diretamente a experiência do usuário.

Quando ambos estão configurados, o modo PR prevalece.

O modo PR requer pull-requests: write nas permissões do seu workflow:

permissions:
  contents: write
  pull-requests: write

Forçando uma atualização completa

O modo delta compara contra a linha de base armazenada. Se você quiser retraduzir tudo independentemente do que a linha de base mostra, defina delta: false. Isso também atualiza a linha de base para corresponder ao arquivo fonte atual, então execuções delta subsequentes começam do novo estado.

Uma atualização completa é útil quando você adiciona um novo idioma alvo, quando quer aproveitar melhorias de qualidade de tradução em uma nova versão do modelo, ou quando a linha de base se desviou da realidade por qualquer motivo.

- uses: UsePolyLingo/translate-action-yaml@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    locales_dir: config/locales
    locales: fr,de,es,ja,zh,ko,ar
    delta: false  # atualização completa, atualiza linha de base
    commit: true

Saídas para etapas subsequentes

Todas as três Actions expõem as mesmas saídas para que você possa usá-las em etapas de workflow posteriores:

- uses: UsePolyLingo/translate-action@v1
  id: translate
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    source_file: messages/en.json
    locales: fr,de,es
    delta: true
    commit: true

- name: Logar estatísticas de tradução
  run: |
    echo "Idiomas traduzidos: ${{ steps.translate.outputs.locales_translated }}"
    echo "Arquivos alterados: ${{ steps.translate.outputs.files_changed }}"
    echo "Tokens usados: ${{ steps.translate.outputs.tokens_used }}"

Cada execução também escreve uma tabela resumo no sumário da etapa do GitHub Actions para que você possa ver o uso de tokens e resultados da tradução sem precisar vasculhar logs.

Começando

Todas as três Actions estão disponíveis no GitHub Marketplace. Você precisará de uma chave API PolyLingo, disponível gratuitamente em usepolylingo.com. O nível gratuito inclui 50.000 tokens por mês. Com o modo delta ativado, a maioria dos projetos ficará bem dentro disso em pushes de desenvolvimento rotineiros.

Adicione sua chave API como um segredo do repositório (POLYLINGO_API_KEY) e insira a Action relevante no seu workflow. A primeira execução faz uma tradução completa e define a linha de base. Cada execução depois disso traduz apenas o que mudou.