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

Referência / CLI

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.

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 --json

Flags

FlagArgumentoPadrãoEfeito
--out<path>verbatra-types.d.tsonde gravar a declaração, relativo ao diretório de trabalho e dentro da raiz do projeto; diretórios ausentes são criados
--checknenhumdesativadocompara 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 argument

O 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 mensagemO que é declarado
sem placeholdersVerbatraNoArguments, 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 arbnumber
um argumento ICU date ou time ({d, date, short}) em next-intl-json ou arbDate | number
um argumento ICU select ({gender, select, ...}) em next-intl-json ou arbstring
um formatador number do i18next ({{count, number}}) em i18next-json, ngx-translate-json ou yamlnumber
um formatador datetime do i18next ({{d, datetime}}) nos mesmos três formatosDate | 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 propertiesnumber
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 verificamVerbatraUnknownArguments, e a chave é nomeada na saída
uma mensagem que mistura argumentos nomeados, numerados e anônimosVerbatraUnknownArguments, 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_one e cart.item_other 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_ordinal_one 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_OUTPUT_CONFLICT quando ele:

  • não nomeia nenhum arquivo, inclusive um que termina com separador de caminho, como generated/ (um --out vazio falha antes, com INVALID_OUT),
  • é absoluto,
  • sai da raiz do projeto com ..,
  • não é um arquivo TypeScript, ou seja, o nome dele não termina em .ts, .mts ou .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.cjs ou verbatra.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 glossary da sua configuração aponta,
  • é um arquivo existente que não começa com a linha de cabeçalho // Generated by verbatra from que 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_UNWRITABLE, 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=lf

Saí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:

Saída
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 types

Veja Saída no terminal para a cor, o spinner e as variáveis que os controlam.

Códigos de saída

CódigoSignificado
0a 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)
2não foi possível executar: um erro de uso, um problema de configuração ou de origem, um caminho de saída recusado (TYPES_OUTPUT_CONFLICT) ou uma declaração que não pôde ser gravada (TYPES_UNWRITABLE)

Veja Códigos de saída para o contrato que todo comando segue.

Veja também

  • verbatra extract adiciona ao catálogo as chaves que seu código usa; o types entã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.
Editar no GitHub

Nesta página