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 doctor

Verifique se um projeto está configurado corretamente e receba todos os problemas em um único relatório, sem chamar um provedor nem ler uma chave de API.

Verifique se um projeto está configurado corretamente e receba todos os problemas em um único relatório. O doctor não instancia nenhum provedor, não grava nenhum arquivo e só lê o valor de uma chave de API com --live, que o envia em uma requisição para obter a lista de idiomas do provedor (o LibreTranslate não recebe nenhuma chave de API). Execute-o depois de verbatra init ou quando outro comando falhar.

Sinopse

verbatra doctor [flags]

Exemplos

# report every setup problem at once
verbatra doctor

# validate a project in another directory, with an explicit config
verbatra doctor --cwd apps/web --config verbatra.config.ts

# machine-readable report for a CI preflight step
verbatra doctor --json

# list hardcoded user-facing strings, with no key set
verbatra doctor --literals

# what the provider supports for each target locale
verbatra doctor --locales

# the same, against the provider's current language list
verbatra doctor --live

# a data-flow manifest to attach to a DPA or NDA review
verbatra doctor --data-flow --json

Flags

FlagArgumentoPadrãoEfeito
--literalsnenhumdesativadovarre os diretórios-raiz do código-fonte do bloco extract atrás de strings de interface escritas diretamente no código, em vez de verificar a configuração (veja Literais não traduzidos)
--localesnenhumdesativadodepois das verificações, lista por locale de destino o código enviado, o suporte do provedor, o glossário e a formalidade (veja Suporte a locales)
--livenenhumdesativadobusca primeiro a lista atual de idiomas do provedor, sem usar cota de tradução; implica --locales
--data-flownenhumdesativadodescreve o que é enviado a qual host e o que é gravado localmente, em vez de verificar a configuração (veja Fluxo de dados)

Aceita também as flags globais --cwd, --config e --json. --locales e --live não podem ser combinadas com --literals (INVALID_OPTION, código de saída 2), e --data-flow não pode ser combinada com nenhuma das três.

Comportamento

O que ele verifica

Uma execução normal (que verifica a configuração) relata estas verificações, nesta ordem. Plural rules (regras de plural), Plural completeness (completude de plurais), Locale codes (códigos de locale), Locale state (estado do locale) e Length limits (limites de tamanho) são apenas informativas e nunca falham: cada uma imprime [warn] quando aponta algo e [ok ] nos demais casos.

VerificaçãoFalha quando
Configurationnenhum arquivo de configuração é encontrado, ou ele não passa na validação
Format adaptero format configurado não corresponde a nenhum adaptador de arquivo
Providero provider.id configurado não corresponde a nenhuma função de fábrica de provedor
API key environment variablea variável da qual esse provedor lê a chave de API não está definida
Network policya política de rede em vigor (veja Restringir o acesso à rede) recusa o host do provedor ou um proxy que ele usaria
Source locale fileo arquivo de locale de origem está ausente no caminho resolvido, não é um arquivo comum ou não pode ser analisado no formato configurado
Plural rulesnunca; nomeia as versões do ICU e do CLDR em uso e emite um alerta quando um locale de destino não tem regras de plural do ICU
Plural completenessnunca; emite um alerta e nomeia cada plural de destino que não tem uma categoria do CLDR usada pelo idioma dele, avaliando um plural para o qual o destino não tem formas pelo que uma execução gravaria ali (uma forma de origem em branco conta como ausente, e a geração de plurais só onde ela de fato é executada), de propósito mais rigorosa que o aviso do translate, exclusivo do i18next (no máximo dez; verbatra check lista as lacunas nos plurais que um destino já tem)
Locale codesnunca; emite um alerta e nomeia todo código válido, mas não canônico, como en-us ou iw, com a forma canônica (veja Códigos de locale)
Locale statenunca; emite um alerta e nomeia todo locale para o qual o arquivo de lock, o cache ou o arquivo de procedência guardam estado e que a configuração não lista, e se o translate o mantém
Length limitsnunca; emite um alerta quando o verbatra.limits.json não pode ser usado (uma execução o ignora e um limite só pode ser definido depois que ele for corrigido), nomeia um limite para uma chave que a origem não tem mais ou um que o maxLength da configuração sobrescreve, e informa quando a origem não pôde ser lida para verificar as chaves; passa quando o arquivo não existe (limites de tamanho)
Locale supporto provedor não aceita o locale de origem ou um locale de destino; emite um alerta quando um locale traz um alerta (veja Suporte a locales)

