XML
Traduisez le texte de n'importe quel document XML directement dans le fichier, en conservant sa déclaration, ses commentaires, ses attributs et sa mise en forme à l'octet près.
Le gestionnaire de fichiers xml traduit le texte des documents XML qu'aucun format dédié ne prend en charge, comme un export de contenu, un fichier d'aide ou un format de ressources personnalisé. Il écrit chaque traduction dans une copie du fichier source : la déclaration, le DOCTYPE, les commentaires, les instructions de traitement, les attributs, les espaces de noms et les caractères d'espacement restent ainsi inchangés. Seuls le texte traduit et les attributs que vous désignez sont modifiés.
Les ressources Android, XLIFF et les dictionnaires de pluriels Apple sont également en XML, mais disposent de leurs propres formats : Android, XLIFF et Apple stringsdict. Utilisez ces formats pour les fichiers concernés : ils prennent en compte les clés, les pluriels et l'état de chaque traduction.
Configurer la traduction XML #
Un fichier n'est traduit comme du XML générique que si son entrée dans la liste des fichiers définit "format": "xml". L'extension .xml ne suffit pas à sélectionner un format, car un fichier Android strings.xml utilise la même extension. La CLI ignore les fichiers .xml dont l'entrée ne précise aucun format et affiche un message ; la GitHub App les ignore également :
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"files": [{ "pattern": "content/en/*.xml", "format": "xml" }]
}Cette configuration écrit content/de/guide.xml et content/fr/guide.xml pour content/en/guide.xml. Les chemins cibles suivent les mêmes règles que pour JSON, décrites dans la section chemins de sortie, et targetPath permet de déclarer toute autre organisation. Un fichier appartient à la première entrée dont le motif le sélectionne. Conservez donc les ressources Android dans une entrée distincte avec "format": "android", et donnez à l'entrée xml un motif qui ne les sélectionne pas. La même configuration fonctionne dans la CLI et la GitHub App.
Ce qui est traduit #
Chaque élément contenant du texte constitue une unité. Un élément qui ne contient que d'autres éléments, des commentaires et des caractères d'espacement ne constitue pas une unité à lui seul : ce sont ses éléments enfants qui sont lus à la place.
<?xml version="1.0" encoding="UTF-8"?>
<help>
<!-- shown on the settings page -->
<topic id="sync">
<title>Sync your files</title>
<p>Click <b>Sync</b> to upload your <a href="/files">files</a> now.</p>
</topic>
</help>Ici, title constitue une unité et p une autre. Le commentaire, id et href ne sont pas envoyés pour traduction.
- Éléments en ligne. Un texte contenant des éléments, comme
pci-dessus, constitue une seule unité pour la phrase entière. Les éléments en ligne sont transmis au modèle sous forme de marqueurs qu'il peut déplacer, mais pas modifier. La traduction peut ainsi placerSyncetfileslà où la langue cible l'exige. Les commentaires et les instructions de traitement présents dans ce texte sont conservés de la même manière. - Caractères d'espacement. Un texte composé uniquement de caractères d'espacement, comme l'indentation entre les éléments, n'est jamais envoyé. Les caractères d'espacement qui entourent le texte restent dans le fichier, et ceux à l'intérieur du texte sont envoyés tels quels. Les caractères d'espacement ajoutés par la traduction autour de son texte sont supprimés.
- CDATA. Un texte constitué d'une seule section CDATA est traduit puis réécrit sous forme de section CDATA. Une section CDATA qui côtoie d'autres portions de texte est intégrée à ce texte et réécrite sous forme échappée, ce que XML interprète de la même manière.
- Références.
&,<,>,",'et les références de caractères telles que©sont décodés avant la traduction. Une entité déclarée dans le DOCTYPE, comme&brand;ou&product-name;, est protégée comme un marqueur et réécrite telle quelle. - Valeurs qui ne sont pas du texte courant. Un texte composé uniquement de chiffres, d'une URL, d'une date ISO ou d'un identifiant de 22 caractères alphanumériques est copié dans chaque cible au lieu d'être traduit.
Les noms et les chemins des éléments sont lus exactement tels qu'ils sont écrits, en respectant la casse et les préfixes d'espaces de noms.
Traduire les attributs #
Les valeurs des attributs ne sont jamais traduites, sauf si translateComponentProps désigne ces attributs. Une chaîne désigne un attribut sur tous les éléments ; un objet avec component ne le désigne que sur les éléments indiqués :
{
"pattern": "content/en/*.xml",
"format": "xml",
"translateComponentProps": ["title", { "component": "item", "props": ["label"] }]
}Cette configuration traduit tous les attributs title ainsi que l'attribut label des éléments <item>. Les noms doivent correspondre exactement à leur forme écrite : x:title et Title sont donc des attributs distincts. Les valeurs vides sont ignorées. Les identifiants, les liens, xml:lang et les déclarations d'espaces de noms ne sont traduits que si vous les désignez. En désigner un par erreur modifie donc la façon dont le fichier est lu.
Comment les traductions sont écrites #
Dans le texte traduit, &, < et > sont échappés. Dans un attribut traduit, &, < et le caractère de guillemet qui délimite l'attribut sont échappés. Les tabulations et les sauts de ligne sont écrits sous forme de références de caractères pour que XML les conserve. Un ]]> dans une section CDATA traduite est réparti sur deux sections. Les sauts de ligne d'une traduction utilisent la convention de fin de ligne du fichier. Les caractères de contrôle que XML ne peut pas contenir sont supprimés de la traduction.
Lorsque la déclaration indique un encodage autre que UTF-8, comme encoding="ISO-8859-1", les caractères non ASCII d'une traduction sont écrits sous forme de références de caractères, par exemple é pour é, afin que la cible reste lisible dans cet encodage. Le fichier est lu en UTF-8 : s'il déclare un autre encodage et contient des octets bruts représentant des lettres accentuées, une erreur indique la position du premier caractère concerné, et rien n'est écrit pour ce fichier. Enregistrez-le en UTF-8 ou écrivez ces caractères sous forme de références.
Le gestionnaire ne modifie pas xml:lang ni aucun autre attribut indiquant la langue du document. Mettez-le à jour lors de la compilation ou désignez-le dans translateComponentProps s'il contient du texte.
Clés et réutilisation #
Chaque unité possède une clé correspondant au chemin de son élément, écrit selon la syntaxe XPath : /help/topic/title, /list/item[2] ou /menu/item[1]/@label pour un attribut. Une position n'apparaît que lorsqu'un élément a des éléments frères portant le même nom. Ces clés identifient les unités dans la tâche et dans Studio.
Une unité conserve sa traduction existante tant que son texte et le chemin de son élément (hors positions) n’ont pas changé depuis le dernier envoi et que la traduction préserve les éléments en ligne du texte source ainsi que leur imbrication. Ces éléments peuvent apparaître dans un ordre différent dans la traduction, comme l’exige souvent l’ordre des mots dans la langue cible. Tout attribut traduit d’un élément en ligne se déplace avec cet élément. Lorsqu’un élément est inséré, seul ce nouvel élément est traduit ; les éléments qui le suivent conservent leurs traductions, même si leurs positions ont changé. Une traduction dont les éléments en ligne ne correspondent plus à ceux du texte source — par exemple, parce qu’une personne en a supprimé un ou l’a déplacé à l’intérieur d’un autre dans le texte cible — est traduite à nouveau.
Options non applicables #
XML ne prévoit pas de règles pour les clés. La CLI et la GitHub App refusent une entrée xml qui définit lockedKeys, preservedKeys, ignoredKeys, keyColumn, injectLocale ou translateFrontmatterFields, car le fichier serait sinon traduit comme si l'option n'était pas définie. lockedPatterns est refusé, comme pour tous les formats autres que les fichiers de propriétés Java.
lingo push --key ignore les fichiers xml en affichant un message et envoie les autres fichiers sélectionnés.
XML non valide #
Un fichier XML mal formé provoque une erreur indiquant la ligne et la colonne du premier problème : une balise non fermée ou ne correspondant pas à la balise d'ouverture, un & non échappé, deux éléments racines ou du texte en dehors de l'élément racine, par exemple. Si plusieurs balises sont encore ouvertes à la fin du fichier, l'erreur les indique à la place. Un fichier dont les éléments dépassent 256 niveaux d'imbrication provoque également une erreur. Rien n'est écrit pour ce fichier, et toute cible existante reste inchangée. Une cible mal formée provoque le même type d'erreur, avec indication de sa langue. Corrigez le XML, puis effectuez un nouvel envoi.