---
title: "verbatra types"
description: "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."
type: "reference"
---
# 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.

<AvailableFrom version="0.11.0" />

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](https://verbatra.kreitz-webdev.de/pt-BR/docs/formats.md)) 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 [#sinopse]

```bash
verbatra types [flags]
```

## Exemplos [#exemplos]

```bash
# 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 [#flags]

| 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](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli.md#flags-globais) `--cwd`, `--config` e `--json`.

## Comportamento [#comportamento]

### O que ele gera [#o-que-ele-gera]

Dado um `locales/en.json` assim:

```json
{
  "app": { "title": "Verbatra" },
  "greeting": "Hello {{name}}",
  "cart": { "item_one": "{{count}} item", "item_other": "{{count}} items" }
}
```

você obtém:

```ts
// 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:

```ts
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 [#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 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 [#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`:

```ts
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 [#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 [#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 [#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 [#mantê-la-honesta-na-ci]

Execute `types --check` ao lado do [`verbatra check`](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/check.md) 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:

```text
verbatra-types.d.ts text eol=lf
```

### Saída JSON [#saída-json]

Schema: [`types-envelope.json`](https://verbatra.kreitz-webdev.de/schema/v1/types-envelope.json) valida o envelope inteiro (o objeto JSON da resposta); [Schemas](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/output.md#schemas) lista os outros.

Com `--json`, o [envelope](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/output.md#saída-json) traz um resultado:

```ts
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 [#retorno-no-terminal]

<AvailableFrom version="0.12.0" />

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:

```text output
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](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/output.md#saída-no-terminal) para a cor, o spinner e as variáveis que os controlam.

## Códigos de saída [#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_OUTPUT_CONFLICT`) ou uma declaração que não pôde ser gravada (`TYPES_UNWRITABLE`) |

Veja [Códigos de saída](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/output.md#códigos-de-saída) para o contrato que todo comando segue.

## Veja também [#veja-também]

- [`verbatra extract`](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/extract.md) adiciona ao catálogo as chaves que seu código usa; o `types` então as declara.
- [`verbatra check`](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/check.md) é a barreira de CI para divergências de locale, ao lado desta para divergências de tipos.
- [Formatos](https://verbatra.kreitz-webdev.de/pt-BR/docs/formats.md) lista a sintaxe de placeholder que cada formato usa.
- [Códigos de saída e saída JSON](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/output.md) cobre o envelope e o contrato dos códigos de saída.
