Un EPUB peut s'ouvrir dans votre application de lecture et pourtant échouer à la validation. Parfois, le même message apparaît sur plusieurs chapitres ; parfois, un seul défaut du paquet provoque une longue liste d'erreurs. La bonne méthode n'est pas de supprimer toutes les lignes signalées une à une : il faut identifier la cause, corriger l'édition source, puis valider la nouvelle exportation.

EPUBCheck est le vérificateur de conformité EPUB maintenu par le DAISY Consortium pour le W3C. Il signale des écarts à la spécification, mais n'évalue pas l'intégralité de l'expérience de lecture ni la pertinence des choix éditoriaux. https://www.w3.org/publishing/epubcheck/

Apprendre à lire une ligne EPUBCheck

La sortie habituelle associe une gravité, un code, un chemin et un message. Exemple tiré de la documentation officielle :

ERROR(RSC-001): ./manifest-item-missing-error.epub(-1,-1): File "EPUB/missing.xhtml" could not be found.

ERROR désigne la gravité ; RSC-001, le code ; le chemin indique l'emplacement concerné. Les numéros -1,-1 signalent qu'aucune localisation ligne/colonne précise n'est possible. La documentation EPUBCheck — Running explique cette structure.

Le libellé précis peut varier selon la version et la langue du logiciel. Pour vérifier la signification d'un code, consultez la liste de référence officielle, pas une capture d'écran ancienne.

1. RSC-001 et RSC-007 : ressource manquante

RSC-001 signale un fichier introuvable ; RSC-007, une ressource référencée qui n'existe pas dans le conteneur EPUB. Une image déplacée, une différence de majuscule ou un ancien nom de chapitre peuvent suffire.

Supposons que Text/chapitre-01.xhtml contienne :

<img src="../Images/carte.png" alt="Carte des lieux cités dans le récit" />

Mais le ZIP comporte EPUB/Images/Carte.png. Selon les environnements, la casse du nom peut provoquer une référence brisée. Deux corrections possibles : renommer physiquement le fichier pour faire correspondre le chemin ou changer la référence dans le XHTML. Vérifiez également que la ressource est déclarée dans le manifest du paquet OPF.

À ne pas faire : ajouter un fichier image vide simplement pour supprimer l'erreur. Vous pourriez obtenir un EPUB techniquement plus calme mais éditorialement incomplet.

2. RSC-008 : fichier présent, mais absent du manifest

Le manifest dans content.opf énumère les ressources de la publication. Un fichier peut être correctement présent dans l'archive et être néanmoins absent de la déclaration. Le code RSC-008 concerne une référence à une ressource non déclarée dans le manifest OPF.

Exemple de déclaration de ressource :

<manifest>
  <item id="chap01" href="Text/chapitre-01.xhtml"
        media-type="application/xhtml+xml" />
  <item id="carte" href="Images/carte.png"
        media-type="image/png" />
</manifest>

Les chemins href sont relatifs à l'emplacement du document OPF. Le bon correctif ne consiste donc pas à copier partout un chemin trouvé dans une page XHTML : le chemin doit être recalculé depuis le fichier qui l'emploie.

Après correction, vérifiez que le media-type correspond au contenu réel et qu'il n'existe pas une seconde déclaration inutile de la même ressource.

3. RSC-012 : une ancre interne ne mène nulle part

Les liens internes d'un EPUB reposent souvent sur des identifiants id. Un sommaire peut pointer vers chapitre-02.xhtml#section-3 alors que le titre porte id="section-03".

<!-- Lien dans la navigation -->
<a href="chapitre-02.xhtml#section-3">Troisième section</a>

<!-- Cible réelle -->
<h2 id="section-03">Troisième section</h2>

Le lien et sa cible doivent désigner le même identifiant. Attention aux changements introduits par le logiciel d'export : un identifiant généré automatiquement peut être remplacé lors d'une nouvelle compilation du livre.

Vérification utile : ouvrir le sommaire depuis une application de lecture, atteindre le chapitre, puis revenir au sommaire. Une validation sans erreur ne remplace pas ce test fonctionnel.

4. OPF_049 : une référence du spine ne correspond à aucun item

Le spine désigne les éléments qui constituent l'ordre principal de lecture. Ses itemref utilisent les identifiants id du manifest. Si un idref ne correspond à aucun item déclaré, EPUBCheck peut émettre OPF_049.

<manifest>
  <item id="texte-1" href="Text/01.xhtml"
        media-type="application/xhtml+xml" />
