Pular para o conteúdo
Pular para o conteúdo

Docs / Guias

Página traduzida automaticamente

Esta página foi traduzida automaticamente, então pode ter erros ou soar um pouco estranha. A versão em inglês é a fonte da verdade. Ler o original em inglês.

Usar a GitHub Action

Execute o verbatra no GitHub Actions com a composite action: traduza a cada push ou barre um pull request, com anotações e resumo do job.

Use a action para executar o verbatra em um job do GitHub Actions e ver o que aconteceu. Ela executa translate, check ou diff com --json; para qualquer outro comando ou flag, como --prune, execute a CLI diretamente (veja Executar o verbatra na CI).

Antes de começar, você precisa de:

  • Uma configuração do verbatra diretamente dentro do diretório em que a action executa (veja Descoberta da configuração).
  • Uma versão exata do @verbatra/cli para fixar, 0.9.3 ou mais recente.
  • Só para translate: a chave de API do seu provedor como segredo do repositório (secret).
  • Actions Runner v2.327.1 ou mais recente, e verbatra/action v1.3.0 ou mais recente, que é o que esta página descreve e de que qa, require-reviewed, sensitive, locales e needs-human precisam.

Adicionar a action a um fluxo de trabalho

A action fica em verbatra/action e no GitHub Marketplace; não há pacote npm. Fixe-a em um SHA de commit, como abaixo, ou use a tag móvel verbatra/action@v1. O caminho antigo mariokreitz/verbatra/packages/github-action não resolve mais.

.github/workflows/translate.yml
name: translate
on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  verbatra:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<commit-sha>
      - uses: verbatra/action@<commit-sha> # a commit on the v1 line
        with:
          version: 0.13.6 # an exact @verbatra/cli release, 0.9.3 or newer
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

A action instala @verbatra/cli e @verbatra/sdk exatamente nessa versão em um diretório temporário, sem tocar nas suas dependências, então o job não precisa de nenhum passo de instalação.

Passar a chave de API do provedor

Mapeie a chave de API dos segredos do repositório para a variável que o seu provedor lê; as variáveis estão em As chaves de API vêm do ambiente. A action não tem entrada para a chave de API, então uma chave de API nunca viaja como entrada nem como argumento da CLI.

Barrar um pull request

Defina command: check para reprovar um pull request cujos arquivos de locale divergiram, ou command: diff para listar também as chaves pendentes. Os dois são somente leitura e não chamam nenhum provedor, então não precisam de chave de API e funcionam em pull requests de forks:

      - uses: verbatra/action@<commit-sha> # a commit on the v1 line
        with:
          version: 0.13.6
          command: check

Verificar a qualidade da tradução

Adicione qa: "true" a command: check para executar verbatra check --qa sobre todas as traduções versionadas, inclusive valores digitados manualmente.

      - uses: verbatra/action@<commit-sha> # a commit on the v1 line
        with:
          version: 0.13.6
          command: check
          qa: "true"
  • Cada ocorrência vira uma anotação com o título verbatra qa: <locale>: um erro para um valor que a barreira de integridade recusaria, um alerta para um motivo de revisão.
  • O passo falha em qualquer ocorrência de erro. Adicione qa-strict: "true" para falhar também em alertas e em plurais incompletos, ou qa-severity: error para relatar só erros. A CLI rejeita os dois juntos.

Exigir traduções revisadas

Adicione require-reviewed: "true" a command: check para executar verbatra check --require-reviewed. O passo falha enquanto uma tradução gerada por máquina não estiver aprovada no verbatra.provenance.json versionado, onde o Studio registra as decisões de revisão (veja Revisar no Studio). Ele continua somente leitura e sem chave de API e se combina com qa.

      - uses: verbatra/action@<commit-sha> # a commit on the v1 line
        with:
          version: 0.13.6
          command: check
          require-reviewed: "true"
  • Cada locale com chaves não aprovadas recebe uma anotação de erro REVIEW_REQUIRED que as nomeia, e o resumo do job acrescenta uma coluna unreviewed.
  • Um verbatra.provenance.json corrompido ou de um verbatra mais novo faz a barreira falhar com uma única anotação REVIEW_STATE_UNREADABLE.

Escolher locales e varrer o código-fonte

Defina locales como uma lista separada por vírgulas, como de,fr, para limitar qualquer comando a esses locales.

      - uses: verbatra/action@<commit-sha> # a commit on the v1 line
        with:
          version: 0.13.6
          command: check
          locales: "de,fr"

Conteúdo sensível

Adicione sensitive: "true" a command: check para executar verbatra check --sensitive. O passo falha quando o arquivo de origem ou o glossário contém conteúdo que um detector ou padrão de sensitiveData reconhece, como e-mails, chaves de API ou números de cartão, e anota cada chave afetada sem imprimir o trecho encontrado. Uma version mais antiga, ou uma pré-versão 0.12.0-next.*, faz o passo falhar antes de qualquer instalação.

Modo somente humano

