Migration de contenu Drupal : méthodes

Migrer le contenu d'un site vers Drupal est rarement le simple transfert qu'on imagine au départ. Derrière chaque article, chaque fiche produit et chaque page se cachent des médias, des références entre entités, des taxonomies et parfois des traductions. Le choix de la méthode de migration conditionne directement la fidélité du résultat, le temps passé et la capacité à rejouer l'opération autant de fois que nécessaire. Ce n'est pas une décision technique à reléguer en fin de projet, c'est un arbitrage qui mérite d'être posé tôt.

La bonne nouvelle, c'est que Drupal dispose d'un outillage de migration parmi les plus matures de l'écosystème CMS. Migrate API est intégré au core, les modules contrib couvrent la plupart des sources courantes et les scripts custom prennent le relais pour les cas exotiques. Cet article passe en revue les différentes approches, explique quand utiliser chacune, détaille les pièges qui font dérailler les projets de migration et propose une méthode pour valider que le contenu migré est complet et fidèle.

Les quatre grandes approches de migration

Il n'existe pas une seule bonne façon de migrer du contenu. Le bon choix dépend du volume, de la complexité des données, de la fréquence à laquelle l'opération devra être rejouée et de la qualité de la source. Voici les quatre approches qui couvrent la quasi-totalité des projets.

