Referência / CLI
Página traduzida automaticamente
verbatra diff
Mostra as chaves que uma execução adicionaria ou retraduziria por locale e as chaves órfãs que ela deixaria, sem gravar arquivos nem chamar um provedor.
Lista as chaves pendentes exatas por locale de destino: as que uma execução adicionaria, as que ela retraduziria e as que agora são órfãs. O diff executa a mesma leitura e a mesma comparação do verbatra translate e para: sem chamada ao provedor, sem arquivo gravado, sem atualização do arquivo de lock (veja O arquivo de lock e a procedência) e sem precisar de chave de API.
Sinopse
verbatra diff [flags]Exemplos
# listar as chaves pendentes por locale (código de saída 1 se houver alguma)
verbatra diff
# só os locales alemão e francês
verbatra diff --locales de,fr
# listas de chaves legíveis por máquina para ferramentas ou um comentário no pull request
verbatra diff --json
# listar também as chaves de origem que o seu código não nomeia mais
verbatra diff --unusedFlags
| Flag | Argumento | Padrão | Efeito |
|---|---|---|---|
--locales | <list> | todos os destinos configurados | compara 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 |
--unused | nenhum | desativado | lista também as chaves do locale de origem que nenhum ponto de chamada sob os diretórios-raiz do código-fonte (roots) do bloco extract nomeia; veja Chaves de origem não usadas |
Aceita também as Flags globais --cwd, --config e --json.
Comportamento
Chaves pendentes e órfãs
Cada locale lista quatro tipos de chave:
| Lista | Significado |
|---|---|
missing (exibido como add) | na origem, ausente do destino: uma execução a adicionaria |
changed (exibido como re-translate) | o texto de origem mudou desde a última tradução: uma execução a retraduziria |
orphaned | no destino, ausente da origem: só é relatada |
emptySource (exibido como empty source) | o valor de origem está vazio ou só tem espaços em branco: não há nada a traduzir até você escrevê-lo, nunca fica pendente |
Um locale tem alterações pendentes quando tem pelo menos uma chave ausente ou alterada. As chaves órfãs nunca contam como pendentes, porque uma execução padrão as deixa no lugar; só o verbatra translate --prune as remove. Onde o verbatra check dá as contagens, o diff dá as listas de chaves.
Chaves de origem não usadas
O --unused responde a uma pergunta diferente da de orphaned: quais chaves do arquivo de locale de origem o seu app não nomeia mais? Ele varre os roots do bloco extract com o leitor que o verbatra extract usa e lista toda chave de origem que nenhuma referência estática nomeia. As duas listas nunca são mescladas. A varredura continua somente leitura: nada é removido e nenhuma chave de API é lida. Excluir uma chave é decisão sua.
A varredura modela o runtime do i18next. Contam como referência:
- uma chamada
t(...),$t(...)ou<object>.t(...)em qualquer lugar sob os diretórios-raiz, também por um alias comoconst { t: translate } = useTranslation(),const tr = i18n.t,t.bind(i18n)oui18n.getFixedT(...); - um
keyPrefixestático ou o terceiro argumento degetFixedT, que cobre também a forma com prefixo de toda chave estática naquele arquivo, e umi18nKeyestático emTransou em um objeto; - uma chave qualificada por namespace (
common:nav.homecobre tambémnav.home), uma chave em linguagem natural e cada entrada de um array estático de chaves; - uma variante de plural ou de contexto de uma chave referenciada (
t("items", { count })cobreitems_eone items_) e toda chave sob um pai referenciado.other
As chaves são comparadas na codificação própria do formato do catálogo, então uma chave JSON plana com pontos, uma entrada de plural ou msgctxt do gettext e uma entrada <plurals> do Android correspondem todas à chave que o seu código nomeia. Um template literal com início estático, como t(`nav.${page}`), lista as chaves sob nav. como possiblyDynamic, separadas de unused, e nunca faz a execução falhar.
O relatório traz um status: complete (toda chave alcançável foi delimitada, então unused é confiável), unreliable (uma chave listada ainda pode estar em uso; unreliableBecause nomeia cada motivo com a sua contagem e os seus pontos) ou not-run (nada é listado; reason diz por quê):
| Motivo | status | Quando |
|---|---|---|
dynamic-keys | unreliable | uma chave sem parte estática: t(key), um template literal sem início estático ou uma concatenação |
dynamic-key-prefix | unreliable | um prefixo de keyPrefix ou de getFixedT que não é uma string estática |
trans-without-key | unreliable | um elemento Trans sem um i18nKey estático |
aliased-translate-function | unreliable | t atribuído a qualquer coisa que não seja uma variável simples, como this.tr = t |
translate-function-escapes | unreliable | uma função de tradução usada em qualquer lugar que não seja uma chamada direta, o seu binding, um alias local, t={t} em Trans ou Translation, ou um array de dependências de hook: renderRow(t), { t }, return t, export default t |
unrecognised-translate-source | unreliable | um t ou $t obtido de um jeito que a varredura não modela, como um hook wrapper que retorna useTranslation(...), opções de hook montadas com um spread ou o resultado exportado de um getFixedT |
template-files-not-scanned | unreliable | arquivos .vue, .svelte, .html, .htm, .astro, .hbs, .handlebars, .ejs, .pug, .njk, .liquid ou .mdx sob os diretórios-raiz (os 20 primeiros são listados, todos são contados) |
incomplete-scan | unreliable | um arquivo grande demais, ilegível ou que não pode ser lido até o fim (também um elemento JSX sem fechamento ou uma string entre aspas que corre até o fim da linha), ou um diretório que não pode ser listado |
EXTRACT_ | not-run | nenhum bloco extract |
EXTRACT_ | not-run | o sistema de arquivos de quem chama pelo SDK não consegue listar diretórios |
FRAMEWORK_ | not-run | o formato é next-intl-json, vue-i18n-json ou ngx-translate-json, cujos runtimes a varredura não modela |
NO_ | not-run | não há nenhum arquivo de origem sob os diretórios-raiz |
NO_ | not-run | os arquivos varridos não nomeiam nenhuma chave e não têm nenhum ponto de chave dinâmica enquanto o catálogo não está vazio, o que costuma significar que os diretórios-raiz não alcançam o seu código |
As formas reconhecidas de obter a função de tradução são useTranslation(...) desestruturado em um binding local, não exportado, com argumentos estáticos; um i18n.getFixedT(...) local com argumentos estáticos; uma chamada direta em um membro t (i18n.t("key"), this.props.t("key")) e o seu alias local; <Translation>{(t) => ...}</Translation>; withTranslation("ns")(Component) com props.t(...); e import { t } from "i18next". Toda variável ou membro chamado t ou $t é avaliado, então um frame.t + 1 sem relação pode tornar um relatório não confiável. Em arquivos .tsx, .jsx e .js, o texto JSX e os valores de atributo entre aspas são lidos como marcação, nunca como código.
Cada chave listada mostra a sua grafia decodificada (uma entrada msgctxt do gettext como menu|Open); o --json traz também o catalogKey como o adaptador o escreve. Uma chave usada só fora do código-fonte varrido (um template de servidor, um CMS) pertence a extract.unused.ignore: um padrão corresponde à chave decodificada, e uma chave que corresponde é listada em ignored, nunca descartada.
Chaves protegidas
As chaves ausentes e alteradas que o translate deixaria para uma pessoa (uma pessoa escreveu, importou ou alterou o valor fora do verbatra, ou a chave corresponde a pinnedKeys) são listadas de novo em protected; veja Manter traduções humanas. Elas continuam em add e re-translate, porque ainda estão pendentes. Quando o verbatra.provenance.json está corrompido ou vem de um verbatra mais novo, só as chaves fixadas são listadas.
Saída JSON
Schema: o diff-envelope.json valida o envelope inteiro (o objeto JSON da resposta); Schemas lista os demais.
O --json imprime um envelope (veja Saída JSON) cujo result é um DiffSummary. hasPendingChanges é verdadeiro exatamente quando o comando termina com 1 por chaves pendentes:
interface DiffSummary {
hasPendingChanges: boolean;
locales: LocaleDiff[];
unused?: UnusedKeysReport; // só com --unused
}
interface LocaleDiff {
locale: string;
missing: string[]; // seria adicionada
changed: string[]; // seria retraduzida
orphaned: string[]; // só é relatada
emptySource?: string[]; // valor de origem vazio: nunca pendente
hasPendingChanges: boolean; // missing.length > 0 || changed.length > 0
changedOrigins?: Record<string, KeyOrigin>; // ausente quando o arquivo de procedência não pode ser lido
protected?: string[]; // chaves pendentes que o translate deixaria de lado
}Retorno no terminal
O diff mostra uma linha enquanto trabalha (diffing and scanning the source, com uma contagem de arquivos em andamento sob --unused) e sugere o próximo comando:
verbatra: diffing the locales... done (0.8s)
next: verbatra translate (send the pending keys to your provider)Quando toda chave pendente está protegida, ele sugere verbatra studio; sob provider: { id: "none" }, sugere verbatra export. Essas linhas vão para o stderr, e o --quiet as suprime. Veja Saída no terminal.
Códigos de saída
| Código | Significado |
|---|---|
0 | nenhum locale tem uma chave a adicionar ou retraduzir, e nenhuma varredura --unused completa encontrou uma chave não usada |
1 | pelo menos um locale tem uma chave ausente ou alterada, ou uma varredura --unused com status complete encontrou uma chave não usada |
2 | não conseguiu executar: um erro que afeta a execução inteira, um valor de --locales não configurado (UNKNOWN_) ou um erro de uso, como uma lista --locales vazia (INVALID_) |
As chaves órfãs, as possivelmente dinâmicas e as ignoradas, assim como um relatório unreliable ou not-run, nunca causam 1 sozinhas. Veja o contrato dos códigos de saída em Códigos de saída.
Veja também
- O
verbatra checkdá as contagens por locale por trás dessas listas. - O
verbatra translateaplica as alterações pendentes; o--pruneremove as chaves órfãs. - A página Arquivo de configuração documenta o bloco
extracte ounused.ignore. - Executar o verbatra na CI mostra o
diffem um pipeline.