verbatra doctor

Responde una pregunta antes de ejecutar cualquier otra cosa: ¿este proyecto está bien configurado? doctor valida la configuración, el adaptador de formato, el proveedor, la variable de la clave de API y el archivo del locale de origen, y luego informa de todos los problemas que encontró a la vez. No gasta nada: no construye ningún proveedor, no hace ninguna petición de red, no escribe ningún archivo y nunca lee el valor de una clave de API.

Úsalo en un checkout recién hecho, justo después de verbatra init, o cuando otro comando haya fallado y quieras la lista completa en lugar del primer error. verbatra check es la validación más barata una vez que el proyecto ya funciona, pero lee los archivos de locale y se detiene en el primer error de toda la ejecución, así que no puede decirte qué falla en un proyecto que todavía no tiene archivo de origen.

Sinopsis

verbatra doctor [flags]

Flags

Qué comprueba

Todas las comprobaciones se ejecutan aunque una anterior haya fallado, así que una sola ejecución informa de cada problema independiente. La única excepción es la propia configuración: cuando no se puede cargar, las cuatro comprobaciones que la necesitan se omiten en lugar de llegar a un veredicto. Una comprobación así se imprime como [skip] en el informe legible y lleva "status": "skipped" en el envoltorio --json.

Cuatro detalles que conviene conocer:

• La clave de API se comprueba solo por nombre. doctor pregunta si la variable está definida, nunca qué contiene. El valor no se lee, no se imprime y no se envía a ninguna parte. Consulta Proveedores para saber qué variable usa cada proveedor.
• El proveedor openai-compatible es la excepción. Recurre a una clave placeholder, así que una variable ausente no es problema. Solo falla cuando tu configuración nombra su propia variable con provider.options.apiKeyEnvVar y esa variable no está definida.
• Un archivo de locale de destino que falta no es un problema: verbatra translate lo crea. Los archivos de destino no se comprueban en absoluto.
• El archivo del locale de origen se lee y se analiza, no solo se comprueba su existencia. Un directorio en su lugar, un archivo vacío y contenido malformado fallan esta comprobación con el mismo mensaje que daría verbatra check, porque esos son justo los casos que hacen fallar a todos los demás comandos. Cuando el format configurado no resuelve a ningún adaptador no hay con qué analizarlo, así que la comprobación vuelve a la mera existencia y lo indica.

Igual que verbatra translate, doctor carga .env.local y luego .env desde el directorio de trabajo antes de mirar el entorno, así que una clave guardada en un archivo dotenv cuenta como definida. Con --literals no carga ninguno de los dos archivos.

Literales sin traducir

verbatra doctor --literals busca el único error de i18n que ninguna otra comprobación ve: una cadena visible para el usuario que nunca llegó a un catálogo. Recorre las raíces de código de tu bloque extract e informa de cada cadena incrustada en el código que se lee como texto para el usuario pero no pasa por ninguna llamada de traducción. Lee tu código y nunca lo escribe, no construye ningún proveedor, no lee ninguna variable de clave de API y no carga ningún archivo .env, así que pasa en un job sin secretos. En este modo solo se ejecutan dos comprobaciones: la configuración y el escaneo de literales.

Cada hallazgo indica archivo, línea y columna. En su texto se compactan los espacios y, en JSX, se decodifican las referencias de caracteres como &, y se recorta a 80 caracteres como máximo:

