La façon la plus rapide de convertir du TOML en YAML est la commande yq -oy '.' file.toml. Pour une conversion manuelle, mappez les en-têtes de table TOML [table] aux blocs indentés YAML, les tableaux TOML aux listes préfixées par un tiret, et citez toujours les chaînes ambiguës pour éviter le « problème de la Norvège ».
Conversion rapide : utiliser le CLI yq
TOML (Tom’s Obvious, Minimal Language) a atteint sa version 1.1.0 en décembre 2025, mais YAML reste la norme pour les pipelines CI/CD et les manifestes Kubernetes. L’outil yq gère la conversion en une seule commande.
Installer yq
| Plateforme | Commande |
|---|---|
| macOS/Linux | brew install yq |
| Windows | choco install yq |
| Python (pip) | pip install yq |
La version basée sur Go de Mike Farah est préférée pour sa rapidité. Comme indiqué dans la documentation yq de Mike Farah, l’outil décode la structure TOML et la réencode en YAML propre.
Exécuter la conversion
Afficher dans le terminal :
yq -oy '.' your-config.toml
Enregistrer dans un fichier :
yq -oy '.' your-config.toml > your-config.yaml
Le flag -oy définit le format de sortie en YAML. Il gère les paires clé-valeur, les tables imbriquées et les tableaux.
Carte de traduction syntaxique : structure TOML vers YAML
Le développeur Drew DeVault a noté que si TOML est populaire, YAML gère plus proprement l’imbrication profonde. Voici la correspondance exacte :
Tables vers clés indentées
TOML utilise des en-têtes entre crochets ; YAML utilise l’indentation.
| TOML | YAML |
|---|---|
[server] |
server: |
host = "127.0.0.1" |
host: 127.0.0.1 |
port = 8080 |
port: 8080 |
Différence critique : En TOML, l’indentation est cosmétique. En YAML, l’indentation est structurelle — un seul espace incorrect casse toute la configuration.
Tableaux vers listes préfixées par un tiret
TOML : ports = [ 8000, 8001 ]
YAML :
ports:
- 8000
- 8001
Comme l’explique Knightli.com, le « style bloc » de YAML rend les listes lisibles, à condition que l’alignement vertical soit cohérent.
Tables en ligne et clés pointées
| Construction TOML | Équivalent YAML |
|---|---|
[a.b.c] (en-tête pointée) |
a: → b: → c: (indentation imbriquée) |
point = { x = 1, y = 2 } (table en ligne) |
point: → x: 1 → y: 2 |
Cas d’utilisation concrets
Configuration du site statique Hugo
Hugo accepte hugo.toml, hugo.yaml ou hugo.json. La plupart des projets commencent avec TOML (par défaut), puis migrent vers YAML lorsque la configuration doit s’aligner sur des plateformes de déploiement comme Netlify ou GitHub Actions. Hammer Europe note que la commande hugo lit ces fichiers pour déterminer comment le Markdown est converti en site en ligne.
Packaging Python : pyproject.toml vers CI/CD YAML
La communauté Python a standardisé pyproject.toml via PEP 518. Ces paramètres doivent souvent être traduits en YAML pour les flux CI/CD de GitHub Actions. Pour les flux d’agents IA, CocoIndex indique que les configurations YAML optimisées peuvent réduire l’utilisation de tokens jusqu’à 70 %.
Le problème de la Norvège et autres pièges de conversion
Le bug du code pays NO
En YAML 1.1, les chaînes brutes comme NO, OFF et YES sont automatiquement converties en booléens false ou true. TOML évite cela en exigeant des guillemets pour toutes les chaînes. Lors de la conversion, citez toujours les valeurs ambiguës :
| Valeur | Interprétation YAML 1.1 | Correction |
|---|---|---|
NO |
false |
"NO" |
OFF |
false |
"OFF" |
YES |
true |
"YES" |
On |
true |
"On" |
YAML 1.2 (la spécification actuelle) corrige la plupart de ces conversions, mais de nombreux analyseurs utilisent encore le comportement 1.1 par défaut.
Erreurs d’indentation
Les analyseurs YAML rejettent les fichiers avec une indentation incohérente. Erreurs courantes :
- Mélanger tabulations et espaces (YAML interdit les tabulations)
- Utiliser 3 espaces dans un bloc et 2 dans un autre
- Éléments de liste désalignés
Génération assistée par IA
Des outils comme AgentBuilder permettent de décrire la configuration en langage naturel et de produire du YAML validé. Ce cycle « décrire → générer → valider » aide à éviter les erreurs d’indentation et le problème de la Norvège.
Conclusion
Utilisez yq -oy '.' file.toml pour la conversion automatisée. Pour le travail manuel, mappez les tables TOML en indentation YAML, les tableaux en listes préfixées par un tiret, et citez toujours les chaînes pouvant être confondues avec des booléens. Après toute conversion, validez le YAML avant le déploiement — un seul espace mal aligné ou un NO sans guillemets peut casser tout votre pipeline.
FAQ
YAML prend-il en charge les commentaires comme TOML ?
Oui. Les deux utilisent # pour les commentaires sur une seule ligne. Les commentaires YAML peuvent interférer avec l’analyse des chaînes multilignes, donc placez-les sur des lignes séparées en cas de doute.
Qu’est-ce que le « problème de la Norvège » en YAML ?
En YAML 1.1, les chaînes brutes comme NO (code pays de la Norvège) sont automatiquement converties en booléen false. TOML évite cela en exigeant des guillemets pour toutes les valeurs de chaîne. Lors de la conversion de TOML en YAML, enveloppez toute chaîne potentiellement ambiguë de guillemets.
Quel format gère mieux l’imbrication profonde ?
YAML. TOML nécessite de répéter de longs en-têtes comme [table.subtable.subsubtable] à chaque niveau, ce qui devient verbeux. YAML représente la même hiérarchie avec une indentation — plus compacte et lisible en profondeur.
Laisser un commentaire