verbatra doctor

Réponds à une question avant de lancer quoi que ce soit d'autre : ce projet est-il correctement configuré ? doctor valide la config, l'adaptateur de format, le fournisseur, la variable de clé d'API et le fichier de locale source, puis signale d'un coup tous les problèmes trouvés. Il ne dépense rien : aucun fournisseur n'est construit, aucune requête réseau n'est faite, aucun fichier n'est écrit, et aucune valeur de clé d'API n'est jamais lue.

Utilise-le sur un checkout tout neuf, juste après verbatra init, ou chaque fois qu'une autre commande a échoué et que tu veux la liste complète plutôt que la première erreur. verbatra check est la validation la moins chère une fois le projet fonctionnel, mais il lit les fichiers de locale et s'arrête à la première erreur globale : il ne peut donc pas te dire ce qui cloche dans un projet qui n'a pas encore de fichier source.

Synopsis

verbatra doctor [flags]

Options

Ce qu'il vérifie

Chaque vérification s'exécute même si une précédente a échoué : une seule exécution signale donc tous les problèmes indépendants. Seule exception, la config elle-même : quand elle ne peut pas être chargée, les quatre vérifications qui en dépendent sont ignorées au lieu d'aboutir à un verdict. Une telle vérification s'affiche [skip] dans le rapport lisible et porte "status": "skipped" dans l'enveloppe --json.

Quatre détails comptent :

• La clé d'API est vérifiée par son nom uniquement. doctor demande si la variable est définie, jamais ce qu'elle contient. La valeur n'est pas lue, pas affichée, et n'est envoyée nulle part. Voir Fournisseurs pour la variable utilisée par chaque fournisseur.
• Le fournisseur openai-compatible fait exception. Il retombe sur une clé placeholder : une variable absente ne pose donc pas de problème. Il échoue seulement quand ta config nomme sa propre variable via provider.options.apiKeyEnvVar et que cette variable n'est pas définie.
• Un fichier de locale cible manquant n'est pas un problème : verbatra translate le crée. Les fichiers cibles ne sont pas vérifiés du tout.
• Le fichier de locale source est lu et analysé, pas seulement recherché. Un répertoire à sa place, un fichier vide et un contenu malformé font tous échouer cette vérification avec le message que verbatra check donnerait, car ce sont exactement les cas qui font échouer toutes les autres commandes. Quand le format configuré ne résout aucun adaptateur, il n'y a rien pour l'analyser, donc la vérification retombe sur la seule existence et le signale.

Comme verbatra translate, doctor charge .env.local puis .env depuis le répertoire de travail avant de regarder l'environnement : une clé rangée dans un fichier dotenv compte donc comme définie. Avec --literals, il ne charge aucun des deux fichiers.

Littéraux non traduits

verbatra doctor --literals cherche le seul bug i18n qu'aucune autre vérification ne voit : une chaîne visible par l'utilisateur qui n'est jamais arrivée dans un catalogue. Il parcourt les racines de code de ton bloc extract et signale chaque chaîne écrite en dur qui se lit comme un texte destiné à l'utilisateur mais ne passe par aucun appel de traduction. Il lit ton code et ne l'écrit jamais, ne construit aucun fournisseur, ne lit aucune variable de clé d'API et ne charge aucun fichier .env : il passe donc dans un job sans secrets. Dans ce mode, seules deux vérifications s'exécutent : la configuration et l'analyse des littéraux.

Chaque constat indique le fichier, la ligne et la colonne. Dans son texte, les espaces sont réduits et, en JSX, les références de caractères comme & sont décodées, et il est coupé à 80 caractères au plus :

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)

Ce qui compte comme un constat :

• Le texte JSX, comme <p>Welcome back</p>, dans les fichiers .tsx, .jsx et .js.
• La valeur d'un attribut JSX visible par l'utilisateur : alt, title, placeholder, label, aria-label et les autres attributs aria-* porteurs de texte.
• Une chaîne à tout autre endroit qui se lit comme de la prose, c'est-à-dire de deux mots ou plus. Un mot isolé hors JSX, comme un nom d'événement ou une valeur d'option, n'est pas signalé.

