Gérer les projets de documentation multilingues DITA XML¶
DITA XML est un formidable format pour gérer les projets de documentation. Pour les projets multilingues, cependant, le rédacteur technique doit créer un fichier ditamap, qui contient la structure de table des matières des documents, par version. Ceci entraîne un risque d’erreurs et d’incohérences. Heureusement, une méthodologie appropriée et un script d’automatisation destiné à la chaîne de publication DITA-OT remédient à ce problème.
Méthodologie de gestion des projets de documentation multilingues DITA XML¶
Le fichier ditamap ne doit pas comporter de section navtitle, qui contient un titre en toutes lettres, au lieu d’extraire le titre de la section DITA XML correspondante, et est donc propre à chaque langue.
Dès le début de votre projet DITA XML, placez les fichiers de contenu DITA XML dans un sous-répertoire spécifique à la langue dans laquelle il est initialement rédigé.
Par exemple :
product
- en_US
- images
- tasks
- topics
et non :
- en_US
product
- images
- tasks
- topics
Remplacez dans le fichier ditamap toutes les occurrences du nom du répertoire propre à la langue par une chaîne unique provisoire.
Par exemple, utilisez la chaîne @language-code@ :
<topicref href="@language-code@/topics/managing-rights.dita"/>
et non :
<topicref href="en_US/topics/managing-rights.dita"/>
Pour générer les fichiers cibles, vous pouvez maintenant :
- modifier dans le fichier
demo/fo/build.xml
le paramètredefault.locale
, - remplacer dans le fichier ditamap la variable de langue par le nom du répertoire de langue,
- modifier le paramètre de langue
xml:lang
dans le fichier ditamap et dans les fichiers de contenu DITA XML, - pour les fichiers cibles PDF, modifier les dimensions de page (A4 ou US letter, par exemple) selon la langue,
- générer les fichiers cibles,
- rétablir les valeurs initiales dans les fichiers sources.
- modifier dans le fichier
Heureusement, un script Bash (GNU/Linux) simple permet d’automatiser cela.
Prérequis
- Vous avez installé DITA-OT.
- Votre projet DITA XML ne comporte qu’un fichier ditamap.
- Vos fichiers de contenu DITA XML ont l’extension
.dita
. - Les noms des répertoires des versions linguistiques correspondent aux codes de
langues supportés par Dita Open Toolkit (
fr_FR
ouen_US
, par exemple). - Vos fichiers de contenu DITA XML se trouvent dans des sous-répertoires des
répertoires des versions linguistiques (par exemple, dans
fr_FR/tasks/
etfr_FR/topics/
).
Les valeurs supportées pour la dimension des pages PDF sont fr_FR
(A4)
et en_US
(US letter). Ce script peut être bien entendu facilement
adapté, ou inspirer un nouveau script.
Attention
Ce script est fourni sans garantie. Avant toute exécution de ce script, effectuez une sauvegarde de l’ensemble de votre projet DITA XML, fichiers de configuration inclus (par exemple sous un système de gestion de versions). Assurez-vous de pouvoir restaurer facilement le projet dans son intégralité en cas d’erreur ou de comportement inattendu.
Pour utiliser ce script :
Téléchargez le script de génération multilingue DITA XML dans le répertoire contenant le fichier ditamap du projet.
Dans un terminal, placez-vous dans ce répertoire, puis entrez :
$ chmod +x dita2target.sh
Dans le terminal, entrez :
$ mkdir out
pour créer le répertoire qui contiendra les fichiers cibles.
Entrez :
$ ./dita2target.sh <fichier ditamap> \ <nom du répertoire de langue> <format cible>
pour générer les fichiers cibles.
L’argument format cible accepte les valeurs gérées par DITA-OT.
Exemple
./dita2target.sh firewall.ditamap en_US pdf2
Le fichier PDF
firewall.pdf
est alors généré dans le répertoireout
(spécifié en dur dans le script).