i18n

Cette page couvre la mécanique de traduction des chaînes d’interface — libellés de navigation, texte ARIA, texte des boutons, messages d’état. Elle ne couvre pas la rédaction de pages de contenu bilingues; cette règle éditoriale vit dans Pages bilingues.

Où vivent les chaînes#

Chaque chaîne d’interface traduisible est une clé dans i18n/en.toml et i18n/fr.toml, une table TOML par clé :

[skipToContent]
other = "Skip to content"

Le fichier français porte la même clé avec la valeur française :

[skipToContent]
other = "Aller au contenu"

Il n’y a pas de langue de repli. Une clé définie dans un fichier et absente de l’autre s’affiche comme une chaîne vide sur le site auquel elle manque — voir Les clés manquantes échouent silencieusement ci-dessous.

Nommage des clés#

Les clés sont en camelCase et décrivent le rôle de la chaîne, pas son emplacement, selon la règle générale de Conventions de nommage : mainNavigation, languageSwitcher, footerSiteInformation, dataTableScrollRegion, skipToContent. Un libellé propre à un composant est préfixé par ce composant : codeBlockScrollRegion, pas scrollRegion.

Réutilisez une clé entre gabarits seulement quand la chaîne est réellement le même concept d’interface. Ne réutilisez pas une clé simplement parce que deux chaînes se lisent pareil aujourd’hui — une clé partagée signifie qu’une future modification d’un contexte modifie silencieusement l’autre.

Appeler une clé depuis un gabarit#

<nav class="nav-strip" aria-label="{{ i18n "mainNavigation" }}">

La fonction lit automatiquement la langue de la page courante — le même appel se résout en Main navigation sur le site anglais et en Navigation principale sur le site français. Les appels fonctionnent de façon identique dans les attributs, le texte visible et les blocs JSON comme la balise app-config, qui remet ses chaînes localisées à JavaScript.

Formes plurielles#

Une clé qui varie selon un nombre définit plus d’une table — one pour le singulier, other pour le reste — et le gabarit passe le nombre en deuxième argument :

[readingTime]
one = "1 min read"
other = "%d min read"

{{ i18n "readingTime" $page.ReadingTime }}

Hugo choisit la table selon les règles de pluriel CLDR de la langue cible, pas seulement « est-ce 1 » — le français et l’anglais s’accordent par hasard au singulier/pluriel à 1, mais ne présumez pas que toutes les langues font pareil.

Les clés manquantes échouent silencieusement#

Hugo n’avertit ni n’échoue sur un appel i18n dont la clé est indéfinie dans la langue courante. La fonction retourne une chaîne vide, et le gabarit affiche ce qui l’entoure — un aria-label="", un libellé visible vide, une ligne vide dans app-config. Une compilation complète hugo --gc reste verte.

Cela s’est déjà produit une fois : cinq gabarits ont été modifiés pour appeler de nouvelles clés i18n, les clés ont été ajoutées à une note provisoire plutôt qu’à i18n/en.toml, et quatre points de repère de navigation ont été mis en ligne avec aria-label="" pendant un moment, jusqu’à ce que l’écart soit détecté en comparant l’usage dans les gabarits aux fichiers TOML, pas par la compilation.

Avant de publier une clé nouvelle ou renommée :

• ajoutez-la dans les deux fichiers i18n/en.toml et i18n/fr.toml dans le même changement
• cherchez le nom de la clé dans layouts/ pour confirmer que chaque site d’appel a une définition correspondante
• vérifiez le HTML rendu d’une page touchée, pas seulement une compilation propre — une compilation propre prouve que le gabarit a compilé, pas que la chaîne s’est résolue

Alternatives de langue#

layouts/_default/baseof.html affiche un <link rel="alternate" hreflang="…"> par entrée dans .Translations — les autres versions linguistiques de la page courante — plus une alternative auto-référentielle pour la page courante elle-même, le motif que les moteurs de recherche attendent : chaque version linguistique renvoie vers chaque version, y compris elle-même.

Le sélecteur de langue visible est un composant distinct, couvert dans Sélecteur de langue : il résout la traduction de la page courante pour chaque site par AllTranslations, et se replie sur la page d’accueil de cette langue lorsqu’aucune traduction n’existe, pour que le contrôle ne pointe jamais vers une erreur 404.

Où les chaînes d’interface sont câblées aujourd’hui#

La plupart des appels i18n vivent dans les gabarits qui les affichent directement : layouts/partials/header.html (navigation, sélecteur de langue), layouts/partials/footer.html, layouts/partials/search.html et search-modal.html, layouts/partials/docs/breadcrumbs.html, et les render hooks des blocs de code et des encadrés. Quelques clés sont regroupées dans le bloc JSON app-config de baseof.html pour qu’assets/js/site.js puisse lire des chaînes localisées sans aller-retour de gabarit — l’indicatif de recherche et les messages d’erreur fonctionnent ainsi.