Referência / CLI
Página traduzida automaticamente
verbatra types
Gera declarações TypeScript para as chaves do catálogo e os argumentos de suas mensagens, sem chamar um provedor nem ler uma chave de API.
Transforme uma chave com erro de digitação ou um argumento de interpolação esquecido em um erro de compilação. O types lê seu catálogo de origem pelo adaptador de formato configurado (veja Formatos) e grava um arquivo de declaração: uma união de todas as chaves e, por chave, os argumentos que a mensagem recebe. Ele não chama nenhum provedor, não lê nenhuma chave de API e nunca toca em um arquivo de locale de destino.
Sinopse
verbatra types [flags]Exemplos
# write verbatra-types.d.ts from the source catalog
verbatra types
# write it where the app already imports from
verbatra types --out src/generated/messages.d.ts
# CI gate: exit 1 if the committed declaration is stale
verbatra types --check
# machine-readable result for a script
verbatra types --jsonFlags
| Flag | Argumento | Padrão | Efeito |
|---|---|---|---|
--out | <path> | verbatra-types.d.ts | onde gravar a declaração, relativo ao diretório de trabalho e dentro da raiz do projeto; diretórios ausentes são criados |
--check | nenhum | desativado | compara a declaração versionada com uma geração nova byte a byte, sem gravar nada; termina com 1 quando ela está desatualizada ou ausente |
Aceita também as flags globais --cwd, --config e --json.
Comportamento
O que ele gera
Dado um locales/en.json assim:
{
"app": { "title": "Verbatra" },
"greeting": "Hello {{name}}",
"cart": { "item_one": "{{count}} item", "item_other": "{{count}} items" }
}você obtém:
// Generated by verbatra from locales/en.json (i18next-json). Do not edit by hand.
// Re-run `verbatra types` after the source catalog changes.
/** An argument whose type the source catalog does not record. */
export type VerbatraArgument = string | number;
/** The arguments of a message that takes none: passing any argument is a type error. */
export type VerbatraNoArguments = Record<string, never>;
/**
* The arguments of a message verbatra could not analyse, so nothing is claimed about them.
* Every key carrying this type is listed by `verbatra types` when it generates this file.
*/
export type VerbatraUnknownArguments = Record<string, VerbatraArgument>;
/** Every key in the source catalog, mapped to the arguments its message takes. */
export interface VerbatraMessages {
"app.title": VerbatraNoArguments;
"greeting": { readonly "name": VerbatraArgument };
"cart.item": { readonly "count": VerbatraArgument };
"cart.item_one": { readonly "count": VerbatraArgument };
"cart.item_other": { readonly "count": VerbatraArgument };
}
/** Every key in the source catalog. */
export type VerbatraMessageKey = keyof VerbatraMessages;
/** The arguments the message at `Key` takes. */
export type VerbatraMessageArguments<Key extends VerbatraMessageKey> =
VerbatraMessages[Key];
/** The keys the source catalog marks as carrying plural forms. */
export type VerbatraPluralMessageKey = "cart.item_one" | "cart.item_other";Defina os tipos da sua própria função de tradução com base nele e o compilador faz o resto:
import type { VerbatraMessageArguments, VerbatraMessageKey } from "./verbatra-types.js";
declare function t<Key extends VerbatraMessageKey>(
key: Key,
args: VerbatraMessageArguments<Key>,
): string;
t("greeting", { name: "Ada" }); // fine
t("greting", { name: "Ada" }); // error: not a key in the catalog
t("greeting", {}); // error: the name argument is required
t("app.title", { name: "Ada" }); // error: this message takes no argumentO que ele afirma e o que não afirma
As chaves são exatamente o que o adaptador de formato produziu, na ordem do documento, então o mesmo catálogo sempre produz os mesmos bytes. Os argumentos vêm dos placeholders que o adaptador extraiu; as mensagens de next-intl-json e arb são lidas com o parser de ICU do adaptador, então um argumento que só alguns ramos usam ainda é declarado. Nada é adivinhado e nada é declarado como any.
| Sua mensagem | O que é declarado |
|---|---|
| sem placeholders | VerbatraNoArguments, então passar qualquer coisa é um erro de tipo |
placeholders nomeados ({{name}}, {name}, %(name)s) | um tipo de objeto com esses nomes |
placeholders numerados ou anônimos ({0}, %@, %1$d) | uma tupla readonly, uma posição por argumento |
um argumento que só alguns ramos de select ou plural usam (next-intl-json, arb) | um membro opcional, name?:, ou uma posição opcional da tupla no fim ([number, VerbatraArgument?]); um que todos os ramos usam continua obrigatório |
um argumento ICU number, plural ou selectordinal em next-intl-json ou arb | number |
um argumento ICU date ou time ({d, date, short}) em next-intl-json ou arb | Date | number |
um argumento ICU select ({gender, select, ...}) em next-intl-json ou arb | string |
um formatador number do i18next ({{count, number}}) em i18next-json, ngx-translate-json ou yaml | number |
um formatador datetime do i18next ({{d, datetime}}) nos mesmos três formatos | Date | number |
uma interpolação sem escape do i18next ({{- name}}) | o nome que vem depois do prefixo, name |
um argumento number, plural ou choice do MessageFormat ({0,number}) em properties | number |
uma conversão numérica do printf (%d, %1$d) | number |
uma conversão de string do printf (%s, %(name)s) | string |
qualquer outro placeholder, inclusive um argumento ICU simples ({name}) | VerbatraArgument, um alias de string | number |
sintaxe de mensagem inválida, que só next-intl-json e arb verificam | VerbatraUnknownArguments, e a chave é nomeada na saída |
| uma mensagem que mistura argumentos nomeados, numerados e anônimos | VerbatraUnknownArguments, e a chave é nomeada na saída |
um argumento numerado abaixo da posição 0 ou na posição 64 ou acima (%0$s, {64}) | VerbatraUnknownArguments, e a chave é nomeada na saída |
Um formato cujos placeholders não têm nome (.strings da Apple, strings.xml do Android, conversões posicionais do gettext) recebe uma tupla, nunca nomes inventados. Um nome usado com tipos diferentes recebe a união deles: {d, date, short} ao lado de um {d} simples vira Date | number | string. As chaves são sempre literais de string entre aspas, então uma chave com ponto, palavra reservada, dígito inicial ou aspas é declarada literalmente. Uma chave que o adaptador excluiu da tradução (uma folha que não é string, um recurso translatable="false" do Android) nunca é declarada e é nomeada na saída.
Uma chave cujo próprio nome contém um ponto
A chave declarada é escrita do jeito que o verbatra a escreve em verbatra.lock.json, não em uma sintaxe de busca que sua biblioteca de i18n entenda. Um catálogo JSON com {"a.b": "..."} carrega a chave a\.b, deliberadamente distinta do caminho aninhado a.b:
export interface VerbatraMessages {
"a\\.b": VerbatraNoArguments;
}O i18next não tem escape para o separador de chaves, então t("a\\.b") não busca essa chave. Se o seu catálogo tem chaves assim, defina keySeparator com outro caractere (ou false para um catálogo plano) e mapeie a chave declarada para a chave usada em tempo de execução no seu próprio wrapper tipado.
O único caso em que a declaração está errada, e não apenas omissa
Só next-intl-json e arb validam a sintaxe das mensagens. Em todos os outros formatos, um valor quebrado como "Hello {name" não gera nenhum placeholder, então a mensagem é declarada como sem argumentos e passar o argumento de que ela realmente precisa é um erro de compilação. Nada relata isso, porque nada detectou. Corrija o catálogo, não a declaração.
Chaves com plural
Nada é agrupado. O i18next carrega o plural como sufixo de chave, então cart.item_ e cart.item_ são declaradas como estão escritas e, ao lado delas, a chave base cart.item que t("cart.item", { count }) busca, exigindo count e todo argumento que qualquer forma recebe. Os tipos do próprio i18next também aceitam as duas grafias. Um grupo ordinal como place_ declara place, e uma chave base que o catálogo já tem mantém a própria declaração. VerbatraPluralMessageKey lista as chaves que o adaptador marcou como portadoras de formas de plural, as com sufixo, para você restringir a elas.
Onde a declaração fica
Por padrão, ela vai para verbatra-types.d.ts na raiz do projeto. Inclua-a no commit: um colega ou um job de CI verifica os tipos com ela sem executar o verbatra, e --check precisa de um arquivo versionado para comparar. Nada a adiciona ao .gitignore.
Um caminho de saída é recusado com TYPES_ quando ele:
- não nomeia nenhum arquivo, inclusive um que termina com separador de caminho, como
generated/(um--outvazio falha antes, comINVALID_),OUT - é absoluto,
- sai da raiz do projeto com
.., - não é um arquivo TypeScript, ou seja, o nome dele não termina em
.ts,.mtsou.cts, - nomeia um arquivo de locale configurado, de origem ou de destino, para que a geração nunca possa sobrescrever um catálogo,
- é o arquivo de lock,
verbatra.lock.json, - é o arquivo de procedência,
verbatra.provenance.json, - é o cache da memória de tradução,
verbatra.cache.json, - é um arquivo que o verbatra procura para a configuração:
package.json,.verbatrarc,.verbatrarc.json,.verbatrarc.yaml,.verbatrarc.yml,.verbatrarc.js,.verbatrarc.cjs,.verbatrarc.ts,verbatra.config.js,verbatra.config.cjsouverbatra.config.ts, - é o arquivo de configuração que a execução de fato carregou, inclusive um que você nomeou com
--config, - é o arquivo de glossário para o qual a opção
glossaryda sua configuração aponta, - é um arquivo existente que não começa com a linha de cabeçalho
// Generated by verbatra fromque o verbatra grava no topo de toda declaração (uma marca de ordem de bytes inicial e linhas em branco são ignoradas), ou é grande demais para ser verificado.
Os nomes de arquivo são comparados sem diferenciar maiúsculas de minúsculas, e as verificações são repetidas depois que os links simbólicos são resolvidos, então um diretório vinculado não pode levar a declaração para fora da raiz do projeto nem para um arquivo protegido. A última verificação só é feita quando uma execução gravaria e deixa seu arquivo intacto; o --check nunca recusa um arquivo existente. Um caminho que passa em todas as verificações ainda pode falhar na gravação (um diretório somente leitura, um disco cheio): a execução para com TYPES_, nomeando o arquivo e o código do sistema de arquivos, como EACCES.
Mantê-la honesta na CI
Execute types --check ao lado do verbatra check no mesmo job: o check pega locales que ficam para trás da origem, e o types --check pega seus tipos ficando para trás dela. A comparação é byte a byte e a declaração é sempre gravada com quebras de linha LF, então fixe as quebras de linha no .gitattributes, ou um checkout que as reescreva deixa o arquivo permanentemente desatualizado:
verbatra-types.d.ts text eol=lfSaída JSON
Schema: types-envelope.json valida o envelope inteiro (o objeto JSON da resposta); Schemas lista os outros.
Com --json, o envelope traz um resultado:
interface GenerateTypesResult {
path: string; // absolute path of the declaration file
sourcePath: string; // the source catalog, relative to the project root
keys: number; // how many keys are declared
withArguments: number; // keys taking at least one determined argument
unresolved: { key: string; reason: "invalid-message-syntax" | "mixed-argument-styles" | "argument-index-out-of-range" }[];
excluded: string[]; // keys the adapter excluded, never declared
plural: string[]; // keys carrying plural forms
written: boolean; // false under --check and when the file already matched
stale: boolean; // the file on disk differed when the run started
missing: boolean; // no file existed when the run started
check: boolean; // whether this was a --check run
}Retorno no terminal
O resumo vai para o stdout; uma linha de spinner e, depois de uma gravação, uma dica para fazer commit do arquivo vão para o stderr (--check não sugere nada, e --quiet omite os dois). Uma execução que gera, uma nova execução sem alterações e um --check que encontra a declaração obsoleta:
verbatra: generating the declarations... done (0.2s)
verbatra types
214 keys declared, 63 of them taking arguments, from locales/en.json
arguments not determined (1):
legal.notice invalid-message-syntax
excluded by the adapter (1): meta.version
wrote verbatra-types.d.ts
next: commit verbatra-types.d.ts (verbatra types --check compares against it in CI)
verbatra types
214 keys declared, 63 of them taking arguments, from locales/en.json
unchanged verbatra-types.d.ts
verbatra types
215 keys declared, 63 of them taking arguments, from locales/en.json
verbatra-types.d.ts is out of date, re-run verbatra typesVeja Saída no terminal para a cor, o spinner e as variáveis que os controlam.
Códigos de saída
| Código | Significado |
|---|---|
0 | a declaração foi gerada, tenha o arquivo mudado ou não; ou --check a encontrou atualizada |
1 | --check encontrou a declaração versionada desatualizada ou ausente (is missing, run verbatra types to create it) |
2 | não foi possível executar: um erro de uso, um problema de configuração ou de origem, um caminho de saída recusado (TYPES_) ou uma declaração que não pôde ser gravada (TYPES_) |
Veja Códigos de saída para o contrato que todo comando segue.
Veja também
verbatra extractadiciona ao catálogo as chaves que seu código usa; otypesentão as declara.verbatra checké a barreira de CI para divergências de locale, ao lado desta para divergências de tipos.- Formatos lista a sintaxe de placeholder que cada formato usa.
- Códigos de saída e saída JSON cobre o envelope e o contrato dos códigos de saída.