verbatra doctor
  [ok  ] Configuration: Loaded /app/verbatra.config.ts.
  [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."
1 problem found (run verbatra doctor again after fixing them)

Qué cuenta como hallazgo:

• Texto JSX, como <p>Welcome back</p>, en archivos .tsx, .jsx y .js.
• El valor de un atributo JSX visible para el usuario: alt, title, placeholder, label, aria-label y los demás atributos aria-* que llevan texto.
• Una cadena en cualquier otra posición que se lee como prosa, es decir, de dos o más palabras. Una sola palabra fuera de JSX, como un nombre de evento o un valor de opción, no se informa.

Lo que nunca se informa: una cadena pasada a una llamada de traducción reconocida (t(...), $t(...), i18n.t(...), o un t renombrado desde useTranslation, como en const { t: translate } = useTranslation(), desde esa línea hasta el final del bloque que la contiene) o renderizado dentro de <Trans> o <Translation>, una clave de objeto, un especificador de import, un nombre de clase o valor CSS, un test id o atributo data-*, un atributo que contiene ids o una palabra clave en lugar de texto (como aria-describedby, aria-labelledby, aria-controls, rel, sandbox, allow, autoComplete, referrerPolicy o crossOrigin), una URL, un literal en posición de tipo (también uno después de as o satisfies; el valor anterior, como en "Welcome" as const, se sigue comprobando), un mensaje de log, el mensaje de un error construido (new ValidationError(...)) o de un error integrado llamado sin new (throw Error(...)), un operando de comparación, un template literal con una expresión, una cadena sin letras (puntuación, espacios, un número, un emoji, un símbolo) y todo lo que esté en archivos de test, stories, declaraciones o configuración.

También se omiten las llamadas que esperan una consulta, un formato o un nombre en lugar de texto: una cadena pasada directamente como argumento de describe (zod), query, execute, prepare, format o parse, una cadena del array pasado directamente a z.enum, cada argumento de tipo cadena de setItem, getItem y removeItem, y el primer argumento de on, off, once, emit, addEventListener y de una llamada get o set sobre un objeto, como cookies().get(...). Solo se omiten los argumentos directos: el texto anidado más adentro de esa llamada, como en un callback (query(() => ({ message: "..." }))), un objeto o JSX, se sigue informando. Una función cuyo nombre solo termina en Error por casualidad, como setError o showError, no se omite, así que el mensaje que le pasas se sigue informando.

Para retener un literal, pon // verbatra-ignore-next-line encima (en JSX, {/* verbatra-ignore-next-line */}), o // verbatra-ignore-line al final de su propia línea. Una directiva de línea siguiente apunta a la siguiente línea con código (se saltan las líneas vacías y las que solo tienen comentarios) y cubre cada literal que empieza en esa línea. Cuando ahí empieza una etiqueta de apertura JSX, también cubre todos sus atributos, aunque la etiqueta ocupe varias líneas. El texto y los elementos anidados de líneas posteriores no quedan cubiertos, así que dale a cada uno su propia directiva. Para una cadena que está bien en todas partes, como un nombre de marca, añádelo en extract.literals.ignore en el archivo de configuración. Una entrada coincide con el texto tal como se informa, con las referencias de caracteres decodificadas, así que escribe Tom & Jerry, no Tom & Jerry. Un literal retenido se sigue listando como suprimido, con el motivo, así que nada desaparece en silencio.

La comprobación falla cuando encuentra un literal, y también cuando un archivo no se pudo escanear. Un archivo que el escáner no puede leer hasta el final (un comentario o template literal sin cerrar, o un elemento JSX que nunca se cierra o que queda cerrado por la etiqueta de un elemento que lo rodea), no puede abrir en absoluto o considera demasiado grande se lista como no escaneado y el resto del escaneo continúa, pero la ejecución nunca se informa como limpia. Un tipo de función genérico del estilo type Fn = <T>(x: T) => T o una lista de parámetros de tipo como <const T extends object = {}>(x: T) => x en un archivo .tsx se lee como código normal, así que nunca hace fallar el archivo, y un elemento con argumentos de tipo de cualquier longitud, como <Table<Row>>, se sigue leyendo como JSX. Un proyecto sin bloque extract hace fallar la comprobación con un mensaje que nombra el bloque. Con --json, el escaneo viaja en el envoltorio bajo result.literals, dividido en findings, suppressed y diagnostics.

Ejemplos

# 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 in your source, with no key set
verbatra doctor --literals

Una ejecución con dos problemas se ve así:

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.
  [fail] Source locale file: The source locale file was not found at /app/locales/en.json.
2 problems found (run verbatra doctor again after fixing them)

Códigos de salida

El código de salida 1 significa "se ejecutó y encontró problemas". El código 2 queda reservado a que doctor no pueda ejecutarse en absoluto, por eso un archivo de configuración que la búsqueda no encuentra es una comprobación fallida y da 1, mientras que una ruta --config que apunta a la nada da 2.

Relacionado

• verbatra init genera la configuración y el .env.example que doctor valida.
• verbatra check es la puerta contra el desfase que ejecutas una vez que la configuración es correcta.
• El archivo de configuración documenta todas las claves que doctor valida.
• Proveedores lista la variable de clave de API que lee cada proveedor.