Com provider: { id: "none" } (veja Trabalhar sem tradução automática), translate sai com 3 quando deixa chaves para uma pessoa. A action trata isso como trabalho a entregar, não como falha: o passo passa, cada locale afetado recebe um alerta NEEDS_HUMAN, o resumo do job lista as chaves e a saída needs-human é "true". Use essa saída em uma condição:

      - uses: verbatra/action@<commit-sha> # a commit on the v1 line
        id: verbatra
        with:
          version: 0.13.6
      - if: steps.verbatra.outputs.needs-human == 'true'
        run: echo "Some keys need a human translation; see the job summary."

Só translate recebe esse tratamento; check e diff nunca saem com 3, então uma falha deles ainda faz o passo falhar.

Descoberta da configuração

Com config-path vazio, a action exige um arquivo de configuração reconhecido diretamente dentro de working-directory (por padrão, a raiz do repositório). Ela nunca procura em um diretório pai, então em um monorepo aponte working-directory para o app e mantenha a configuração dele ali:

      with:
        version: 0.13.6
        working-directory: apps/docs

Se nenhuma configuração for encontrada, o passo falha antes de instalar a CLI e nomeia o diretório que verificou. Para carregar uma configuração de outro lugar, defina config-path: um caminho relativo é resolvido a partir de working-directory.

Persistir as traduções

translate grava os arquivos de locale atualizados no checkout do runner; a action nunca faz commit. Adicione um passo seu que faça commit e push, ou abra um pull request, e conceda contents: write ou pull-requests: write só a esse job.

Entradas

EntradaPadrãoEfeito
versionobrigatórioversão exata do @verbatra/cli a executar, 0.9.3 ou mais recente; uma dist-tag, um intervalo ou um prefixo ^/~ faz o passo falhar
commandtranslatetranslate, check ou diff; qualquer outro valor faz o passo falhar
config-path""arquivo de configuração a carregar (--config); relativo a working-directory
working-directory""diretório em que executar (--cwd); a raiz do repositório quando vazio
dry-run"false""true" faz uma pré-visualização sem chamar um provedor nem gravar (--dry-run); só translate
qa"false""true" adiciona a verificação de qualidade (--qa); só check
qa-severity""menor severidade a relatar, error ou warning (--severity); exige qa
qa-strict"false""true" também falha em alertas (--strict); exige qa
require-reviewed"false""true" também falha em traduções geradas por máquina não aprovadas (--require-reviewed); só check
sensitive"false""true" adiciona a varredura de conteúdo sensível (--sensitive); só check
locales""locales de destino, separados por vírgulas, aos quais limitar a execução (--locales)
node-version"24"versão do Node.js a configurar. CLI 0.13.0+: 22.22.0+ no 22, 24+ (action v1.4.0: só versões principais pares); CLI 0.12.x: `^22.18.0

As entradas booleanas aceitam só "true" ou "false". Um booleano inválido, ou uma entrada sem o comando ou o qa de que precisa, faz o passo falhar com o código 1 antes da instalação da CLI. A CLI rejeita um qa-severity desconhecido, e qa-severity: error com qa-strict, com o código 2, depois da instalação.

Saídas

SaídaValor
needs-human"true" quando translate saiu com 3 e deixou chaves para uma pessoa; caso contrário, "false"

O que uma execução mostra

  • Anotações. Em translate com código de saída 1, cada locale com falha ou parcial vira uma anotação de erro com o título verbatra: <locale>. Em check ou diff, cada locale divergente recebe uma com o título verbatra check: <locale> ou verbatra diff: <locale>. Todas elas são associadas ao arquivo desse locale quando a action consegue encontrá-lo. A anotação LOCALE_PARTIAL de um locale parcial nomeia as chaves retidas, agrupadas por causa. Todo check adiciona um alerta PLURAL_CATEGORIES_INCOMPLETE por locale cujos plurais não têm uma categoria do CLDR que o idioma usa. Com sensitive, cada chave sinalizada recebe uma anotação de erro SENSITIVE_CONTENT e uma linha no resumo. Uma execução que falha como um todo recebe uma anotação verbatra com o código de erro, a causa como (cause: X) e uma dica Next step: quando a CLI as fornece. O GitHub mostra no máximo 10 anotações por severidade, então a action as ordena assim: divergência, revisão, erros de qualidade, alertas, e acrescenta um aviso que conta as demais.
  • Resumo do job. Uma linha por locale com as contagens do comando que foi executado, uma linha agregada e os locales parciais e com falha. Com qa, ele acrescenta uma tabela de ocorrências com até 1000 ocorrências; plurais incompletos ganham uma seção própria.
  • Status de saída. A action emite primeiro as anotações e o resumo e depois sai com o próprio código de saída da CLI (veja Códigos de saída), exceto que um translate com saída 3 passa e uma falha antes de a CLI executar (sem diretório de trabalho, sem configuração, instalação com falha) sai com 1; uma entrada recusada recebe um único ::error:: e nenhum resumo.

Segurança

Fixe as duas referências: uses: em um SHA de commit e version em uma versão exata (a atual no npm); a action rejeita qualquer coisa que possa resolver para latest. As entradas chegam à CLI como um array de argumentos entre aspas, nunca inseridas em texto de shell.

Veja também

Editar no GitHub

Nesta página