</manifest>
<spine>
  <itemref idref="texte-01" />
</spine>

Ici, texte-1 et texte-01 sont différents. Il faut aligner les identifiants, pas créer un deuxième chapitre artificiel. Ensuite, confirmez que le document appartient effectivement à l'ordre de lecture voulu et qu'il s'ouvre dans le lecteur.

5. PKG_006 et PKG_007 : le conteneur n'est pas un EPUB valide

Un EPUB est un conteneur ZIP qui suit des règles précises. Le fichier mimetype doit être présent, placé correctement et contenir exactement la chaîne application/epub+zip. PKG_006 et PKG_007 signalent des problèmes liés à ces exigences.

Un problème fréquent survient lorsqu'on décompresse un EPUB, modifie quelques fichiers, puis le recompresse comme un ZIP ordinaire : le paquet peut paraître complet à l'œil, mais ne plus respecter les contraintes du conteneur.

Si vous disposez du projet source, réexportez avec un outil EPUB fiable plutôt que de reconstruire manuellement l'archive. Si vous devez produire le conteneur vous-même, suivez la spécification OCF et vérifiez immédiatement le résultat avec EPUBCheck.

6. Une déclaration ne suffit pas : CSS, médias et métadonnées

Une erreur CSS, une déclaration de type MIME ou une image corrompue peuvent produire des messages différents selon le contexte. N'inventez pas de correspondance rigide « un code = une retouche ». Un échec du parseur CSS demande par exemple de vérifier la syntaxe, les caractères et les ressources utilisées, alors qu'un message informatif sur une propriété CSS peut seulement inviter à tester le rendu sur les dispositifs cibles.

Le diagnostic correct repose sur les fichiers réels et sur la version du validateur. Si une erreur subsiste après correction, commencez par confirmer que vous avez réanalysé le bon fichier : il est fréquent de confondre un EPUB corrigé et celui qui avait été exporté auparavant.

Comment décider quoi corriger en premier ?

Famille Exemple de code Priorité pratique habituelle
Fichier absent RSC-001, RSC-007 Examiner immédiatement : pages et images peuvent manquer
Déclaration OPF incohérente RSC-008, OPF_049 Corriger la structure et réexporter
Ancre non résolue RSC-012 Corriger avant de valider la navigation
Conteneur mal construit PKG_006, PKG_007 Reconstruire un EPUB conforme
Avertissement de compatibilité Code dépendant du défaut Évaluer le rendu sur les canaux concernés

La gravité officielle du code reste celle indiquée par EPUBCheck ; la colonne de droite est une aide de travail, pas une classification normative universelle.

Procédure de réparation et de contrôle en six étapes

  1. Sauvegardez l'EPUB original et les résultats du validateur.
  2. Repérez dans l'archive le chemin et la ressource mentionnés.
  3. Recherchez la cause dans le projet source, l'export ou le manifest.
  4. Corrigez les références et réexportez si possible.
  5. Relancez EPUBCheck, puis un contrôle d'accessibilité avec Ace by DAISY.
  6. Testez sur les systèmes de lecture pertinents et vérifiez les fichiers effectivement distribués.

Pour analyser votre propre fichier, Nommera Prism propose une première synthèse gratuite. Si vous avez déjà votre rapport, voyez comment le lire et organiser les corrections. Pour un protocole plus large, consultez la documentation officielle de DAISY sur la validation EPUB.

Questions fréquentes

Une erreur EPUBCheck empêche-t-elle systématiquement la publication ?

Une erreur de conformité doit être corrigée pour obtenir un EPUB valide. L'acceptation effective dépend aussi du canal et de ses vérifications supplémentaires ; il ne faut pas confondre ces deux questions.

Pourquoi EPUBCheck affiche-t-il plusieurs erreurs pour un seul fichier ?

Une même cause, comme une ressource renommée mais encore référencée, peut provoquer plusieurs messages dans l'OPF, le XHTML et la navigation.

Est-ce que je peux corriger directement le fichier EPUB compressé ?

C'est possible dans certaines conditions, mais une manipulation incorrecte du conteneur peut créer de nouvelles erreurs. Un réexport depuis le projet source est généralement plus sûr.

Peut-on corriger le message en remplaçant simplement le nom du fichier ?

Seulement si vous avez vérifié toutes les références relatives et les déclarations concernées. Le bon correctif dépend de l'usage réel du fichier.

Sources