Ce que le moteur
refuse, et pourquoi
37 erreurs cataloguées en 11 familles. Chacune porte son code, sa conséquence réelle et sa correction — avec le fichier et la ligne. Le texte des messages vit dans un JSON, pas dans le code : cette page en est la mise en forme.
Le texte des erreurs vit dans un JSON
Aucun message d'erreur n'est écrit dans le code du moteur. Ils vivent tous dans noyau/erreurs.json — un fichier de données, au même titre que les jetons de design ou la médiathèque.
Le code se contente de nommer un code — TRA-001 — et d'y joindre le contexte du cas rencontré : quel fichier, quelle ligne, quelle valeur.
| Conséquence | Ce que cela permet |
|---|---|
| La documentation est le catalogue | un message ne peut pas diverger de ce que la documentation en dit — cette page est engendrée depuis le même fichier |
| Un agent IA peut lire le catalogue | il sait ce que le moteur refuse sans lancer de compilation |
| Ajouter une erreur est une opération de données | pas une modification du code |
37 erreurs cataloguées, réparties en 11 familles. Un code se lit AAA-nnn : les trois lettres nomment la famille, le nombre identifie la faute. Un agent peut s'y référer sans ambiguïté.
Ce qu'un rapport contient
Un message qui dit seulement « erreur de traduction » oblige à chercher. Chaque entrée porte donc quatre choses.
| Contenu | |
|---|---|
| OÙ | le fichier, et la ligne quand elle existe |
| QUOI | la valeur fautive, citée |
| POURQUOI | la conséquence réelle — pas la règle, la conséquence |
| COMMENT | la correction, avec les valeurs attendues |
$ ./verifier.sh
── cohérence des langues ──────────────────────────────────────────
✗ TRA-001 — Clé absente d'une traduction (5 cas)
Une clé existe dans la langue maîtresse mais pas dans cette langue.
de · site/textes/txt_de.json:11 « accueil.concept.chapo »
→ insérer avant la ligne 11 — valeur française :
« Kaina redonne confiance aux femmes traversant un mom »
de · site/textes/txt_de.json:119 « accueil.pour-qui.titre »
→ insérer avant la ligne 119 — valeur française :
« Pour celles qui ne se reconnaissent plus »
de · site/textes/txt_de.json:584 « kaina.description-seo »
de · site/textes/txt_de.json:1260 « pass-experience.titre-seo »
de · site/textes/txt_de.json:1428 « temoignage-camille.presentation.titre »
Pourquoi : Le convertisseur ne comble pas le trou avec la langue
maîtresse : une page mi-traduite est un signal de
mauvaise qualité, et un mélange de deux langues sur une
même page est pire qu'une page absente.
Corriger : Ajouter la clé au fichier de la langue, avec sa
traduction.
Source : https://developers.google.com/search/docs/specialty/…
✓ en 13 pages 325 Ko
✓ fr 13 pages 330 Ko
⚠ langue « de » : 5 textes manquants (99,7 % traduit) — non compilée.Une compilation ne s'arrête pas à la première faute. Elle les collecte toutes, puis rend un rapport complet. Corriger sept fautes une par une, en relançant à chaque fois, est le comportement qui fait abandonner les outils stricts.
Les cas répétitifs sont regroupés : cinquante clés manquantes forment un bloc, pas cinquante messages identiques.
Trois niveaux, trois conséquences
Toutes les fautes n'ont pas le même poids. La distinction la plus importante est la deuxième : une traduction en chantier ne doit pas bloquer la publication du site existant.
| Niveau | Effet | Nombre |
|---|---|---|
| Bloquant | La compilation s'arrête. Aucun fichier n'est écrit. | 30 |
| Bloque la langue | Seule la langue concernée n'est pas compilée. Les autres sont publiées normalement. | 2 |
| Alerte | La compilation continue. Signalé dans le rapport, à traiter. | 5 |
Traductions
cohérence entre les fichiers de langue — 4 codes
TRA-001 — Clé absente d'une traductionBloque la langue
Ce que cela signifie. Une clé existe dans la langue maîtresse mais pas dans cette langue.
Pourquoi c'est traité ainsi. Le convertisseur ne comble pas le trou avec la langue maîtresse : une page mi-traduite est un signal de mauvaise qualité, et un mélange de deux langues sur une même page est pire qu'une page absente.
Comment corriger. Ajouter la clé au fichier de la langue, avec sa traduction.
https://developers.google.com/search/docs/specialty/international/localized-versions
TRA-002 — Clé en trop dans une traductionAlerte
Ce que cela signifie. Une clé existe dans cette langue mais plus dans la langue maîtresse.
Pourquoi c'est traité ainsi. Elle n'est plus utilisée : c'est le reste d'un texte supprimé. Sans nettoyage, les fichiers de langue divergent lentement.
Comment corriger. Supprimer la clé, ou la rétablir dans la langue maîtresse si sa disparition est un oubli.
TRA-003 — Valeur identique à la langue maîtresseAlerte
Ce que cela signifie. Un texte long est rigoureusement identique à l'original.
Pourquoi c'est traité ainsi. Probable oubli de traduction. Certains cas sont légitimes — noms propres, URL, prix — d'où l'alerte plutôt que le blocage.
Comment corriger. Traduire, ou ignorer si la valeur ne doit pas l'être.
TRA-004 — Métadonnée SEO non traduiteAlerte
Ce que cela signifie. Un titre ou une description SEO est identique à la langue maîtresse.
Pourquoi c'est traité ainsi. C'est le seul point où une balise du <head> a un effet mesuré et documenté : un <title> non traduit déclenche activement sa réécriture par Google.
Comment corriger. Rédiger le titre et la description dans la langue cible — 30 à 60 caractères pour le titre, 120 à 155 pour la description.
https://developers.google.com/search/docs/appearance/title-link
Jetons de design
vocabulaire fermé des valeurs — 5 codes
JET-001 — Taille de texte sans composante remBloquant
Ce que cela signifie. Une taille en unités de fenêtre ne contient aucun rem ni em.
Pourquoi c'est traité ainsi. Au zoom 200 %, le texte ne grossit pas — il peut même rétrécir. Mesuré sur l'ancien site : un h1 passait de 152 px à 79 px.
Comment corriger. Mélanger rem et vw dans la composante fluide, par exemple clamp(2.9rem, 4rem + 5.9vw, 16rem).
JET-002 — Borne minimale en unités de fenêtreBloquant
Ce que cela signifie. Le premier terme d'un clamp() est en vw, vh, vmin ou vmax.
Pourquoi c'est traité ainsi. Sur un écran étroit le texte devient illisible, et le zoom ne le rattrape pas : la borne basse suit la fenêtre, pas le réglage de l'utilisateur.
Comment corriger. Exprimer la borne minimale en rem.
JET-003 — Composante fluide sans remBloquant
Ce que cela signifie. Le terme central d'un clamp() est en unités de fenêtre pures.
Pourquoi c'est traité ainsi. C'est ce terme qui pilote la taille sur la plage utile. En vw seul, il ignore le zoom du navigateur entre les deux bornes.
Comment corriger. Écrire par exemple 4rem + 5.9vw plutôt que 8vw.
JET-004 — Couleur non analysableBloquant
Ce que cela signifie. La valeur n'est pas une couleur CSS reconnue.
Pourquoi c'est traité ainsi. Le contraste ne peut pas être calculé, donc la conformité WCAG ne peut pas être garantie.
Comment corriger. Utiliser #rrggbb, rgb(), hsl(), oklch() ou transparent.
JET-005 — Jeton inconnuBloquant
Ce que cela signifie. Une valeur nommée qui n'existe dans aucune famille.
Pourquoi c'est traité ainsi. CSS ignore silencieusement une variable inconnue : la règle serait morte, sans erreur et sans effet visible.
Comment corriger. Vérifier l'orthographe. Le message liste les noms valides de la famille.
Contraste
calcul WCAG sur les valeurs réelles — 1 code
CTR-001 — Contraste insuffisantBloquant
Ce que cela signifie. Une paire de couleurs descend sous 4,5:1 (texte) ou 3:1 (interface).
Pourquoi c'est traité ainsi. Calculé à chaque compilation sur les valeurs réelles, pas déclaré. Échec WCAG 1.4.3, niveau AA.
Comment corriger. Assombrir le texte ou éclaircir le fond. Le message donne le rapport obtenu et le seuil.
Document
arbre et hiérarchie des titres — 3 codes
DOC-001 — Saut de niveau de titreBloquant
Ce que cela signifie. Un h3 suit un h1 sans h2 intermédiaire.
Pourquoi c'est traité ainsi. Faute d'accessibilité, pas de référencement : un lecteur d'écran annonce « titre niveau 3 » et l'utilisateur cherche la section qui n'existe pas. WCAG 1.3.1, niveau A.
Comment corriger. Le niveau étant calculé depuis l'arbre, cette faute vient d'un composant mal classé — pas d'une écriture.
https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships
DOC-002 — Zéro ou plusieurs h1Bloquant
Ce que cela signifie. La page produite ne contient pas exactement un h1.
Pourquoi c'est traité ainsi. Vérifié sur les OCTETS PRODUITS, pas sur l'arbre. C'est ce contrôle qui a rattrapé une page à deux h1 que le contrôle d'arbre avait laissé passer.
Comment corriger. Le message cite le texte de chaque h1 trouvé.
DOC-003 — Profondeur supérieure à sixBloquant
Ce que cela signifie. L'imbrication dépasse h6.
Pourquoi c'est traité ainsi. h7 n'existe pas dans la spécification HTML. Une arborescence si profonde est un défaut de conception du contenu.
Comment corriger. Aplatir la structure de la page.
Composants
vocabulaire du langage — 5 codes
CMP-001 — Composant inconnuBloquant
Ce que cela signifie. Le type nommé ne fait pas partie du vocabulaire.
Pourquoi c'est traité ainsi. Le langage a un vocabulaire fini : un type inconnu ne peut pas être rendu.
Comment corriger. Le message propose le composant le plus proche, ou liste ceux disponibles.
CMP-002 — Propriété non reconnueBloquant
Ce que cela signifie. Une propriété absente des listes obligatoire et facultative.
Pourquoi c'est traité ainsi. Une faute de frappe tolérée ferait disparaître du contenu EN SILENCE — le cas le plus coûteux, invisible à la compilation comme à la relecture.
Comment corriger. Le message propose la propriété la plus proche et liste les admises.
CMP-003 — Propriété obligatoire absenteBloquant
Ce que cela signifie. Un composant est déclaré sans une propriété qu'il exige.
Pourquoi c'est traité ainsi. Un bouton sans destination, une image sans source : le rendu serait incomplet.
Comment corriger. Ajouter la propriété nommée dans le message.
CMP-004 — Valeur hors vocabulaire ferméBloquant
Ce que cela signifie. Une propriété à liste finie reçoit une valeur non admise.
Pourquoi c'est traité ainsi. Chaque option d'un vocabulaire fermé est correcte par construction. Une valeur libre rouvrirait l'espace des fautes.
Comment corriger. Le message donne la valeur reçue et la liste des valeurs attendues.
CMP-005 — Contenu imbriqué refuséBloquant
Ce que cela signifie. Un composant qui n'accepte pas d'enfants en reçoit.
Pourquoi c'est traité ainsi. Le contenu serait ignoré silencieusement.
Comment corriger. Déplacer le contenu dans un composant conteneur.
Images
médiathèque et balise responsive — 6 codes
IMG-001 — Image absente de la médiathèqueBloquant
Ce que cela signifie. Le jeton d'image nommé n'existe pas.
Pourquoi c'est traité ainsi. Les pages nomment un emplacement, jamais un fichier : un jeton inconnu ne peut pas être résolu.
Comment corriger. Le message liste les emplacements connus.
IMG-002 — Texte alternatif absentBloquant
Ce que cela signifie. Une image n'a ni alt ni déclaration décorative.
Pourquoi c'est traité ainsi. Google documente le alt comme « the most important attribute » d'une image. Un alt manquant fait lire le NOM DU FICHIER par le lecteur d'écran — la distinction entre « rien à dire » et « oubli » ne peut pas être devinée.
Comment corriger. Renseigner le alt, ou déclarer l'image décorative explicitement.
https://developers.google.com/search/docs/appearance/google-images
IMG-003 — Dimensions absentesBloquant
Ce que cela signifie. Une image sans width ni height.
Pourquoi c'est traité ainsi. Le navigateur ne connaît pas le rapport d'aspect avant le téléchargement : il réserve zéro pixel puis pousse le contenu. Première cause de décalage de mise en page (CLS).
Comment corriger. Les dimensions viennent de la médiathèque — reconstruire l'entrée.
IMG-004 — Deux images prioritairesBloquant
Ce que cela signifie. Plus d'une image porte fetchpriority="high" sur la même page.
Pourquoi c'est traité ainsi. La priorité est RELATIVE : deux images prioritaires équivalent à aucune.
Comment corriger. Ne garder la priorité que sur l'image du hero.
IMG-005 — Aucune variante de repliBloquant
Ce que cela signifie. L'image n'a ni WebP ni JPEG sous son AVIF.
Pourquoi c'est traité ainsi. Un src AVIF nu est une image cassée sur Safari 16.3 et antérieur.
Comment corriger. Régénérer les variantes de l'image.
IMG-006 — Texte alternatif dupliquéAlerte
Ce que cela signifie. Deux images différentes portent le même texte alternatif.
Pourquoi c'est traité ainsi. Soit une description est trop générique, soit la même photo est entrée deux fois.
Comment corriger. Différencier les descriptions, ou fusionner les entrées.
En-tête
ordre du <head> et métadonnées — 3 codes
TET-001 — charset au-delà de 1024 octetsBloquant
Ce que cela signifie. La balise meta charset ne tient pas dans le premier kilo-octet.
Pourquoi c'est traité ainsi. Le navigateur redémarre l'analyse du document avec le bon encodage, et jette tout le travail déjà fait.
Comment corriger. Raccourcir ce qui précède dans le <head>.
https://html.spec.whatwg.org/multipage/semantics.html#charset
TET-002 — Viewport absent ou bloquant le zoomBloquant
Ce que cela signifie. Pas de meta viewport, ou présence de user-scalable=no.
Pourquoi c'est traité ainsi. Sans viewport, la page est rendue à 980 px puis réduite. Avec user-scalable=no, l'utilisateur ne peut plus zoomer : échec WCAG 1.4.4.
Comment corriger. Émettre width=device-width,initial-scale=1 sans restriction d'échelle.
TET-003 — Texte de page manquantBloque la langue
Ce que cela signifie. Une référence @clé ne trouve pas son texte.
Pourquoi c'est traité ainsi. La page afficherait la clé au lieu du mot.
Comment corriger. Ajouter la clé au fichier de la langue concernée.
Budgets
poids et nœuds DOM — 2 codes
BUD-001 — Page au-delà de 2 MoBloquant
Ce que cela signifie. Le HTML décompressé dépasse la limite de Googlebot.
Pourquoi c'est traité ainsi. Googlebot récupère les 2 premiers Mo puis interrompt : la suite n'est pas indexée. La limite s'applique aux données DÉCOMPRESSÉES — Brotli n'agrandit pas ce budget.
Comment corriger. Découper la page.
https://developers.google.com/search/docs/crawling-indexing/googlebot
BUD-002 — Nombre de nœuds DOM élevéAlerte
Ce que cela signifie. La page dépasse 800 nœuds.
Pourquoi c'est traité ainsi. Indicateur de coût de rendu, PAS un facteur de classement. Un annuaire dense peut légitimement dépasser le seuil.
Comment corriger. Alerte informative : à arbitrer, pas à corriger mécaniquement.
Sources
fichiers et structure du dépôt — 3 codes
SRC-001 — Fichier source introuvableBloquant
Ce que cela signifie. Un fichier attendu du dépôt est absent.
Pourquoi c'est traité ainsi. Le moteur ne devine pas une source manquante.
Comment corriger. Le message donne le chemin attendu.
SRC-002 — JSON invalideBloquant
Ce que cela signifie. Un fichier source n'est pas du JSON analysable.
Pourquoi c'est traité ainsi. Virgule finale, guillemet non fermé, commentaire — le JSON ne les tolère pas.
Comment corriger. Le message donne le fichier, la ligne et la colonne.
SRC-003 — Langue absente du catalogueBloquant
Ce que cela signifie. Un fichier txt_XX.json existe sans entrée dans le catalogue.
Pourquoi c'est traité ainsi. Le convertisseur ignore l'endonyme, le drapeau et le sens de lecture de cette langue.
Comment corriger. Ajouter la langue à site/langues/catalogue.json.
Annexes
robots.txt, sitemap, page 404 — 2 codes
ANX-001 — robots.txt fautifBloquant
Ce que cela signifie. Une directive obsolète, inefficace ou dangereuse.
Pourquoi c'est traité ainsi. Six fautes documentées, dont le blocage des ressources de rendu et le préfixe sans barre finale — « Disallow: /de » bloque aussi /design et /demo.
Comment corriger. Le message nomme la ligne et le motif.
ANX-002 — Page noindex dans le sitemapBloquant
Ce que cela signifie. Une page exclue de l'index figure au sitemap.
Pourquoi c'est traité ainsi. Contradiction : le sitemap propose une page que la page elle-même refuse.
Comment corriger. Retirer la page du sitemap, ou lever son noindex.
Éprouvé sur un cas réel
La traduction allemande a été produite avec sept défauts délibérés — cinq clés supprimées, deux valeurs laissées en français — pour vérifier que le moteur les nomme toutes, et correctement.
Résultat : 7 défauts posés, 7 détectés, chacun avec son fichier et sa ligne.
| Défaut posé | Code rendu | Effet |
|---|---|---|
| accueil.concept.chapo | TRA-001 | allemand non compilé ; français et anglais publiés normalement |
| accueil.pour-qui.titre | TRA-001 | |
| kaina.description-seo | TRA-001 | |
| pass-experience.titre-seo | TRA-001 | |
| temoignage-camille.presentation.titre | TRA-001 | |
| partenaires.inscription.chapo | TRA-003 | alerte — le site est publié |
| temoignages.presentation.chapo | TRA-003 | alerte — le site est publié |
Le test a aussi montré la reprise. Les cinq clés rétablies, l'allemand a compilé — sauf une, laissée en français exprès : elle est passée en TRA-004, distinct de TRA-003 parce qu'un <title> non traduit est le seul cas où une balise du <head> a un effet mesuré et documenté.
Un catalogue qui décrit des contrôles réels
Un catalogue qui décrirait des contrôles inexistants serait pire qu'une absence de catalogue : il donnerait une fausse assurance.
tests/audit_erreurs.py fabrique un défaut par code et vérifie que le moteur le refuse vraiment.
$ python3 tests/audit_erreurs.py
37 codes au catalogue · 21 éprouvés par un cas réel
✓ JET-001 Taille de texte sans composante rem
✓ JET-002 Borne minimale en unités de fenêtre
✓ JET-003 Composante fluide sans rem
✓ CTR-001 Contraste insuffisant
✓ DOC-001 Saut de niveau de titre
✓ DOC-002 Zéro ou plusieurs h1
✓ NAV-001 Règle CSS qui casse un moteur
✓ IMG-002 Texte alternatif absent
✓ ANX-001 robots.txt fautif
…
21 détectés · 0 non détectés · 16 hors de ce bancCe banc a trouvé un vrai défaut. Le contrôle des tailles ne vérifiait que la borne minimale d'un clamp(). Or c'est le terme central qui pilote la taille sur la plage utile : clamp(2rem, 8vw, 5rem) passait le contrôle tout en échouant au zoom. Le code JET-003 est né de cette découverte.