Toda verificação é executada mesmo quando uma anterior falhou. A única exceção é a configuração: quando ela não pode ser carregada, as verificações que dependem dela aparecem como [skip] ("status": "skipped" no JSON), assim como Plural completeness para um formato sem formas de plural do CLDR. Uma verificação que encontrou algo que merece atenção sem falhar imprime [warn] ("status": "warn" no JSON) e nunca muda o código de saída. Uma verificação com falha traz também um fix, um próximo passo no imperativo impresso como fix: e enviado como "fix" no JSON, para que um agente não precise analisar o detail.

Uma execução com dois problemas:

Saída
verbatra doctor
  [ok  ] Configuration: Loaded /app/verbatra.config.ts.
  [ok  ] Format adapter: Format "i18next-json" resolves to an adapter.
  [ok  ] Provider: Provider "anthropic" resolves to a factory.
  [fail] API key environment variable: The ANTHROPIC_API_KEY environment variable is not set.
         fix: Set ANTHROPIC_API_KEY in the environment, or, with the CLI, in a .env file in the project directory.
  [ok  ] Network policy: any host (config: unset; VERBATRA_NETWORK_POLICY: unset). Provider "anthropic" connects to api.anthropic.com: permitted.
  [fail] Source locale file: The source locale file was not found at /app/locales/en.json.
         fix: Create the source locale file, or fix `files.pattern` and `sourceLocale` in the config so they point at it.
  ...
  [warn] Locale codes: "iw" is canonically "he". Consider the canonical form in your config; file names follow the configured code and are never renamed for you.
  [ok  ] Locale support: Provider "anthropic" is an LLM and accepts any locale (well-tested list of 2026-09-28).
2 problems found (run verbatra doctor again after fixing them)

Uma execução limpa termina com no problems found, mais , N warnings quando uma verificação emitiu um alerta.

Chaves de API e arquivos

  • A chave de API é verificada apenas pelo nome: o doctor pergunta se a variável está definida, nunca o que ela contém. Veja Provedores para a variável de cada provedor.
  • O openai-compatible recorre a uma chave de API fictícia, então só falha quando a configuração nomeia a própria provider.options.apiKeyEnvVar e essa variável não está definida. O libretranslate nunca falha na verificação, já que a chave de API dele é opcional.
  • Com provider: { id: "none" }, as verificações Provider (provedor), API key (chave de API) e Network policy (política de rede) passam e Locale support (suporte a locales) é ignorada.
  • Um arquivo de destino ausente não é problema: o translate o cria. O arquivo de origem é analisado, então um diretório, um arquivo vazio ou conteúdo malformado faz a verificação falhar.
  • O doctor carrega primeiro os arquivos de ambiente, então uma chave de API em um arquivo dotenv conta como definida; com --literals ele não carrega nenhum dos dois.

Suporte a locales

A verificação Locale support pergunta se o provedor consegue traduzir cada locale configurado. O DeepL e o Google Cloud Translation são avaliados com base em uma tabela de idiomas datada que o verbatra inclui; um provedor de LLM aceita qualquer locale. Ela falha exatamente no locale que o verbatra translate recusaria com LOCALE_UNSUPPORTED_BY_PROVIDER e, nos demais casos, imprime [warn] quando um locale traz um alerta ou quando o --live não conseguiu obter a lista. Idiomas e locales explica os vereditos.

--locales imprime o veredito por locale depois das verificações:

Saída
  locale support (deepl, language table of 2026-09-28, static)
    en  sent as EN  source, supported
    de  sent as DE  supported  glossary: yes  formality: yes
    sv  sent as SV  supported  glossary: yes  formality: no
      warning [FORMALITY_UNSUPPORTED_BY_PROVIDER] Provider "deepl" has no formality control for "sv", so the configured formal tone is not applied and the provider's default register is used.
    chr  sent as CHR  unsupported  glossary: no  formality: no

Cada linha nomeia o locale, o código que o provedor recebe (depois de localeMap, marcado com (localeMap)), o veredito e se um glossário e um tom formal ou informal se aplicam. Um alerta é apenas informativo.

--live avalia com base na lista atual do provedor, em vez da tabela (/v3/languages do DeepL, languages do Cloud Translation, /languages do LibreTranslate). Para o LibreTranslate, que não inclui tabela, é a única forma de obter um veredito diferente de unverified, então Locale support mostra [warn] até o --live ser executado. A requisição só é enviada quando a variável da chave de API está definida (o LibreTranslate não precisa de nenhuma) e a política de rede (veja Restringir o acesso à rede) permite o host; caso contrário, ou em caso de falha, a tabela que acompanha o verbatra é usada e uma linha live language list diz o motivo.

Literais não traduzidos

--literals encontra strings de interface que nunca chegaram a um catálogo. Ela percorre os diretórios-raiz do código-fonte do seu bloco extract, lê o seu código-fonte e nunca o grava, não instancia nenhum provedor, não lê nenhuma chave de API e não carrega nenhum arquivo .env. Só duas verificações são executadas: Configuration (configuração) e Untranslated literals (literais não traduzidos). Cada ocorrência indica arquivo, linha e coluna, com os espaços em branco reduzidos a um só, as referências de caractere do JSX decodificadas e no máximo 80 caracteres:

