Variables et réutilisation multi-sites

Les variables sont ce qui transforme un template en réseau. Un bon découpage en variables, et 100 sites se rendent depuis une seule source. Un mauvais, et vous recopiez du texte à la main dans chaque préréglage.

Trois sources, une seule portée fusionnée

Au rendu, la plupart des moteurs fusionnent les variables de trois origines dans une table de recherche unique. Quand le template lit %SomeName%, le résolveur parcourt cette table et substitue la valeur.

1. Aides locales au template, déclarées avec #set ou #def dans le corps du template.
2. Variables de site, définies par locataire — un enregistrement par site, partagé par tous les templates de ce site.
3. Variables d’exécution, passées au résolveur au moment de l’appel (contexte de l’article, du système, de l’utilisateur).

Les décisions d’écriture se résument à savoir quelle couche possède quel fait.

Aides locales avec #set

Utilisez #set pour des aides de courte durée à l’intérieur d’un template :

#set %Lead% = {Welcome|Greetings|Hello}
%Lead% to %brand_name%!

Bons usages :

• des aides propres à un seul template, qui encombreraient sinon le corps de répétitions ;
• de longues phrases réutilisées plusieurs fois dans le même template ;
• la lisibilité, quand l’imbrication devient assez profonde pour fatiguer l’œil.

Mauvais usages :

• les faits propres à un locataire — ils appartiennent aux variables de site ;
• tout ce que l’exécution fournit déjà — un #set local perd la bataille de priorité.

Règles de syntaxe qui font trébucher

• Les noms de variables sont insensibles à la casse.
• ASCII uniquement : lettres, chiffres, tiret bas. Pas d’espaces, pas de traits d’union.
• #set ne fonctionne qu’en début de ligne.
• Les commentaires s’écrivent /# ... #/ et sont retirés avant traitement.
• Les variables inconnues restent littérales. %MissingVar% se rend en %MissingVar%, pas en chaîne vide ni en erreur. Traitez les restes comme un défaut de recette.

Variables de site — le multiplicateur multi-sites

Les variables de site sont la raison pour laquelle un template partagé peut servir plusieurs sites sans se lire pareil sur chaque domaine.

Un préréglage de site générique ressemble à ceci :

#set %BrandTone% = {practical|no-nonsense|straightforward}
#set %Industry% = SaaS analytics
#set %TopFeatures% = [<minsize=3;maxsize=4;sep=", ";lastsep=" and ">dashboards|alerting|audit logs|SSO|role-based access]
#set %Audience% = {teams|product leads|operations}

Tout template partagé peut désormais lire %BrandTone%, %TopFeatures%, etc., et la sortie change selon le site sans que personne touche au template.

Quand créer une variable de site

Variables d’exécution

Les variables d’exécution viennent du contexte appelant : l’article rendu, l’utilisateur courant, l’horloge système. Elles l’emportent sur les variables de site et sur les aides locales de même nom.

Variables d’exécution courantes selon les moteurs (les noms dépendent de votre implémentation) :

• %year% — année courante
• %lang% — code de langue courant
• %site_domain% — hôte du site courant
• %brand_name%, %product_name% — marque/produit dont parle l’article
• %article_topic%, %category% — métadonnées au niveau de l’article

On ne les affecte jamais depuis un template. Les lire suffit.

Priorité des variables

Quand le même nom existe sur plusieurs couches, la priorité la plus haute l’emporte. Un ordre standard, du plus fort au plus faible :

1. Variables d’exécution
2. Variables de site
3. Variables système
4. #set local au template

Conséquence pratique : #set %brand_name% = Demo dans un template ne fait rien si l’exécution fournit %brand_name%. L’exécution gagne. Choisissez des noms d’aide qui ne masquent pas ceux de l’exécution.

Conventions de nommage

L’homogénéité au sein d’un préréglage compte plus qu’un style particulier. Cela dit, un défaut raisonnable :

• Variables d’exécution : en général lowercase_snake_case. Elles échappent à votre contrôle.
• Variables de site : PascalCase pour les chaînes ordinaires, PascalCaseAvecSuffixe pour les variantes grammaticales.
• Variables de liste : au pluriel (%TopFeatures%, %SupportedLanguages%).
• Aides locales : courtes et parlantes — %Lead%, %Closing%.

Variables composées

Les variables de site peuvent se référencer entre elles. Le résolveur de préréglages substitue d’abord les références inter-variables tout en laissant le spintax imbriqué à l’état brut, pour que les re-tirages ultérieurs fonctionnent encore :

