Coast Systems

Antora multilingue

Antora est le générateur de site statique de choix pour AsciiDoc et la documentation technique. Cependant, tel quel, Antora ne prend pas en charge la documentation multilingue. Cela dit, avec quelques ajustements, un site multilingue est possible, mais encore avec quelques réserves. On trouvera ici quelques commentaires ainsi qu’une interface par défaut d’Antora modifiée pour la prise en charge du multilingue, en utilisant la version comme indicateur de langue.

ATTENTION
Attention
Cet article est un travail en cours. Et il existe probablement plusieurs façons de faire. Ce qui suit est une tentative, et à ce stade je ne suis pas sûr que ce soit la meilleure. Je corrigerai certainement les choses au fur et à mesure que je les comprendrai ! Toute suggestion ou demande de fusion est la bienvenue !

La langue par la version

Il a été suggéré, dans les discussions de la communauté, que la version d’Antora serve de sélecteur de langue. Cela semble raisonnable, car cela permet encore d’avoir différents composants pour le site, par exemple blog, livre et documentation.

De plus, si vous traduisez réellement la documentation de versions logicielles, vous pourrez peut-être simplement ajouter le symbole de langue à la version du logiciel. Comme je ne versionne pas ma documentation, je n’ai pas à le faire et ne pourrai pas commenter l’efficacité de cette approche pour l’instant. Et comme ici nous utilisons la version dans l’en-tête HTML et ailleurs pour désigner la « langue », cela posera problème.

Je vais mettre cela de côté pour l’instant…​

En revanche, si vous n’avez pas de versions dans vos documents, par exemple un blog, un livre ou un autre support, le sélecteur de version fonctionne très bien avec les symboles de langue ISO, sans changements significatifs de l’interface. Le sélecteur de version par défaut, en bas à gauche et en haut à droite, devient simplement le « sélecteur de langue ». En outre, le sélecteur de « langue » de la barre d’outils grise les langues pour lesquelles le document courant n’a pas de traduction. Il agit comme un commutateur de langue du document, tandis que le commutateur de composant/version (désormais langue), en bas à gauche, change la langue du site et vous laisse sur la page d’accueil. Cela fonctionne tout simplement ! Belle fonctionnalité, à mon avis !

Vous pouvez aussi définir la version comme symbole ISO de langue à deux ou trois lettres, et display_version comme le nom de la langue dans la configuration YAML source du document. Comme display_version est facultatif, vous avez le choix d’utiliser le symbole ou le nom de la langue dans les sélecteurs de langue version.

en_US ou en_CA ou en ?

Je recommanderais d’utiliser « en » plutôt que « en_US ».

Le premier est le code de langue, le second est le « locale », qui désigne aussi le pays et les aspects culturels de la langue. C’est significatif, et pas seulement une préférence.

Par exemple, une documentation écrite pour fr_CA devrait exiger des accents sur les majuscules (É vs E), tandis que fr_FR accepte mais n'exige pas cela. fr_CA utilisera du papier format lettre et la virgule comme séparateur de milliers, et, bien que ce ne soit pas spécifié dans la locale, du 100 V pour les machines à espresso. fr_FR utilisera du papier A4, l’espace comme séparateur de milliers et du 220 V, ce qui fait un bien meilleur espresso. Les sites web commerciaux doivent en tenir compte pour leurs clients potentiels, et peut-être que le vôtre aussi.

Un autre point important à garder à l’esprit : les utilisateurs en en_CA, en_GB et en_AU peuvent très bien régler leur préférence de navigation, leur application Android ou autre sur :

  1. en_CA < langue du pays d’origine

  2. en < la langue elle-même

  3. en_US < anglais américain

Si vous voulez toucher le public le plus large pour votre langue, vous devriez utiliser html="en" dans votre en-tête, puis ajouter des balises de métadonnées de locale pour en_US selon les besoins. Le même principe s’applique bien sûr à fr, fr_FR, fr_CA et bien d’autres langues.

Ordre de tri version/langue