Saída
  [fail] Untranslated literals: Scanned 42 source files: 2 untranslated literals found (1 suppressed).
    src/components/Header.tsx:12:9  "Welcome back"
    src/pages/settings.tsx:40:22  "Save changes"
    suppressed (directive) src/pages/legal.tsx:8:5  "Acme Inc."

São informados: texto JSX em arquivos .tsx, .jsx e .js; atributos JSX voltados ao usuário (alt, title, placeholder, label, aria-label e os demais aria-* que carregam texto); e qualquer outra string de duas ou mais palavras.

Nunca são informados:

  • uma string passada a t(...), $t(...), i18n.t(...) ou a um t renomeado vindo de useTranslation, ou renderizada dentro de <Trans> ou <Translation>;
  • chaves de objeto, especificadores de importação, nomes de classe, valores de CSS, ids de teste, data-* e atributos de id ou de palavra-chave (aria-describedby, aria-labelledby, aria-controls, rel, sandbox, allow, autoComplete, referrerPolicy, crossOrigin), URLs e strings sem letras;
  • literais em uma posição de tipo (o valor antes de as ou satisfies ainda é verificado), mensagens de log, mensagens de erro (new ValidationError(...), throw Error(...)), operandos de comparação e template literals com uma expressão;
  • argumentos diretos de describe (zod), query, execute, prepare, format, parse, z.enum, setItem, getItem e removeItem, e o primeiro argumento de on, off, once, emit, addEventListener e de um get ou set de membro; textos aninhados mais fundo, e mensagens passadas a funções como setError, ainda são informados;
  • qualquer coisa em arquivos de teste, de story, de declaração ou de configuração.

Para excluir um literal, coloque // verbatra-ignore-next-line acima dele ({/* verbatra-ignore-next-line */} no JSX) ou // verbatra-ignore-line no fim da linha dele. Uma diretiva next-line se aplica à próxima linha que contém código e, em uma tag de abertura JSX, a todos os atributos dessa tag. Para uma string que é aceitável em todo lugar, liste-a em extract.literals.ignore com as referências decodificadas (Tom & Jerry). Os literais excluídos continuam listados, com o motivo.

A verificação falha diante de uma ocorrência e de um arquivo que não pôde ser aberto, lido até o fim ou que foi considerado grande demais (a varredura continua). Um projeto sem um bloco extract faz a verificação falhar.

Fluxo de dados

--data-flow descreve para onde vão os dados deste projeto, em vez de verificar a configuração, como evidência para uma revisão de DPA (acordo de tratamento de dados) ou de NDA (acordo de confidencialidade); Tratamento de dados e privacidade explica cada categoria. Ele não lê nenhuma chave de API e não faz nenhuma requisição de rede. Só duas verificações são executadas: Configuration e Data flow (fluxo de dados). Data flow nunca falha: imprime [warn] quando a política de rede (veja Restringir o acesso à rede) recusa um host ou contém um valor inválido, ou quando o arquivo de origem não pode ser lido para as contagens.

Saída
  [ok  ] Data flow: Provider "deepl" sends source-text, placeholder-markers, language-codes to api.deepl.com (permitted), api-free.deepl.com (permitted).
  data flow (manifest version 1)
    provider     deepl (machine-translation)
    network      any host (no policy set)
    destination  api.deepl.com  default  paid-key  before-construction  permitted
    destination  api-free.deepl.com  default  free-key  before-construction  permitted
    sent         source-text, placeholder-markers, language-codes
    api key      required
    placeholders masked
    sensitive    off
    counts       3 source keys, 0 with a description or meaning, 1 with placeholders it cannot mask (withheld)
    locale       de  sent as DE  glossary terms: 0
    local        lock  verbatra.lock.json  (no source text, translations or personal data)
    local        provenance  verbatra.provenance.json  (reviewer names)
    local        limits  verbatra.limits.json  (no source text, translations or personal data)
    local        cache  verbatra.cache.json  (source text, translations, gitignored by init)
    local        local-state  .verbatra-local  (source text, host name and process ID of a run holding a write lock, gitignored by init)
    request      language-list  verbatra doctor --live  sends the API key
    request      dns-lookup  each connection to a destination host
    agent        mcp  verbatra mcp  redactable
    agent        studio-agent-tools  verbatra studio --expose-agent-tools

