Referência / CLI
Página traduzida automaticamente
verbatra check
Relata chaves ausentes ou obsoletas por locale sem gravar arquivos nem chamar um provedor, e faz a CI falhar enquanto algum locale estiver fora de sincronia.
Relata, por locale de destino, quantas chaves estão ausentes, obsoletas ou em dia, e termina com um código de saída no qual um passo da CI pode se basear. O check executa a leitura e o diff que o verbatra translate executa antes de chamar um provedor, e para aí: nenhuma chamada a provedor, nenhum arquivo gravado, nenhuma chave de API necessária.
Sinopse
verbatra check [flags]Exemplos
# faz o build falhar quando as traduções divergem
verbatra check
# status legível por máquina para dois locales
verbatra check --locales de,fr --json
# lista também as strings de origem traduzidas de mais de um jeito
verbatra check --consistency
# falha com placeholders, marcação e ICU quebrados, e também com alertas
verbatra check --qa --strict
# falha enquanto traduções automáticas esperam aprovação
verbatra check --require-reviewed
# falha com e-mails, chaves de API ou números de cartão na origem
verbatra check --sensitive
# verifica o único arquivo que um editor ou agente acabou de alterar
verbatra check --file locales/de.json --jsonFlags
| Flag | Argumento | Padrão | Efeito |
|---|---|---|---|
--locales | <list> | todos os destinos configurados | verifica só este subconjunto separado por vírgulas; um locale não configurado falha com UNKNOWN_ e uma lista vazia com INVALID_, ambos com código de saída 2 |
--consistency | nenhum | desativado | lista também as strings de origem traduzidas de mais de um jeito; só relatório, veja Relatório de consistência |
--qa | nenhum | desativado | executa também a verificação de qualidade sobre toda tradução versionada; código de saída 1 em caso de erro |
--file | <path> | desativado | verifica só este arquivo de locale, veja Um único arquivo; não com --locales, --consistency, --require-reviewed nem --sensitive |
--severity | error ou warning | warning | com --qa ou --file, a menor severidade a relatar |
--strict | nenhum | desativado | com --qa ou --file, termina também com código 1 em um alerta ou em um plural incompleto; não com --severity error |
--require-reviewed | nenhum | desativado | termina também com código 1 enquanto uma tradução escrita por máquina não estiver aprovada |
--sensitive | nenhum | desativado | varre também o arquivo de origem e o glossário em busca de conteúdo sensível; código de saída 1 em qualquer ocorrência |
Aceita também as flags globais --cwd, --config e --json.
Uma chave está ausente quando a origem a tem e o destino não, e obsoleta quando a string de origem dela mudou desde a última tradução. Um locale está sincronizado quando não tem nenhuma das duas. Para as listas de chaves por trás das contagens, use o verbatra diff.
Comportamento
Saída em texto simples:
verbatra check
de: 3 missing, 1 stale (1 protected), 38 up-to-date (out of sync)
fr: 0 missing, 0 stale, 42 up-to-date (in sync)
out of sync (run verbatra translate to update)Relatório de consistência
--consistency lista, por locale de destino, toda string de origem que duas ou mais chaves traduzem de forma diferente: a origem, cada tradução distinta e as chaves que a contêm. Ele nunca altera o código de saída, um valor ou a fila de revisão. As regras de comparação:
- Os valores são comparados depois da normalização Unicode NFC, com
\r\nconvertido em\ne o espaço em branco externo removido. O espaço interno e a diferença entre maiúsculas e minúsculas contam. - Só as chaves em dia são comparadas, e uma tradução igual à própria origem fica a cargo de
EQUALS_.SOURCE - Chaves cuja descrição, significado, indicador de plural ou
msgctxtdo gettext diferem nunca são agrupadas. - As formas de plural são comparadas forma por forma: as formas
oneeotherde uma mesma chave nunca são agrupadas entre si.
Falsos positivos conhecidos: variantes de contexto do i18next (invite_, invite_), entradas gettext marcadas com #, fuzzy, chaves no estilo de plural em um formato sem plurais (yaml, ngx-translate-json, xliff, properties, ini, resx) e as formas de plural de um formato custom:. Dê a essas chaves uma descrição ou um significado diferente, ou ignore a ocorrência. Com --json, cada locale traz inconsistencies: { source, context?, description?, meaning?, isPlural, pluralForm?, translations: [{ value, keys }] }[].
Chaves protegidas
Uma chave obsoleta que uma pessoa escreveu, importou ou alterou fora do verbatra, ou uma chave que bate com pinnedKeys, fica para uma pessoa resolver: o translate não a traduz (veja Manter traduções humanas). O check ainda a conta e mostra a parcela protegida, por exemplo 2 stale (1 protected). O --json a traz como protected em cada locale; quando o verbatra.provenance.json está ilegível, só as chaves fixadas contam.
Categorias de plural
Todo check lista os plurais que não têm uma categoria de plural CLDR usada pelo idioma de destino, como um <plurals> do Android em polonês só com one e other:
plural categories (warning: exit 1 only under --qa --strict)
pl: 2 plurals missing CLDR categories
cart {count} plural: missing few, many
files: missing few, manyAs categorias vêm das regras CLDR embutidas no Node.js (veja Plurais). Formatos verificados:
| Formato | Formas de plural lidas |
|---|---|
i18next-json | os sufixos de chave _, _, ..., e os plurais _ comparados com as regras ordinais |
android-xml | as entradas <item quantity> de cada <plurals> |
apple-strings | as regras de plural do .stringsdict ao lado do arquivo .strings |
apple-xcstrings | as categorias de variations.plural de cada locale |
next-intl-json, arb | todo plural e selectordinal ICU, inclusive os aninhados |
other é sempre obrigatória. Um ramo exato como =1 nunca substitui uma categoria, os ramos do select nunca são verificados, e só é verificado um plural do qual o destino tem pelo menos uma forma. É um alerta: um check simples mantém seu código de saída, e --qa --strict falha por ele. O verbatra doctor relata os mesmos plurais. Com --json, cada locale traz incompletePlurals, ordenado por chave:
interface IncompletePlural {
code: "PLURAL_CATEGORIES_INCOMPLETE";
key: string; // chave base, ou a chave da mensagem ICU
argument?: string; // o argumento do plural ICU, como count
ruleType: "cardinal" | "ordinal";
missing: ("zero" | "one" | "two" | "few" | "many" | "other")[]; // na ordem do CLDR
}Verificação de qualidade
--qa executa, sobre os valores que já estão nos seus arquivos de locale, obsoletos ou não, as verificações que uma execução de translate aplica à saída do provedor, inclusive as formas de plural extras de que o idioma de destino precisa. As ocorrências têm duas severidades:
- error: o valor falha na barreira de integridade com
placeholder,markup,icu,degenerateouempty. Os detalhes listam os placeholders removidos como-{{name}}e os adicionados como+{{nom}}. - warning: o valor carrega um motivo de revisão calculado a partir do valor, da origem dele e da sua configuração (glossário,
maxLength), portanto nenhum que dependa do provedor ou do cache; paraFOREIGN_, osPLACEHOLDER_ CHANGED detailsda ocorrência nomeiam cada placeholder removido ou alterado, como-{name}. Um valor com um erro não recebe alertas.
qa: 1 error, 1 warning
de: 1 error, 1 warning in 42 values checked
greeting: error placeholder (-{{name}}, +{{nme}})
title: warning EQUALS_SOURCEAs chaves órfãs e as ausentes são ignoradas, e as chaves de origem que não são ICU válido são listadas uma vez em invalidSourceKeys. Valores protegidos, fixados e rejeitados são verificados como qualquer outro. Com --json, result.qa traz os totais e cada locale traz o seu próprio qa:
interface CheckQaSummary { errors: number; warnings: number; invalidSourceKeys: string[]; limitsNotice?: { code: "LIMITS_FILE_IGNORED"; message: string } }
interface LocaleQaReport { checked: number; errors: number; warnings: number; findings: QaFinding[] }
type QaFinding =
| { key: string; severity: "error"; reason: "placeholder" | "markup" | "icu" | "degenerate" | "empty"; details?: string[] }
| { key: string; severity: "warning"; reason: string; details?: string[] }; // um dos motivos de revisão acimaExigir traduções revisadas
--require-reviewed falha com código de saída 1 enquanto um valor cujo origin (como o valor foi produzido) é machine, memory, fuzzy ou agent não estiver aprovado no verbatra.provenance.json versionado, onde o Studio e as ferramentas do MCP registram as decisões (veja Revisar no Studio e verbatra mcp). Uma aprovação anterior à mudança do texto de origem, ou anterior à mudança do valor, não conta.
review: failed [REVIEW_REQUIRED] 2 machine-written translations not approved
de: 2 unreviewed: checkout.title, checkout.total
approve or reject them in verbatra studio's Review queue, then commit verbatra.provenance.jsonCom --json, result.review é { reviewed, unreviewed, code? }, em que code é REVIEW_, ou REVIEW_ quando o arquivo de procedência está corrompido ou vem de um verbatra mais novo (a barreira então falha). Cada locale traz review.unreviewed, as chaves na ordem da origem.
Conteúdo sensível
--sensitive executa a varredura da proteção de conteúdo sensível sobre cada chave de origem (nome da chave, valor, descrição, significado) e sobre o glossário de cada locale verificado, com os detectores, os padrões e a lista de permissões de sensitiveData (detectores padrão se o bloco não existir), seja qual for o seu mode e o provedor, inclusive none: os valores ainda saem da máquina por entregas de exportação, XLIFF e TMX. Ele relata chaves e detectores, nunca o texto encontrado fora de um nome de chave, e falha com código de saída 1 em qualquer ocorrência.
O detector email ignora domínios de exemplo reservados, então teste com um endereço de aparência real.
sensitive: 1 key and 0 glossary terms hold content that looks sensitive
support.contact: email in value
remove it, list it in sensitiveData.allow, or turn the detector off in sensitiveData.detectorsCom --json, result.sensitive é { findings, glossaryTerms }, cada ocorrência { key, fields, detectors }; detectors pode conter pattern-timeout-<n>.
Um único arquivo
--file <path> verifica um único arquivo de locale, para hooks de editor e de agente depois de uma edição. Ele lê esse arquivo, o verbatra.limits.json (se estiver inutilizável, é ignorado com um aviso no stderr, como em --qa; o doctor nomeia o problema) e, para um locale de destino, o arquivo de origem, nada mais. O caminho é resolvido a partir de --cwd e comparado com files.pattern para achar o locale dele.
- Um arquivo que não pode ser analisado vira um único erro
syntaxcom o código do adaptador (INVALID_,JSON INVALID_, ...) e a linha e a coluna quando o parser informa uma posição.YAML - Um arquivo de destino é verificado como em
--qa, inclusive as categorias de plural; um arquivo de origem, só pela sintaxe. Um catálogoapple-xcstringsé verificado para cada locale de destino. - Um caminho que não é o arquivo de nenhum locale configurado falha com
NOT_e código de saídaA_ LOCALE_ FILE 2.
Com --json, o result reutiliza o relatório de --qa, então um hook analisa uma única estrutura:
interface CheckFileSummary {
file: string; // relativo à raiz do projeto
role: "source" | "target" | "catalogue";
locales: {
locale: string;
incompletePlurals: IncompletePlural[];
qa: { checked: number; errors: number; warnings: number; findings: (QaFinding | QaSyntaxFinding)[] };
}[];
qa: CheckQaSummary;
}
interface QaSyntaxFinding {
severity: "error"; reason: "syntax"; code: string; message: string;
line?: number; column?: number; // quando o parser informa uma posição, contada a partir de 1
}Chaves ausentes e obsoletas não fazem parte da verificação de um arquivo.
Saída JSON
Schema: o check-envelope.json valida o envelope inteiro (o objeto JSON da resposta); Schemas lista os outros.
--json imprime um envelope cujo result é o documento de status. Sem --qa, --require-reviewed nem --sensitive, inSync é verdadeiro exatamente quando o comando termina com código 0:
interface CheckSummary {
inSync: boolean;
locales: LocaleCheckSummary[];
qa?: CheckQaSummary; // só com --qa
review?: CheckReviewSummary; // só com --require-reviewed
sensitive?: CheckSensitiveSummary; // só com --sensitive
}
interface LocaleCheckSummary {
locale: string;
missing: number; // na origem, ausente do destino
stale: number; // origem alterada desde a última tradução
upToDate: number;
inSync: boolean; // missing === 0 && stale === 0
emptySource?: number; // valor de origem vazio: nunca ausente nem obsoleto
provenance?: ProvenanceSummary; // contagens por procedência e estado de revisão
protected?: number;
incompletePlurals?: IncompletePlural[];
inconsistencies?: InconsistencyGroup[]; // só com --consistency
qa?: LocaleQaReport; // só com --qa
review?: LocaleReviewReport; // só com --require-reviewed
}Uma chave de origem cujo valor está vazio ou só tem espaço em branco, como uma que o extract adicionou sem valor padrão, ainda não tem nada a traduzir: ela é contada em emptySource em vez de missing ou stale, nunca deixa um locale fora de sincronia, e a saída no terminal informa a contagem.
Retorno no terminal
O check mostra verbatra: checking the locales... done (0.1s) no stderr, ou verbatra: checking locales/de.json... com --file. --quiet o suprime. Veja Saída no terminal.
Códigos de saída
| Código | Significado |
|---|---|
0 | sincronizado, e nenhuma ocorrência que as flags usadas transformem em falha |
1 | um locale tem uma chave ausente ou obsoleta, --qa ou --file encontrou um erro (ou um alerta ou plural incompleto com --strict), --require-reviewed encontrou uma tradução não aprovada, ou --sensitive encontrou conteúdo sensível |
2 | não foi possível executar: um erro que afeta a execução inteira, como SOURCE_ ou NOT_, ou um erro de uso, como INVALID_, INVALID_ ou INVALID_ para um --file vazio ou combinado com --locales, --consistency, --require-reviewed ou --sensitive |
O código de saída 1 significa que o resultado não está limpo, não que a execução falhou; o relatório ainda é impresso. Em um projeto cujo arquivo de origem ainda não está no lugar, o verbatra doctor ainda relata. Veja Códigos de saída para o contrato.
Veja também
- O
verbatra difflista as chaves exatas por trás destas contagens. - Executar o verbatra na CI mostra o
checkcomo barreira contra divergências. - O arquivo de lock e a procedência explica como a obsolescência é detectada.