L’ordre de tri des versions ne semble pas configurable. (https://docs.antora.org/antora/latest/how-component-versions-are-sorted/).

component Cela crée une situation où la langue « par défaut » du menu Explorateur de navigation (en bas à gauche) n’est pas facilement configurable. Le tri se fait dans l’ordre inverse, ce qui peut être un obstacle majeur pour certains. J’ai quatre langues sur mon site personnel, et la plus obscure, commençant par W, est listée en premier. Tant pis…​

Je préférerais de loin que le français ou l’anglais soit listé en premier, mais il semble que ce ne soit tout simplement pas possible.

Le seul contournement à peu près acceptable que j’aie trouvé consiste à définir un start_page dans le playbook sur lang@component:module:page.adoc. (Dans le cas de ce site, en@) Ainsi, le composant s’ouvre au moins initialement sur la langue spécifiée.

Normalement, une liste de langues politiquement correcte devrait être alphabétique (avec peut-être une langue par défaut en tête). Quoi qu’il en soit, si l’ordre de tri des langues est important, utiliser la « version » comme symbole de langue pourrait poser un vrai problème.

(Si quelqu’un a des suggestions d’autres contournements, merci de me le faire savoir.)

NOTE
Note

2022-02-08 : j’ai enfin trouvé une solution à ce problème.

La liste des versions de composants est en fait déjà une colonne flex. Il suffit d’ajuster le CSS en column-reverse pour résoudre en grande partie le problème de l’ordre des langues. Rappelez-vous simplement que les langues sont triées par nom de version (qui, dans mon cas, est le code ISO). Ce n’est peut-être pas l’ordre requis par la langue d'« affichage ». Mais c’est une énorme amélioration.

Composants

Les composants (c’est-à-dire les sections du site pour les lecteurs non Antora) posent aussi quelques problèmes sans ajustements. Plus important encore, le composant de l’interface par défaut ne se « traduit » pas. Vous pouvez bien sûr le traduire dans le fichier de configuration, mais Antora n’affichera que la valeur du « premier » composant, avec toutes les « langues ». component Cela a bien sûr parfaitement de sens pour la documentation technique de versions logicielles. Le composant ne change pas entre v1 et v1.2. Mais dans de nombreuses situations, le composant ou la section est un terme ou un titre significatif et traduisible qui doit être traduit.

Heureusement, un petit ajustement du modèle nav-explorer peut totalement corriger cela. C’est ce qui est fait dans l’interface ci-dessous.

Plus important encore, un autre problème : lorsqu’un utilisateur clique sur un composant dans le menu explorateur de composants, la page s’affiche dans la version/langue « par défaut » de ce composant. C’est tout à fait normal lorsque vos composants sont des « docs logicielles » unilingues. Lorsque vous cliquez sur un autre composant, la version du composant courant n’a pas d’importance. Mais si la « version » est une langue, c’est l’inverse. Un utilisateur italien ne s’attend pas, en cliquant sur un autre composant (par exemple blog ou docs), à ce que la langue bascule en anglais, d’autant plus lorsque les documents existent en italien.

Quelques ajustements ont été apportés au modèle pour utiliser la version/langue courante avec les composants du menu explorateur. Cela préserve la langue de l’utilisateur. Si la langue n’existe pas pour un composant donné, l’utilisateur obtient simplement une erreur « page non trouvée ». C’est très bien.

<div class="nav-panel-explore{{#unless page.navigation}} is-active{{/unless}}" data-panel="explore">
  {{#if page.component}}
  <div class="context">
    {{#with @root.page.componentVersion}} 1
    <span class="title">{{./title}}</span>
    {{/with}}
    <span class="version"><img class=icon src="../../_/img/globe.svg">&nbsp;{{page.componentVersion.displayVersion}}</span> 2
  </div>
  {{/if}}
  <ul class="components">
    {{#each site.components}}
    <li class="component{{#if (eq this @root.page.component)}} is-current{{/if}}">
    {{#with @root.page.componentVersion}}
      <a class="title" href="{{{@root.site.url}}}/{{./name}}/{{{@root.page.version}}}">{{{./title}}}</a> 3
    {{/with}}
      <ul class="versions">
        {{#each ./versions}}
        <li class="version
          {{~#if (and (eq .. @root.page.component) (eq this @root.page.componentVersion))}} is-current{{/if~}}
          {{~#if (eq this ../latest)}} is-latest{{/if}}">
          <a href="{{{relativize ./url}}}">{{./displayVersion}}</a>
        </li>
        {{/each}}
      </ul>
    </li>
    {{/each}}
  </ul>
</div>
1 Traduit le titre du composant dans la langue courante
2 Icône de langue (globe)
3 Utilise la langue de la page courante pour le composant sélectionné

SEO et métadonnées

<html lang="??">

Des métadonnées de langue correctes sont extrêmement importantes pour le SEO. Voir : https://www.w3.org/International/techniques/authoring-html#language.

Alors qu’Asciidoctor vous donnera un html=CodeISODeVotreDocument dans la section head, Antora, tel quel, vous donnera <html lang="en"> pour chaque document, quel qu’il soit.

Si vous utilisez un code de langue ISO comme « version », ce qui suit peut être placé dans le modèle de mise en page par défaut afin que chaque document reçoive son identifiant de langue correct.

<!DOCTYPE html>
{{#with (or page.attributes.lang page.version)}}
<html lang={{this}}>
{{/with}}
  <head>
{{> head defaultPageTitle='Untitled'}}
  </head>
  <body class="article{{#with (or page.attributes.role page.role)}} {{{this}}}{{/with}}">
{{> header}}
{{> body}}
{{> footer}}
  </body>
</html>

Avec le code ci-dessus, si vous avez un attribut :page-lang: défini dans votre document, il peut remplacer la langue de la « version » et vous permettre d’avoir une page exceptionnelle en anglais dans la « version » française si nécessaire.

Traductions de métadonnées alternatives

Idéalement, il devrait aussi y avoir des <links> de métadonnées pointant vers toutes les pages traduites disponibles pour une page donnée. J’ai cela partiellement fonctionnel, mais cela demande encore du travail. Idéalement, il faudrait des liens comme ceci dans les métadonnées d’en-tête de la page anglaise :

<link rel="alternate" hreflang="dyu" href="https://coastsystems.net/blog/dyu/" title="Kunafoni Julankan"> <link rel="alternate" hreflang="fr" href="https://coastsystems.net/blog/fr/" title="Article de blog français">

Le code suivant dans head-meta.hbs insérera un lien pour les langues de page alternatives avec l’URL correcte, mais pas le titre. Toute solution à ce problème est la bienvenue !

{{#with page.versions}}
  {{#each this}}
  {{~#if (ne ./version @root.page.version)}} 1
    {{#unless ./missing }}
      <link rel="alternate" hreflang="{{./version}} {{./missing }}" href="{{{@root.site.url}}}{{{url}}}" title="{{component.version.page.title}}">
    {{/unless}}
  {{/if~}}
  {{/each}}
{{/with}}
1 Obtenir un lien pour toute langue qui n’est pas la langue de la page courante

Fonction i18n nécessaire…​

Pour les quelques problèmes ci-dessous, je crois que la meilleure solution serait d’utiliser l’une des nombreuses bibliothèques i18n afin de conserver un fichier YAML par langue avec les chaînes traduisibles. J’ai essayé d’ajouter http://i18njs.com/#multiple_languages à mon site Antora. Le paquet semble promettre de faire ce qui est nécessaire et n’est pas gonflé.

Le problème, c’est qu’il n’y a pratiquement pas une seule ligne de code qui passe elint. Et je n’ai pas encore exploré davantage. Mais quelque chose comme cela serait une solution au problème java de la « table des matières » et faciliterait aussi la traduction des chaînes des modèles Handlebars. Si quelqu’un a des idées là-dessus pour l’instant, j’aimerais beaucoup les entendre.

Voici les problèmes qu’une fonction i18n pourrait résoudre :

contenu de l’en-tête (barre d’outils)

Certaines choses, comme les éléments de menu, devront toujours être traduites. Pour l’instant, j’ai un header-content-lang.hbs pour chaque langue. Le modèle header.hbs les récupère comme suit :

{{> header-scripts}}
{{#if (eq page.version 'fr')}}
{{> header-content-fr}}
{{/if}}
{{#if (eq page.version 'en')}}
{{> header-content-en}}
{{/if}}
{{#if (eq page.version 'dyu')}}
{{> header-content-dyu}}
{{/if}}
{{#if (eq page.version undefined)}}
{{> header-content-fr}}
{{/if}}

Si cela reste dans des modèles multilingues, cela pourrait sans doute être amélioré. Mais Handlebars ne regorge pas de documentation avec exemples et tutoriels. J’ai constaté qu’il ne charge pas un modèle dynamique header-content-{{page.version}}. Je ne sais pas comment ni si cela pourrait être fait, mais ce qui précède fonctionne pour l’instant. Une fonction i18n pourrait peut-être éliminer le besoin de plusieurs modèles par langue.

éléments codés en dur

Certaines chaînes anglaises sont aussi codées en dur dans Antora à divers endroits.

  • Par exemple, l’en-tête de la table des matières dans la colonne de droite est codé en dur dans 02-on-this-page.js ligne 43 avec ( title.textContent = sidebar.dataset.title || 'Contents'). Quelqu’un ayant des compétences en JavaScript pourrait trouver un moyen d’intégrer sa propre langue dans le script. Sur ce site, à droite, c’est codé en dur en français : « Sur cette page…​ » (Les techniciens anglophones pourront apprendre le français !)

Bon, cela convient à mon blog personnel, mais pour un site multilingue sérieux, cela ne marchera pas. Aussi, mon contournement pour l’interface multilingue a été de le supprimer.

  • Un autre exemple est celui des libellés « Prev » et « Next » des liens de pagination.

    Ils sont codés en dur en CSS. C’est facile à changer, bien sûr. Je les ai supprimés car les liens sont assez explicites, et incluent déjà des chevrons gauche et droite. Les termes pourraient aussi être remplacés en CSS par de l’unicode ou des icônes. Mais si vous voulez ou devez les traduire, vous voudrez probablement mettre en place une sorte de fonction i18n dans les modèles Handlebars.

  • Il y a aussi des infobulles et des messages dans les modèles HBS qui nécessitent une traduction.

    Je n’y ai pas touché pour l’instant. Même s’il serait possible de faire toutes les traductions nécessaires dans des modèles spécifiques à chaque langue, il serait agréable d’avoir le choix d’utiliser une fonction i18n pour les récupérer dans un fichier YAML i18n.

URL

La plupart des sites web multilingues ont une structure d’URL du type https://example.com/en/docs, https://example.com/fr/posts, etc. Or l’URL d’Antora est https://example/com/component/version, ce qui est totalement normal pour une version logicielle, mais peut paraître un peu bizarre non standard pour du contenu traduit dans différentes sections d’un site. Ainsi, l’URL de cet article est : https://coastsystems.net/blog/en/blog/2022-01-04-antora/. Je dois faire avec.

Rechercher

L’extension de recherche lunr est la seule extension ajoutée ci-dessous au playbook Antora multilingue. Elle fonctionne à merveille et prend en charge de nombreuses langues majeures ! Même si votre langue n’est pas officiellement prise en charge, si elle utilise un script latin, lunr peut aussi très bien fonctionner.

Polices

C’est le plus souvent une préférence personnelle. Mais pour moi, Roboto ne contient pas les caractères latins étendus dont j’ai besoin. La substitution de police est bonne, mais pourquoi se contenter de bon quand on peut avoir une police contenant tous les caractères nécessaires ? Noto Sans semble un bien meilleur choix pour une prise en charge latine étendue et non latine. Bien sûr, les polices se changent facilement avec Antora.

Mais il y a un autre problème. Les paquets npm typeface-* ne fournissent pas (en général ?) de versions latines étendues, même lorsqu’elles existent.

C’est vraiment pratique de lancer simplement npm i typeface-votre-police-preferée-pour votre langue --save-dev, dans l’interface. Mais cela ne me fournira pas les caractères dont j’ai besoin. Encore plus si vous travaillez en vietnamien ou en tagalog.

Dans l’interface supplémentaire, cela exigera de toute façon une installation manuelle. npm @fontsource semble très à jour, et dès que Google publie une nouvelle police, elle y est disponible. Si vous avez besoin d’une police particulière, cherchez-la sur @fontsource. Suivez ensuite les instructions d’Antora pour Ajouter des polices manuellement.

ATTENTION
Attention
Vous devrez probablement renommer les fichiers font.css et copier les fichiers woff2 dans le répertoire des polices. N’oubliez pas que le chemin dans le fichier font.css pointant vers le fichier de police woff2 réel est relatif à l’emplacement de ce fichier CSS.

Ensuite, assurez-vous de définir la famille de polices dans i18n/vars.css et d’importer les fichiers CSS dans i18n/site.css.

Conclusion

Antora est la meilleure plateforme pour la documentation technique et l’écriture en AsciiDoc. Elle peut actuellement être utilisée dans un environnement multilingue avec quelques hoquets et contournements. Des sites comme Fedora docs utilisent Antora et parviennent tant bien que mal à prendre en charge un « grand nombre » de langues. (C’est aussi un site à l’apparence très simple utilitaire. Le service de design de Fedora ??? Êtes-vous là ?) Ce serait à mon avis un atout énorme pour Antora d’être facilement adaptable et utilisable d’emblée pour le monde international du matériel éducatif et plus encore. Et oui, même la documentation technique est et doit être traduite. Dans le village global, le générateur de site web doit totalement prendre en charge plusieurs langues !

Comme l’a si bien dit le Linux Journal en 2010 :
Tout comme les normes d’échange d’informations telles que XML permettent aux systèmes d’être plus interopérables, au fond, l’I18N permet aux applications d’être plus utilisables — par une base d’utilisateurs plus large et plus mondiale. Je ne dis pas que chaque script shell trivial justifie forcément l’I18N, mais comme tout logiciel commercial est potentiellement une marchandise mondiale, l’indépendance linguistique est quelque chose à prendre en compte — et à prendre en compte tôt dans le processus de conception/développement. L’absence d’une telle planification serait très court-termiste en 2010.
— Luis Icanona, le 27 septembre
2010

Espérons qu’une prise en charge complète de l’i18n et du multilingue est en route.

En attendant, si j’ai oublié quelque chose, mal compris quelque chose ou si vous avez une suggestion, faites-le-moi savoir !

NOTE
Note
À l’origine, j’avais un playbook avec tout (modèles Handlebars modifiés, CSS, etc.) dans une interface supplémentaire. Cependant, après avoir fait fonctionner gettext en grande partie, je n’ai pas pu traduire le titre « Contents », comme indiqué ci-dessus avec le JavaScript dans l’interface supplémentaire. Je ne sais pas s’il existe un moyen de le faire. Pour l’instant, le playbook contient la recherche lunr configurée pour le français et l’anglais. Toutes les autres modifications i18n sont dans le dépôt antora-ui-i18n.

Usage

  1. Assurez-vous que vos documents sont organisés par code de langue.

    Par exemple :

    docs
      en/
        antora.yml
        modules/
          ROOT/
            pages/
              index.adoc
      fr/
        antora.yml
        modules/
          ROOT/
            pages/
              index.adoc

    Dans le fichier antora.yml, le nom du composant doit être identique dans toutes les langues. La version doit être le symbole ISO de la langue, par exemple « en ». Facultativement, display_version doit être le nom de la langue, par exemple « English ».

    name: docs
    title: Docs
    version: en
    display_version: English
    start_page: index.adoc
    nav:
      - modules/ROOT/nav.adoc

    Stockez vos documents et votre configuration dans un dépôt git.

  2. Clonez l’interface i18n d’Antora.

    Au minimum, vous devrez *absolument* personnaliser header.hbs en fonction des langues que vous utiliserez. Ensuite, vous devrez ajouter les fichiers header-content-* appropriés pour chaque langue. Ces fichiers se trouvent dans le répertoire src/partials.

  3. Construisez un bundle d’interface personnalisé selon la procédure Antora habituelle décrite dans le readme.

    1. npm -i install

    2. npm -i install gulp-cli

    3. gulp bundle

  4. Clonez (ou créez le vôtre) : dépôt de démonstration du playbook.

    1. Modifiez le fichier playbook.yml et définissez la source des documents au bon emplacement.

    2. Pointez la source du bundle d’interface vers votre version personnalisée. (soit en local, soit sur un dépôt Git cloud)

  5. Lancez npm -i pour installer Antora.

  6. Lancez npm run clean-build pour construire votre site

    (Cela inclut l’interface supplémentaire lunr.) Sinon, si vous supprimez l’extension lunr, vous pouvez lancer la commande ci-dessous.

  7. Lancez npx antora playbook.yml pour construire votre site.