O manifesto nomeia o provedor; cada host de destino, de onde ele vem (embutido, provider.options.baseUrl ou uma variável *_BASE_URL) e o veredito da política (permitted, deferred, refused ou invalid-policy); os tipos de dados enviados, com o número de chaves de origem, de chaves que carregam uma descrição ou um significado e de chaves cujos placeholders o provedor não consegue mascarar (uma estimativa sobre as chaves de origem: uma execução envia apenas as chaves ausentes ou alteradas e pode reter mais com sensitiveData: redact); o código e o número de termos de glossário por locale de destino; os arquivos locais com os caminhos relativos ao projeto, e se guardam texto de origem, traduções ou dados pessoais; e as demais requisições e interfaces de agente. O DeepL é listado com os dois hosts, porque a chave de API que escolhe um deles nunca é lida. Um proxy em vigor é nomeado pela variável e pelo host, nunca pelas credenciais, e os campos listam só o que esta configuração pode enviar. Com provider: { id: "none" }, ele informa que nada é enviado. Ele nomeia hosts, categorias de dados e condições, nunca o valor de uma chave de API nem o conteúdo de arquivos.

Com --json, o manifesto fica em result.dataFlow. O campo version dele só muda quando um campo é renomeado ou removido; campos novos podem aparecer sem mudança de versão, então ignore os que você não conhece. O dataFlowManifestSchema do SDK o valida.

Saída JSON

Schema: doctor-envelope.json valida o envelope inteiro (o objeto JSON da resposta); Schemas lista os demais.

Com --json, o envelope traz o relatório em result. ok é verdadeiro exatamente quando o comando sai com 0:

interface DoctorResult {
  ok: boolean;                 // true exactly when the command exits 0
  checks: DoctorCheck[];       // one per check, always in the same order
  literals?: LiteralScan;      // only with --literals: findings, suppressed, diagnostics
  dataFlow?: DataFlowManifest; // only with --data-flow: what goes where, version 1
  locales?: LocaleCapabilityReport; // per-locale provider support, with or without --locales
}

interface DoctorCheck {
  id:
    | "config"
    | "format-adapter"
    | "provider"
    | "api-key"
    | "network-policy"
    | "source-file"
    | "plural-rules"
    | "plural-completeness"
    | "locale-codes"
    | "locale-state"
    | "limits" // 0.13.0
    | "locales"
    | "untranslated-literals"
    | "data-flow";
  title: string;               // stable, human-readable name
  status: "pass" | "warn" | "fail" | "skipped";  // only "fail" makes ok false
  detail: string;              // why it reached that verdict; never an API key value
  fix?: string;                // the next step, only on a failed check
}

interface LocaleCapabilityReport {
  provider: string;
  coverage: "listed" | "open";       // "open" for an LLM provider
  tableVersion: string;              // the table's date (YYYY-MM-DD)
  tableOrigin: "static" | "live";    // "live" only when --live fetched the list
  live?: { status: "refreshed" | "skipped" | "failed"; detail: string }; // only with --live
  source: {
    locale: string;
    providerCode: string;
    mapped: boolean;
    support: "supported" | "unverified" | "unsupported";
    warnings: { code: string; message: string }[];
  };
  locales: {
    locale: string;
    providerCode: string;            // the code the provider receives
    mapped: boolean;                 // true when localeMap set providerCode
    support: "supported" | "unverified" | "unsupported";
    glossary: boolean;
    formality: boolean;
    warnings: { code: string; message: string }[];
  }[];
}

result.locales está ausente quando a configuração não pôde ser carregada, para um provedor desconhecido e para provider: { id: "none" }.

Retorno no terminal

Enquanto é executado, o doctor mostra uma linha no stderr, que --quiet descarta: checking the setup, checking the setup and fetching the provider's language list com --live, describing the data flow com --data-flow ou scanning the source for literals com --literals, junto com a contagem de arquivos. O relatório permanece no stdout. Veja Saída no terminal.

Códigos de saída

CódigoSignificado
0nenhuma verificação falhou (com um warn, o código de saída continua 0)
1pelo menos uma verificação falhou, inclusive um locale sem suporte; com --literals, um literal foi encontrado ou um arquivo não pôde ser varrido
2não foi possível executar: um erro de uso, ou um caminho --config explícito que não existe

Uma configuração que a busca não encontra, ou que falha na validação, é uma verificação com falha (código de saída 1), porque relatá-la é o trabalho do comando. Veja o contrato dos códigos de saída.

Veja também

  • verbatra init gera a configuração e o .env.example que o doctor valida.
  • verbatra check é a barreira contra divergências a executar quando a configuração estiver correta.
  • Arquivo de configuração documenta todas as opções que o doctor valida.
  • Provedores lista a variável da chave de API que cada provedor lê.
  • Idiomas e locales lista as tabelas de idiomas que a verificação Locale support usa.
Editar no GitHub

Nesta página