Markdoc
Traduisez le texte Markdoc et certains attributs textuels tout en préservant les annotations, les variables et le code.
Les annotations Markdoc relient le texte du document à des composants personnalisés et à des variables. Le gestionnaire de fichiers markdoc traduit le texte pris en charge et certains attributs de balise à valeur textuelle, tout en conservant les annotations nécessaires à votre moteur de rendu.
Sélectionner les propriétés visibles des balises #
Un document peut combiner des métadonnées visibles, un identifiant de mise en page fixe et un encadré :
---
title: Delivery options
description: Understand the available delivery methods.
layout: article
---
{% callout title="Delivery deadline" type="warning" %}
Confirm your address before checkout.
{% /callout %}Le paragraphe et les champs title et description des métadonnées d’en-tête, sélectionnés par défaut, constituent du texte. L’attribut title de la balise devient du contenu à traduire dès qu’une règle de sélection des propriétés le sélectionne. type="warning" et layout: article sont des identifiants structurels ; ne les sélectionnez pas, sauf si le composant qui les utilise attend explicitement des valeurs traduites.
Les règles peuvent cibler une propriété par son nom sur toutes les balises ou uniquement sur certaines balises désignées par leur nom. Privilégiez cette seconde option lorsque plusieurs balises utilisent le même attribut à des fins différentes. Les attributs numériques, booléens, dérivés de variables et les autres attributs dont la valeur n’est pas une chaîne ne constituent pas des unités de texte littéral.
Ce qui reste protégé #
Les blocs de code délimités et le code en ligne sont exclus de la traduction. Les liens conservent leur destination, tandis que leurs libellés peuvent changer. Les annotations en ligne et les images sont protégées au sein du texte qui les entoure. Les noms des balises et les attributs non sélectionnés restent dans le document. Le gestionnaire échappe les caractères des attributs textuels traduits pour respecter la syntaxe des guillemets de Markdoc, mais il ne fournit pas le schéma de balises personnalisées requis par votre moteur de rendu.
Les champs title et description des métadonnées d’en-tête sont sélectionnés par défaut. Une sélection vide les laisse inchangés. La sélection d’une structure associative ou d’une séquence inclut tous ses descendants scalaires. Choisissez des chemins précis, comme seo.title, lorsque les champs de routage ou les identifiants de contenu voisins doivent rester inchangés.
Préserver l’alignement entre la source et la cible #
La reconstruction remplace des segments de texte dans la source actuelle et peut réutiliser les formulations d’une version précédente de la source et de sa cible alignée. Si leurs structures en ligne protégées ne correspondent pas de façon fiable, la réutilisation peut échouer. Conservez la révision source associée à la traduction acceptée, en particulier après avoir déplacé des balises ou modifié des liens.
Ne partez pas du principe qu’un document .md contenant des annotations Markdoc utilisera ce gestionnaire. La CLI déduit le format Markdown pour .md ; sélectionnez explicitement le format lorsque le langage du document exige le traitement propre à Markdoc.
Configurer la traduction Markdoc #
La CLI déduit markdoc à partir de .mdoc ; la sélection par clé n’est pas disponible. Consultez la configuration de la CLI pour les métadonnées d’en-tête, la sélection des propriétés de balise et l’organisation des fichiers de destination, ou GitHub pour le workflow du dépôt.
Valider avec le schéma du site #
Le gestionnaire de fichiers ne configure ni les routes du framework, ni le chargement du contenu, ni les transformations Markdoc de votre application. Après récupération, analysez le document cible et effectuez son rendu avec les mêmes schémas que pour la source. Vérifiez les attributs visibles, les destinations des liens, les variables et les métadonnées d’en-tête sélectionnées, ainsi que les paragraphes traduits.