UI Antora avec po4a et collector

Description de Antora i18n

Ce UI Antora est basésur le Antora Default UI, ayant le but de faciliter la création de site multilingues.

Alors qu’il suit de près autant que possible le ui par défaut, i ajoute les fonctionalité et changements suivants:

Traduit l’attribut meta lang, de l’élément html, utilisant la valeur de la version de la section (component version), ou l’attribut :page-lang: dans le document source.
Incorpore les header-content.$lang.hbs partials pour des entêtes traduits dans chaque langue.
Incorpore l’extension Antora Lunr Extension afin de permettre la recherche hors-ligne dans les langues gérées par lunr.
Ajoute le paquet node gettext.js pour traduire:
1. Tooltips dans le ui.
2. Message générique de recherche (Rechercher…)
3. Titre 'Contents' côte droite
4. lien "Edit this page"
5. Affiche le nom de la section (component) dans le menu de sélection de langue
Incorpore l’extension Antora Collector Extension qui permet à po4a de générer les documents traduits et les injecter dans le contenu du catalogue .
Incorpore Antora Assembler afin de produire un fichier pdf pour chaque section(component)/langue.
- À faire:
- Add a button to the toolbar to download pdf.

Générer ce site localement.

Dupliquer ce dépôt

git clone https://gitlab.com/antora-ui-custom/antora-i18n.git`

Générer le ui
```
pushd ui
npm i
gulp bundle
popd
```
Générer le site
```
npm i
npm run build-local
```

Personalizer

Dépôt UI

Copier le ui hors de ce répertoire et faire un git init.
Pousser vers service d’hébergement git. (CI gitlab inclue)
Modifier les fichiers header.hbs, et header-content.$lang.hbs, se trouvant dans le répertoire ui/src/partials en renommant ou traduisant selon les langues du site.
Adapter et/ou ajouter les traductions de tooltips, message etc se trouvant dans js/vendor/i18n-head.js.

Dépôt documents

Copier/créer dépôt de documents avec antora.yml modifié pour refléter vos langues.
Copier le script update_po.sh à la racine du dépôt des documents et ajuster le variable lang selon les exigences.

Dépôt de lancement playbook

Editer playbook.yml pour désigner les langues de recherche utilisé par lunr.

antora:
  extensions:
  - '@antora/collector-extension'
  - require: '@antora/lunr-extension'
    languages: [en, fr]
  - require: '@antora/pdf-extension'

Editer playbook.yml pour diriger vers le bundle ui, et dépôt de document approprié. == Critères de documents
Chaque langue doit être configurée comme une racine de dépôt

Content descriptor file

Le fichier description du contenu (antora.yml) doit indiquer la version comme un code de langue iso qui correspond a ce qui est utilsé dans le fichiers header.hbs, header-content.$lang.hbs et i18n.js.
Il faut remplacer le code de langue pour chaque langue cible se trouvant aux aux valeurs de run et scan: dir: pour l’extension collecteur. Voir <po4a> dessous.

Source language descriptor Target language descriptor

Table 1. Fichier description du contenu
Source language descriptor	Target language descriptor
`name: antora-i18n title: Multilingual Antora version: en display_version: English nav: - modules/ROOT/nav.adoc ----`	`name: antora-i18n title: Antora multilingue version: fr display_version: Français nav: modules/ROOT/nav.adoc ext: collector: run: command: "po4a --variable langs=fr po4a.cfg" scan: dir: build/fr`

name: antora-i18n title: Multilingual Antora version: en display_version: English nav:
  - modules/ROOT/nav.adoc
    ----

name: antora-i18n title: Antora multilingue version: fr display_version: Français nav:
modules/ROOT/nav.adoc
ext:
  collector:
    run:
      command: "po4a --variable langs=fr po4a.cfg"
    scan:
      dir: build/fr

Attributs de page

Les attributs de page peuvent inclure un attribut :lang: utilisé pour charger les fichiers locales spécifiques asciidoctor.
(En option) Copier https://github.com/asciidoctor/asciidoctor/tree/main/data/locale [les fichiers locales dont vous avez besoin] vers le répertoire pages/locale de la langue correspondante de votre document.
Les pages seront générées, en utilisant par défaut avec un attribut de lang sur l’élément html (<html lang="fr">) qui correspond à la langue de la version de la section (component). Par contre on peut aussi crééer un attribut de page :page-lang: dans le document pour changer le défaut. (par exemple il y a un document anglais dans la section (component version) française du site.

po4a

Po4a est très souple et on peut le configurer de plusieurs manières. En voici une façon.

Modifier le script update_po.sh et changer le variable 'langs' pour désigner toutes les langues cibles de votre site.

Après avoir lancé le script update_po, les fichiers po des langues cibles seront générés sous le répertoire l10n/po. WARNING: Ne jamais exécuter un script inconnu sans vérifier ce qu’il fait! Ce script assume que les fichiers se trouvent dans un repo git, et fait un 'commit' sur le répertoire l10n à chaque exécution.

Tous les fichiers de la langue source doivent se trouver sous le répertoire root pour cette langue. Le fichier po4a doit avoir une entrée pour chaque fichier à traduire.

Le variable 'lang' dans le fichier <content descriptor> est ajusté pour la seule langue de la version de la section ( component).
Lorsque n’importe quel changement se fait dans un document source, ou bien un nouveau document est ajouter, le script update_po.sh doit être exécuté.
Après avoir executé le script update_po.sh les fichiers po pour toutes les langues cibles seront générées sous le répertoire l10/po.
Editer le fichiers po avec votre éditeur po préféré. (Neovim/emacs, poedit gtranslator et bien d’autres.)
En générant le site avec npx antora playbook.yml, les documents traduits seront produits et injectés dans le catalogue de contenu.
Voir les options asciidoc man page pour les renseignements sur d’autres options spécifiques à asciidoc pour le fichier po4a.cfg. Quelques options utiles (utilisés dans le fichier po4a ici) sont:

entry

Indiquer les attributs dont vous voulez traduire. Probablement, lang, page-tags, keywords, description etc.

tablecells

Indique à po4a si vous voulez traduire les tables au niveau des cellules

keep

Le pourcentage du document doit être traduit pour publier.
Toutes les options peuvent être désignés au niveau global et encore pour chaque fichier individuel.
Une option générale de po4a est pot=préfix`pour les fichiers qui pourront autrement être écrasés. Ce sera le cas par exemple pour nav.adoc, ou index.adoc se trouvant dans les modules différents. Avec l’option `pot=, po4a ajoutera un préfixe aux fichiers po générés. Il pourrait être pratique d’utiliser le nom de module`pot=ROOT-nav` afin d’identifier facilement chaque fichier nav.adoc ou index.adoc.