Ce qui n'est jamais signalé : une chaîne passée à un appel de traduction reconnu (t(...), $t(...), i18n.t(...), ou un t renommé depuis useTranslation, comme dans const { t: translate } = useTranslation(), de cette ligne jusqu'à la fin du bloc qui l'entoure) ou rendue dans <Trans> ou <Translation>, une clé d'objet, un spécificateur d'import, un nom de classe ou une valeur CSS, un test id ou un attribut data-*, un attribut qui contient des ids ou un mot-clé plutôt que du texte (comme aria-describedby, aria-labelledby, aria-controls, rel, sandbox, allow, autoComplete, referrerPolicy ou crossOrigin), une URL, un littéral en position de type (y compris un littéral après as ou satisfies ; la valeur qui les précède, comme dans "Welcome" as const, reste vérifiée), un message de log, le message d'une erreur construite (new ValidationError(...)) ou d'une erreur intégrée appelée sans new (throw Error(...)), un opérande de comparaison, un template literal contenant une expression, une chaîne sans lettres (ponctuation, espaces, un nombre, un emoji, un symbole) et tout ce qui se trouve dans les fichiers de test, de stories, de déclaration ou de configuration.

Les appels qui attendent une requête, un format ou un nom plutôt que du texte sont aussi ignorés : une chaîne passée directement en argument à describe (zod), query, execute, prepare, format ou parse, une chaîne du tableau passé directement à z.enum, chaque argument chaîne de setItem, getItem et removeItem, ainsi que le premier argument de on, off, once, emit, addEventListener et d'un appel get ou set sur un objet, comme cookies().get(...). Seuls les arguments directs sont ignorés : le texte imbriqué plus profondément dans un tel appel, comme dans un callback (query(() => ({ message: "..." }))), un objet ou du JSX, reste signalé. Une fonction dont le nom se termine juste par hasard par Error, comme setError ou showError, n'est pas ignorée : le message que tu lui passes reste signalé.

Pour retenir un littéral, mets // verbatra-ignore-next-line au-dessus (en JSX, {/* verbatra-ignore-next-line */}), ou // verbatra-ignore-line à la fin de sa propre ligne. Une directive de ligne suivante vise la prochaine ligne qui contient du code (les lignes vides et celles qui ne contiennent que des commentaires sont sautées) et couvre chaque littéral qui commence sur cette ligne. Quand une balise ouvrante JSX y commence, elle couvre aussi tous ses attributs, même si la balise s'étend sur plusieurs lignes. Le texte et les éléments imbriqués des lignes suivantes ne sont pas couverts : donne à chacun sa propre directive. Pour une chaîne qui convient partout, comme un nom de marque, ajoute-la sous extract.literals.ignore dans le fichier de config. Une entrée correspond au texte tel qu'il est signalé, avec les références de caractères décodées : écris donc Tom & Jerry, pas Tom & Jerry. Un littéral retenu reste listé sous suppressed, avec la raison : rien ne disparaît en silence.

La vérification échoue quand elle trouve un littéral, et aussi quand un fichier n'a pas pu être analysé. Un fichier que l'analyseur ne peut pas lire jusqu'au bout (un commentaire ou un template literal non fermé, ou un élément JSX jamais fermé ou fermé par la balise d'un élément qui l'entoure), qu'il ne peut pas ouvrir du tout ou qu'il juge trop gros est listé comme non analysé et le reste de l'analyse continue, mais l'exécution n'est jamais signalée comme propre. Un type de fonction générique du genre type Fn = <T>(x: T) => T ou une liste de paramètres de type comme <const T extends object = {}>(x: T) => x dans un fichier .tsx est lu comme du code ordinaire et ne fait donc jamais échouer le fichier, et un élément avec des arguments de type de n'importe quelle longueur, comme <Table<Row>>, reste lu comme du JSX. Un projet sans bloc extract fait échouer la vérification avec un message qui nomme le bloc. Avec --json, l'analyse voyage dans l'enveloppe sous result.literals, répartie en findings, suppressed et diagnostics.

Exemples

# 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

Une exécution avec deux problèmes ressemble à ceci :

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)

Codes de sortie

La sortie 1 signifie "il s'est exécuté et a trouvé des problèmes". La sortie 2 est réservée au cas où doctor ne peut pas s'exécuter du tout : c'est pourquoi un fichier de config introuvable par la recherche est une vérification en échec et un code de sortie 1, alors qu'un chemin --config qui pointe dans le vide donne un code de sortie 2.

Voir aussi

• verbatra init génère la config et le .env.example que doctor valide.
• verbatra check est le contrôle de dérive à lancer une fois la configuration saine.
• Le fichier de configuration documente chaque clé que doctor valide.
• Fournisseurs liste la variable de clé d'API que lit chaque fournisseur.