#set %FoundedLine% = launched in %FoundedYear%, based in %HQ%
#set %Pitch% = {fast|lightweight|self-hosted} %ProductCategory%

Composez une fois les faits récurrents et réutilisez-les d’un template à l’autre.

Le piège du re-tirage

C’est de loin la première source de confusion pour qui débute. Si une variable contient du spintax brut, chaque occurrence retire indépendamment.

#set %Tone% = {safe|trusted}
%Tone% and %Tone%

Sortie possible :

Safe and trusted

Ne supposez pas qu’une variable #set se résout une fois puis se contente d’être répétée. S’il vous faut deux adjectifs différents, prenez deux variables.

Quand il vous faut une répétition exacte : #def

La règle ci-dessus concerne #set, qui est une macro. Sa jumelle #def a la même forme et fait l’inverse : elle résout sa valeur une fois par rendu et remet ce même résultat à chaque référence.

#def %Tone% = {safe|trusted|secure}

%Tone% and %Tone%

Les deux emplacements s’accordent maintenant toujours — « safe and safe », « trusted and trusted » — parce que le tirage a eu lieu une fois, avant que la moindre référence soit remplie. C’est toute la différence entre les deux directives ; le reste (ancrée à la ligne, une par ligne, retirée de la sortie, mêmes règles de nom) est identique.

Prenez #def quand une valeur doit rester stable dans le template : un nombre qui alimente un bloc {plural}, un nom sorti d’un emplacement de forme plurielle, ou toute phrase que vous répétez à dessein. Prenez #set quand vous voulez la variation — le cas courant dans le corps du texte.

Une réserve à énoncer clairement : #def rend une variable cohérente avec elle-même. Elle ne corrèle pas deux variables différentes — chaque #def tire pour son compte, donc %Noun% et %NounGenitive% peuvent encore tomber sur des mots différents. Quand deux valeurs doivent s’accorder entre elles, liez-les dans une seule énumération plutôt que dans deux variables.

Fragments optionnels

Une branche vide dans une énumération donne un fragment optionnel :

{|official }website
{fast|secure|} withdrawals

Mettez l’espace à l’intérieur de la branche optionnelle quand le fragment peut disparaître, sinon vous obtenez des espaces doubles ou des mots collés. Pour une liste optionnelle (une permutation qui peut être vide), enveloppez toute la permutation :

{|[<minsize=2;maxsize=3;sep=", ";lastsep=" and ">Slack|Jira|Linear]}

Le moteur ne peut pas choisir zéro élément dans une permutation. L’enveloppement est le seul moyen de rendre « aucune liste du tout » possible.

Collisions de séparateur

Un bug de rendu classique : la variable de liste contient déjà un and, et le texte alentour en ajoute un second.

%Integrations% and other tools

Si %Integrations% se résout en Slack, Jira, and Linear, le texte final donne :

Slack, Jira, and Linear and other tools

Correctifs :

• insérer une virgule : %Integrations%, and other tools ;
• restructurer : {Besides|Along with} %Integrations%, other tools... ;
• supprimer la conjonction finale et utiliser deux-points ou tiret cadratin.

Même problème avec une permutation en lastsep=" and " suivie d’un texte figé commençant par and. Prévisualisez quelques variantes avant de livrer.

Variables ou spintax en ligne

Règle empirique : extrayez en variables les phrases répétées et sensibles à la grammaire avant d’ajouter de petits emplacements de synonymes en ligne. La variable vous donne un seul endroit où corriger les erreurs. L’inline les disperse.

Erreurs fréquentes avec les variables

Checklist de conception des variables

• Chaque fait propre à un locataire vit dans une variable de site, pas dans le template partagé.
• Chaque fait propre à l’article vit dans une variable d’exécution, pas dans un #set.
• Aucun nom d’aide #set ne masque une variable d’exécution.
• Les noms de variables sont en ASCII, sans espaces ni traits d’union.
• Chaque variable répétée a été passée en revue pour l’effet de re-tirage.
• Chaque fragment optionnel gère ses espaces à l’intérieur de la branche.
• Chaque variable de liste suivie d’une conjonction a été vérifiée contre la collision de séparateur.
• Cinq échantillons résolus ne contiennent aucun %...% restant.

Prêt pour la structure ? Le guide suivant traite les permutations en pratique — là où se trouve réellement la variété.

Continuer la série