Migrate API (natif au core). C'est l'outil de référence pour toute migration sérieuse vers Drupal. Migrate API décrit la migration sous forme de configuration : une source (base de données, CSV, JSON, XML), une série de process plugins qui transforment chaque champ et une destination (un type d'entité Drupal). L'opération est idempotente, traçable et rejouable. C'est le choix par défaut dès que le volume dépasse quelques dizaines d'éléments ou que la migration devra être exécutée plusieurs fois.

Modules contrib (Feeds, Migrate Source CSV, Migrate Plus). Pour les cas où l'on veut éviter d'écrire du code, des modules comme Feeds permettent de mapper un fichier ou un flux vers des entités Drupal via une interface d'administration. Migrate Plus et Migrate Tools étendent quant à eux Migrate API avec des sources supplémentaires (JSON, XML, SOAP) et des commandes Drush. Ces modules sont parfaits pour les imports récurrents et les sources structurées que des intégrateurs non développeurs doivent pouvoir piloter.

Scripts custom. Quand la source est vraiment particulière (une API propriétaire, un format de fichier maison, une logique de transformation métier complexe), un script qui utilise l'API d'entités de Drupal reste l'option la plus directe. On garde le contrôle total, mais on perd l'idempotence et la traçabilité offertes par Migrate API. À réserver aux cas que les approches précédentes ne couvrent pas proprement.

Migration manuelle. Pour un faible volume (quelques dizaines de pages éditoriales très soignées), la saisie manuelle reste pertinente. Elle évite tout l'investissement d'outillage et permet de retravailler le contenu au passage. Au-delà d'une centaine d'éléments ou dès qu'il faut rejouer l'opération, elle devient vite ingérable.

Quand utiliser quelle méthode

Le choix se joue sur quelques critères simples. Le volume d'abord : en dessous de cinquante éléments, la migration manuelle ou un import Feeds suffisent souvent. Au-delà, Migrate API s'impose. La récurrence ensuite : si la migration doit être rejouée plusieurs fois (synchronisation continue, imports périodiques), seuls Migrate API et les modules contrib offrent la fiabilité nécessaire.

La complexité des transformations pèse aussi lourd. Si chaque champ source correspond à un champ Drupal sans logique particulière, Feeds fait l'affaire. Si les transformations sont riches (concaténer des champs, résoudre des références, normaliser des dates, découper du HTML), Migrate API avec ses process plugins est nettement plus confortable.

Enfin, la qualité de la source détermine beaucoup. Une base de données propre et bien structurée se prête à une migration automatisée fluide. Une source hétérogène, avec des données incohérentes accumulées sur dix ans, demandera une phase de nettoyage préalable que ni l'outil ni la méthode ne remplaceront. Dans la pratique, près de la moitié de l'effort d'une migration se concentre sur la compréhension et le nettoyage des données source, pas sur l'écriture des migrations elles-mêmes.

Un exemple minimal de migration Migrate API depuis un CSV donne une idée de la structure :

id: articles_legacy
label: 'Import des articles depuis le CSV legacy'
source:
  plugin: csv
  path: 'private://import/articles.csv'
  ids: [id]
process:
  title: titre
  body/value: contenu
  body/format:
    plugin: default_value
    default_value: full_html
  field_tags:
    plugin: migration_lookup
    migration: taxonomie_themes
    source: theme_id
destination:
  plugin: 'entity:node'
  default_bundle: article
migration_dependencies:
  required:
    - taxonomie_themes

Les pièges qui font dérailler une migration

C'est souvent dans les détails que les projets de migration prennent du retard. Quatre familles de problèmes reviennent systématiquement et méritent d'être anticipées dès la conception.

Les médias. Les images, PDF et autres fichiers sont rarement de simples chaînes de caractères. Dans Drupal moderne, un média est une entité à part entière, avec ses propres champs et son fichier rattaché. Migrer un article sans migrer correctement ses médias produit des contenus tronqués. Il faut prévoir une migration dédiée aux fichiers et aux entités média, puis lier les contenus à ces médias via une résolution de référence. Le téléchargement des fichiers depuis l'ancien site, la gestion des chemins et la déduplication sont autant de points à traiter explicitement.

Les références entre entités. Un article référence un auteur, des tags, des contenus liés. Au moment où l'on migre l'article, les entités référencées doivent déjà exister ou être créées dans le bon ordre. Le process plugin migration_lookup et les migration_dependencies servent exactement à ça : ils garantissent que les taxonomies et les utilisateurs sont migrés avant les contenus qui les référencent. Oublier cet ordonnancement produit des références cassées, souvent silencieuses.

Les taxonomies. Les arborescences de termes posent un double défi : conserver la hiérarchie parent-enfant et éviter de créer des doublons. Une migration de taxonomie doit traiter les termes parents avant leurs enfants et mapper correctement les anciens identifiants vers les nouveaux. C'est un cas où l'idempotence de Migrate API fait toute la différence : on peut rejouer la migration sans dupliquer les termes.

Les traductions. Sur un site multilingue, chaque contenu existe en plusieurs versions liées entre elles. Migrer les traductions implique de migrer d'abord la langue par défaut, puis d'attacher les traductions au bon contenu source via les destinations de traduction de Migrate API. Une migration qui ignore cette mécanique produit des contenus dupliqués au lieu de traductions liées, ce qui casse l'expérience multilingue et le SEO.

Valider que le contenu est complet et fidèle

Une migration n'est terminée que lorsqu'on a prouvé que le résultat est fidèle à la source. La validation ne se fait pas à l'œil sur trois pages prises au hasard, elle se structure.

Le décompte. La première vérification est quantitative : combien d'éléments dans la source, combien créés dans Drupal ? Drush expose ces chiffres directement :

drush migrate:status
drush migrate:messages articles_legacy

Tout écart entre le nombre de lignes source et le nombre d'entités créées signale un problème : des lignes ignorées, des doublons ou des erreurs de validation. Les messages de migration listent précisément les lignes en échec et leur cause.

La vérification champ par champ. Sur un échantillon représentatif (et systématiquement sur les contenus les plus complexes), on compare chaque champ entre l'ancien et le nouveau site : titre, corps, médias, références, dates de publication, statut. L'objectif est de débusquer les transformations silencieuses, comme un format de texte mal mappé qui afficherait du HTML brut.

Les liens et les médias. Un crawl du nouveau site permet de détecter les liens internes cassés et les images manquantes. C'est souvent là que se révèlent les références non résolues et les fichiers oubliés en cours de route.

Les tests automatisés. Pour les migrations qui seront rejouées, écrire quelques tests qui vérifient la présence et la cohérence du contenu migré transforme la validation manuelle en filet de sécurité permanent. C'est exactement le terrain de nos tests automatisés Drupal, qui valident en quelques minutes que les parcours et les contenus critiques restent intacts après chaque exécution.

La règle pratique : on ne déclare jamais une migration réussie sur la foi d'un import qui se termine sans erreur. L'absence d'erreur technique ne garantit pas la fidélité éditoriale. Seule la comparaison structurée entre source et destination le fait.

Une migration de contenu réussie est une migration rejouable

Le meilleur indicateur de la qualité d'une migration n'est pas qu'elle fonctionne une fois, mais qu'on puisse la rejouer à volonté. Une migration rejouable permet de répéter l'opération sur un environnement de préproduction, de corriger un mapping et de relancer sans repartir de zéro, puis de basculer en production en confiance le jour J. C'est précisément ce que Migrate API apporte et ce qui justifie d'y investir, même quand un script rapide semblerait suffire.

Cette logique s'inscrit dans une démarche de migration Drupal plus large, où la migration de contenu côtoie la migration de la version du core, des modules et du thème. Aborder les deux ensemble, avec le bon outillage et une validation rigoureuse, évite les mauvaises surprises et sécurise durablement le passage vers la nouvelle plateforme.

Vous préparez une migration de contenu vers Drupal et vous hésitez sur la méthode? Parlons de votre projet : on évalue vos sources, on choisit l'approche adaptée et on bâtit un plan de migration fidèle et rejouable.